| title |
|---|
TypeScript |
Storybook provides an integrated TypeScript experience, including zero-configuration setup and built-in types for APIs, addons, and stories.
Storybook's configuration file (i.e., main.ts) is defined as an ESM module written in TypeScript, providing you with the baseline configuration to support your existing framework while enabling you stricter type-checking and autocompletion in your editor. Below is an abridged configuration file and additional information about the various configuration elements.
<CodeSnippets paths={[ 'common/storybook-main-default-setup.ts.mdx', ]} />
| Configuration element | Description |
|---|---|
stories |
The array of globs that indicates the location of your story files, relative to main.ts |
staticDirs |
Sets a list of directories of static files to be loaded by Storybook staticDirs:['../public'] |
addons |
Sets the list of addons loaded by Storybook addons: ['@storybook/addon-essentials'] |
typescript |
Configures how Storybook handles TypeScript files typescript: { check: false, checkOptions: {} } |
framework |
Configures Storybook based on a set of framework-specific settings framework: { name: '@storybook/svelte-vite', options:{} } |
core |
Configures Storybook's internal features.core: { disableTelemetry: true, } |
docs |
Configures Storybook's auto-generated documentationdocs: { autodocs: 'tag' } |
features |
Enables Storybook's additional features See table below for a list of available features features: { storyStoreV7: true } |
refs |
Configures Storybook composition refs:{ example: { title: 'ExampleStorybook', url:'https://your-url.com' } } |
logLevel |
Configures Storybook's logs in the browser terminal. Useful for debugging logLevel: 'debug' |
webpackFinal |
Customize Storybook's Webpack setup webpackFinal: async (config:any) => { return config; } |
viteFinal |
Customize Storybook's Vite setup when using the vite builder viteFinal: async (config: Vite.InlineConfig, options: Options) => { return config; } |
env |
Defines custom Storybook environment variables. env: (config) => ({...config, EXAMPLE_VAR: 'Example var' }), |
💡 See the Vite builder TypeScript documentation if using @storybook/builder-vite.
Out of the box, Storybook is built to work with a wide range of third-party libraries, enabling you to safely access and document metadata (e.g., props, inputs) from your components without any additional configuration. It relies on babel-loader for TypeScript support and optionally fork-ts-checker-webpack-plugin for type checking. Since Storybook supports multiple frameworks, it also includes a set of third-party packages to support each framework (e.g., ts-loader and ngx-template-loader for Angular, react-docgen-typescript-plugin for React). If you need to customize the default configuration for a specific use case scenario, you can extend the default configuration to suit your needs. Listed below are some examples and a table with the available options.
<CodeSnippets paths={[ 'common/storybook-main-add-ts-config.ts.mdx', ]} />
| Field | Framework | Description | Type |
|---|---|---|---|
| check | All | Optionally run fork-ts-checker-webpack-plugin | boolean |
| checkOptions | All | Options to pass to fork-ts-checker-webpack-plugin if it's enabled | See Docs |
| reactDocgen | React | Which react docgen processor to run: "react-docgen-typescript", "react-docgen", false |
string or false |
| reactDocgenTypescriptOptions | React | Options to pass to react-docgen-typescript-plugin if react-docgen-typescript is enabled. | See docs |
The above example extends the baseline configuration to remove existing props from third-party libraries. Useful if you want to document only your components. However, if you need to include them, you can do so by adjusting your configuration as follows:
<CodeSnippets paths={[ 'common/storybook-main-extend-ts-config.ts.mdx', ]} />
Storybook provides zero-config TypeScript support, allowing you to write stories using this language without additional configuration. You can use this format for improved type safety and code completion. For example, if you're testing a Button component, you could do the following in your story file:
<CodeSnippets paths={[ 'angular/button-story-baseline.ts.mdx', 'web-components/button-story-baseline.ts.mdx', 'common/button-story-baseline.ts.mdx', ]} />
The example above uses the power of TypeScript in combination with the exported generic types (Meta and StoryObj) to tell Storybook how to infer the component's metadata and the type of the component's inputs (e.g., props). This can greatly improve the developer experience by letting your IDE show you what properties are injected by Storybook.
Assuming that you're working on a project that uses TypeScript 4.9+, you can update your component stories to use the new satisfies operator to ensure stricter type checking for your component stories. For example:
<CodeSnippets paths={[ 'common/button-story-baseline-with-satisfies.ts-4-9.mdx', ]} />
Now, when you define a story or update an existing one, you'll automatically get notified that you're missing a required arg. However, you're not limited to using the satisfies operator at the component level. If you need, you can also use it at the story level. For example:
<CodeSnippets paths={[ 'common/button-story-baseline-with-satisfies-story-level.ts-4-9.mdx', ]} />
Out of the box, Storybook supports the satisfies operator for almost every framework already using TypeScript version 4.9 or higher. However, due to the constraints of the Angular and Web Components framework, you might run into issues when applying this operator for additional type safety. This is primarily due to how both frameworks are currently implemented, making it almost impossible for Storybook to determine if the component property is required. If you encounter this issue, we recommend reaching out to the maintainers using the default communication channels (e.g., Discord server, GitHub discussion).
If you're using Vue single file components and TypeScript, you can add both Volar and the TypeScript Vue Plugin for editor support, additional type safety and auto-completion. Nevertheless, if you're working with Svelte, you can add the Svelte for VSCode extension for similar benefits.