Skip to main content

TypeScript Integration

Stylable requires *.st.css stylesheets to be imported into your *.ts/*.tsx files for class names, states, variables, or keyframes to be applied to your components.

By default, TypeScript has no way of knowing what’s inside a *.st.css file, so you must define a type for it. To help ease this requirement, Stylable can generate a declaration file for each stylesheet. These files are generated using our @stylable/cli or by using it through one of our integrations.

Using create-stylable-app will generate the .d.ts files when running:

npm start

or when building the project:

npm run build
tip

All of the examples below are showing the flow of running our stc CLI. Alternatively, you can use the stylable.config.js file to have it generated for you. See further information here.

Publishing​

If you publish any *.st.css files in your package, you should also publish the .d.ts and .d.ts.map files alongside them. This practice leads to a better experience for users consuming your project.

stc --outDir="dist" --stcss --dts --dtsSourceMap

Manually generating stylesheet definition files​

Stylable provides the ability to generate type definition files (.d.ts) for any stylesheet. These serve as static typings for each export that the stylesheet provides:

  • class/var/stVar/keyframe - exposes available symbols defined within the stylesheet.
  • st/style/cssStates - exposes stylesheet utility functions typed according to states defined within stylesheet.

Generate a .d.ts next to all *.st.css files:

stc --dts

Alternatively, you can generate the .d.ts files to a custom folder, for example, st-types:

stc --srcDir="src" --outDir="st-types" --dts

Then modify your tsconfig.json to specify two rootDirs, your source files, and the generated typings (learn more about this by reading the tsconfig.json documentation):

{
  "compilerOptions": {
    "rootDirs": ["./src", "./st-types"]
  }
}

Import third-party stylesheets that does not provide .d.ts files​

You will have to declare global typings, but to keep it type safe you should update the request to match the module's stylesheets only.

For example:

/* globals.d.ts: */
declare module "my-module/*.st.css" {
  export * from "@stylable/runtime/stylesheet";

  const defaultExport: unknown;
  export default defaultExport;
}

Generating source-maps​

In addition to generating .d.ts files, you can also generate source-maps (.d.ts.map).

These source-maps will map the content of the .d.ts file back to the source stylesheet (.st.css) so that you can jump to definitions in your stylesheets straight from your TypeScript files.

stc --dts --dtsSourceMap
note

Source maps are generated by default when generating .d.ts files. If these are not wanted, the --dtsSourceMap flag should be set to false.

Development mode​

To have a good experience when working locally in dev mode, we recommend generating both the definition files and their source-maps using our watch service.

This ensures that as you are working your code, validations, completions and other language-service capabilities will remain up-to-date.

stc --dts --dtsSourceMap -w --cjs false
tip

Generating both definition and source-map files for every stylesheet in a project can clutter the project up. For this reason, we recommend adding the generated *.st.css.d.ts and *.st.css.d.ts.map files to your .gitignore file, and only include them in your published packages.

ESlint Stylable plugin vs. generated definition files​

There is an overlap of functionality between the Stylable ESlint plugin and the generated .d.ts files - both solutions validate stylesheet export usages. The .d.ts file approach is superior, howevever, as it offers better validations, completions and correctness. All it requires is that the watch service be running.

In conclusion, if you are generating definition files, you can remove the ESlint Stylable plugin and suffer no degredation in development experience.

Declaring global stylesheet typings​

If you choose not to generate .d.ts typings for each stylesheet, then it is required that you include in your project a general purpose *.st.css global declaration. This provides a broad signature of a Stylable stylesheet.

To do this, create a globals.d.ts file in your ./src directory and add the following declaration:

/* globals.d.ts: */
declare module "*.st.css" {
  export * from "@stylable/runtime/stylesheet";

  const defaultExport: unknown;
  export default defaultExport;
}