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;
}