TypeScript

Whenever a TypeScript file imports a Stylable stylesheet, you must provide a type for it. This is because TypeScript has no way of knowing what's inside Stylable *.st.css files.

Import example

import { classes } from './button.st.css'; // requires typings

Generating types per stylesheet

Stylable can generate a declaration file for each stylesheet. This approach has the advantage of providing exact typing information for each individual stylesheet runtime API.

Generated files

Stylable generates two kinds of type-related files:

• *.d.ts provides typing for the stylesheet runtime API.
• *.d.ts.map provides mapping from the generated .d.ts file to the original .st.css stylesheet. This allows jumping to definitions in the original source straight from the TypeScript file.

Type definitions that are generated adjacent to the stylesheet are automatically detected and used by TypeScript. This can cause bloat in the project source files, however. To prevent clutter in your project, we recommend that you generate all stylesheet typings to a single directory.

/* type files grouped in st-types folder */
 ├── src
 |  ├── button.st.css           - source stylesheet
 |  └── button.tsx              - component file
 |
 └── st-types
    ├── button.st.css.d.ts      - type definition
    └── button.st.css.d.ts.map  - type definition source-map

You'll then need to configure TypeScript to use that directory. To do this, 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) like this:

tsconfig.json

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

tip

We recommend adding the generated *.st.css.d.ts and *.st.css.d.ts.map files to your .gitignore file, and to only include them in your published packages.

Using the CLI

To generate type definition files to the st-types directory using the stc CLI, provide it with the --srcDir, --outDir and --dts flags:

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

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

tip

Use stylable.config.js as a central location to share common Stylable configurations across tools and integrations.

Using a bundler

For projects that are already using one of our bundler integrations (webpack or rollup), you can configure the Stylable plugin to auto-generate types per stylesheet. This means that as you are working in your normal development flows, types will be updated in the background, and be available in your IDE.

This functionality is dependant on a stylable.config.js file that includes configuration for generating .d.ts files.

stylable.config.js

//@ts-check
const { typedConfiguration } = require('@stylable/cli');

exports.stcConfig = typedConfiguration({
  options: {
    srcDir: './src',
    outDir: './st-types',
    dts: true,
  },
});

To activate this functionality in the bundler, configure the Stylable plugin with { stcConfig: true }.

// create a webpack plugin instance
new StylableWebpackPlugin({ stcConfig: true });

// create a rollup plugin instance
stylableRollupPlugin({ stcConfig: true });

Global definition

If you choose not to generate .d.ts typings for each stylesheet, you'll have to 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;
}

Typing 3rd-party stylesheets

If your project generates .d.ts typings for each stylesheet but you're consuming a package that published .st.css files without typings, you will have to declare global typings for that specific package.

globals.d.ts

declare module 'third-party-package/*.st.css' {
  export * from '@stylable/runtime/stylesheet';

  const defaultExport: unknown;
  export default defaultExport;
}

Publishing

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

stc --srcDir="src" --outDir="dist" --stcss --dts