Story loading limitations
Story loading on demand has two minor limitations: CSF formats from version 1 to version 3 are supported, and custom `storySort` functions are allowed based on a restricted API.
Storybook · Setup · all subjects
configuration
333 notes in this subject, read out of this brain and free to use. This is page 1 of 6.
Storybook configuration folder location
Storybook is configured via a folder called `.storybook`, which contains various configuration files. This folder must be in your project's root directory. You can change the folder location by setting the `-c` flag when running `storybook dev` and `storybook build` CLI commands.
Story loading with custom glob pattern
You can alter the default story loading glob using the syntax supported by picomatch. For example, to pull both `.md` and `.js` files from a specific directory, you can customize the `stories` configuration in your `main.js|ts` file.
Story file loading default pattern
By default, Storybook will load stories from your project based on a glob pattern in `.storybook/main.js|ts` that matches all files with extension `.stories.*`. The intention is to colocate a story file along with the component it documents.
main.js|ts configuration file purpose
The `main.js|ts` file defines your Storybook project's behavior, including the location of your stories, the addons you use, feature flags and other project-specific settings. This file should be in the `.storybook` folder. You can author it in either JavaScript or TypeScript. This configuration file is a preset with a powerful interface that can be customized.
Story loading with custom implementation
You can adjust your Storybook configuration and implement custom logic to load your stories. This allows you to handle particular patterns that conventional story loading methods cannot solve.
preview.js file purpose
To control the way stories are rendered and add global decorators and parameters, create a `.storybook/preview.js` file. This file is loaded in the Canvas UI, the preview iframe that renders your components in isolation. Use `preview.js` for global code such as CSS imports or JavaScript mocks that apply to all stories.
main.js|ts configuration options table
| Configuration element | Description | | --- | --- | | `stories` | The array of globs that indicates the location of your story files, relative to `main.js` | | `staticDirs` | Sets a list of directories of static files to be loaded by Storybook. Example: `staticDirs: ['../public']` | | `addons` | Sets the list of addons loaded by Storybook. Example: `addons: ['@storybook/addon-docs']` | | `typescript` | Configures how Storybook handles TypeScript files. Example: `typescript: { check: false, checkOptions: {} }` | | `framework` | Configures Storybook based on framework-specific settings. Example: `framework: { name: '@storybook/svelte-vite', options:{} }` | | `core` | Configures Storybook's internal features. Example: `core: { disableTelemetry: true, }` | | `docs` | Configures Storybook's auto-generated documentation. Example: `docs: { defaultName: 'Documentation' }` | | `features` | Enables Storybook's additional features. See separate documentation for available features. | | `refs` | Configures Storybook composition. Example: `refs: { example: { title: 'ExampleStorybook', url:'https://your-url.com' } }` | | `logLevel` | Configures Storybook's logs in the browser terminal. Example: `logLevel: 'debug'` | | `webpackFinal` | Customize Storybook's Webpack setup. Example: `webpackFinal: async (config:any) => { return config; }` | | `viteFinal` | Customize Storybook's Vite setup when using the vite builder. Example: `viteFinal: async (config: Vite.InlineConfig, options: Options) => { return config; }` | | `env` | Defines custom Storybook environment variables. Example: `env: (config) => ({...config, EXAMPLE_VAR: 'Example var' }),` | | `build` | Optimizes Storybook's production build for performance by excluding specific features from the bundle. Example: `build: { test: {} }` |
Story loading with directory
You can simplify your Storybook configuration by loading stories using a directory path. For example, to load all stories inside a `packages/MyStories` directory, you can adjust the `stories` configuration to reference that directory.
preview.js exportable keys
The `preview.js` file can be an ES module and export the following keys: `decorators` (an array of global decorators), `parameters` (an object of global parameters), and `globalTypes` (definition of global types for the toolbar annotation).
Story loading configuration with object
You can customize your Storybook configuration to load stories based on a configuration object. For example, if you wanted to load stories from a `packages/components` directory, you could adjust your `stories` configuration field into an object configuration. When Storybook starts, it will look for any file containing the `stories` extension inside that directory and automatically generate the titles for your stories.
manager.js file purpose
To control the behavior of Storybook's UI (the 'manager'), create a `.storybook/manager.js` file. This file does not have a specific API but is the place to set UI options and to configure Storybook's theme.
Feature support table for core frameworks
Core frameworks (React, Vue 3, Angular, Web Components) feature support: Essentials: Actions (✅), Backgrounds (✅), Controls (✅), Interactions (✅), Measure (✅), Outline (✅), Viewport (✅) Addons: A11y (✅), Docs (✅), Test runner (✅), Test coverage (✅), CSS resources (✅), Design assets (✅), Events (✅), Google analytics (✅), GraphQL (React, Angular only), Jest (✅), Links (✅), Queryparams (✅) Docs: CSF Stories (✅), Autodocs (✅), Doc Blocks - ArgTypes (✅), Canvas (✅), ColorPalette (✅), Controls (✅), Description (✅), IconGallery (✅), Markdown (✅), Meta (✅), Primary (✅), Source (✅), Story (✅), Stories (✅), Subtitle (✅), Title (✅), Typeset (✅), Unstyled (✅), UseOf (✅), Inline stories (✅)
Core frameworks with dedicated maintainers
Core frameworks have dedicated maintainers or contributors responsible for maintaining the integration. React, Vue 3, Angular, and Web Components are core frameworks. Most Storybook features are supported in these frameworks.
Feature support table for community frameworks
Community frameworks (Ember, HTML, Svelte, Preact, Qwik, SolidJS) feature support: Essentials: Actions (✅ all), Backgrounds (✅ all), Controls (✅ all), Interactions (HTML, Svelte, Preact, Qwik, SolidJS only; not Ember), Measure (✅ all), Outline (✅ all), Viewport (✅ all) Addons: A11y (✅ all), Docs (✅ all), Test runner (HTML, Svelte, Preact, Qwik, SolidJS only; not Ember), Test coverage (HTML, Svelte, Preact, Qwik, SolidJS only; not Ember), CSS resources (✅ all), Design assets (✅ all), Events (✅ all), Google analytics (✅ all), GraphQL (not supported in any), Jest (✅ all), Links (✅ all), Queryparams (✅ all) Docs: CSF Stories (✅ all), Autodocs (HTML, Svelte, Preact, Qwik, SolidJS only; not Ember), Doc Blocks - ArgTypes (✅ all), Canvas (✅ all), ColorPalette (✅ all), Controls (✅ all), Description (✅ all), IconGallery (✅ all), Markdown (✅ all), Meta (✅ all), Primary (✅ all), Source (✅ all), Story (✅ all), Stories (✅ all), Subtitle (✅ all), Title (✅ all), Typeset (✅ all), Unstyled (✅ all), UseOf (✅ all), Inline stories (HTML, Svelte only)
Community frameworks have fewer contributors
Community frameworks (Ember, HTML, Svelte, Preact, Qwik, SolidJS) have fewer contributors and may not be as up to date as core frameworks. If you use one of these frameworks for your job, consider contributing to its Storybook integration.
Framework configuration options for NextJS
NextJS framework supports the following configuration options: nextConfigPath sets the default path for the NextJS configuration file (e.g., framework: { name: '@storybook/nextjs', options: { nextConfigPath: '../next.config.js'} }); builder configures Webpack 5 builder options (e.g., core: { builder: { name:'webpack5', options: { lazyCompilation: true} }}).
Storybook framework auto-detection and configuration
When you install Storybook into an existing project, it automatically detects the framework being used and configures Storybook to work with it. This process includes adding necessary libraries as dependencies, adjusting configuration, and automatically loading the framework configuration before any addons when Storybook starts.
Frameworks with custom configurations may require addons
Some frameworks like CRACO provide their own configuration that Storybook is not prepared to handle without additional steps. These cases may require either via addon or integration solutions. Read the addons guide for more information.
Supported frameworks by builder
Storybook supports frameworks organized by their builders: Webpack builder supports React, Angular, Vue 3, Web Components, NextJS, HTML, Ember, Preact, and Svelte. Vite builder supports React, Vue 3, Web Components, HTML, Svelte, SvelteKit, Qwik, and Solid.
Framework configuration options for React
React framework supports the following configuration options: strictMode enables React's strict mode (e.g., framework: { name: '@storybook/react-webpack5', options: { strictMode: false } }); legacyRootApi requires React 18 and toggles support for React's legacy root API (e.g., framework: { name: '@storybook/react-webpack5', options: { legacyRootApi: true } }).
Legacy framework support deprecation
Support for several frameworks is being deprecated, including Aurelia, Marionette, Mithril, Rax, and Riot. These frameworks have been moved to the Storybook End-of-Life repository. Community contributions are welcome to maintain these frameworks.
Framework configuration in main.js or main.ts
Framework configuration is provided in the Storybook configuration file at ./storybook/main.js|ts|cjs. This file can be extended with additional options to customize the framework setup beyond the default out-of-the-box configuration.
NextJS 13 breaking changes not fully supported by Storybook
NextJS version 13 introduced breaking changes including TurboPack and Server Components that are not yet fully supported by Storybook. You can still use Storybook with a NextJS 13 project if you are not relying on these features, but the Storybook team is working on adding support.
Framework configuration options for Angular
Angular framework supports the following configuration options: enableIvy is enabled by default with Angular 9+ and replaces the default compiler with the Ivy compiler (e.g., framework: { name: '@storybook/angular', options: { enableIvy: true } }); enableNgcc is enabled by default with Angular 9+ and adds support for ngcc for backwards compatibility (e.g., framework: { name: '@storybook/angular', options: { enableNgcc: false } }).
Global story layout in preview.js
Story layout can be configured globally by adding the layout parameter to ./storybook/preview.js. This will apply the layout setting to all stories in the UI.
Layout parameter options for Canvas positioning
The layout parameter accepts three options: 'centered' (centers the component horizontally and vertically in the Canvas), 'fullscreen' (allows the component to expand to the full width and height of the Canvas), and 'padded' (the default, adds extra padding around the component).
Layout parameter configuration locations
The layout parameter can be configured at three levels: globally in ./storybook/preview.js, at the component level, or at the individual story level.
Preview file builds inside iframe canvas
Stories render in a preview iframe (also called the Canvas) inside the larger Storybook web application. The JavaScript build configuration of the preview is controlled by a builder config.
Preview file location and execution
The preview file is located at `.storybook/preview.ts` or `.storybook/preview.tsx`. Code executed in this file runs for every story in your Storybook.
Preview file use cases
The preview file is useful for setting up global styles, initializing libraries, or anything else required to render your components.
Vue single file component editor support for TypeScript
For Vue projects using single file components with TypeScript, add the official Vue extension (available at https://marketplace.visualstudio.com/items?itemName=Vue.volar) for editor support, additional type safety, and auto-completion.
Svelte TypeScript editor support
For Svelte projects using TypeScript, add the Svelte for VSCode extension (available at https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) for editor support, type safety, and auto-completion.
React external package types not generated solution
If Storybook doesn't generate required types for third-party packages in a React project, adjust the reactDocgen configuration option to use react-docgen-typescript instead and include required options in the Storybook configuration file.
TypeScript satisfies operator support in Storybook
Storybook supports the satisfies operator introduced in TypeScript 4.9+ for stricter type checking in component stories. This can be used at both the component level and story level to ensure required args are defined. However, Angular and Web Components frameworks have constraints that may prevent the satisfies operator from working as expected due to framework implementation limitations.
TypeScript configuration options for React framework
For React projects, the available TypeScript options are: check (Available for Webpack-based projects, enables type checking within Storybook with syntax `typescript: { check: true }`); checkOptions (Requires check option enabled, configures the fork-ts-checker-webpack-plugin with syntax `typescript: { checkOptions: {} }`); reactDocgen (Configures the TypeScript parser used by Storybook with available options: react-docgen (default), react-docgen-typescript, false; example: `typescript: { reactDocgen: 'react-docgen' }`); reactDocgenTypescriptOptions (Requires reactDocgen option set to react-docgen-typescript, configures the react-docgen-typescript-plugin per builder with syntax `typescript: { reactDocgen: 'react-docgen-typescript', reactDocgenTypescriptOptions: {} }`); skipCompiler (Disables parsing TypeScript files through the compiler with syntax `typescript: { skipCompiler: false }`).
TypeScript configuration options for non-React frameworks
For Angular, Vue, Web Components, Ember, HTML, Svelte, Preact, Qwik, and Solid frameworks, the available TypeScript options are: check (Available for Webpack-based projects, enables type checking within Storybook with syntax `typescript: { check: true }`); checkOptions (Requires check option enabled, configures the fork-ts-checker-webpack-plugin with syntax `typescript: { checkOptions: {} }`); skipCompiler (Disables parsing TypeScript files through the compiler with syntax `typescript: { skipCompiler: false }`).
Storybook configuration file uses TypeScript ESM format
Storybook's main configuration file is named main.ts and is defined as an ESM module written in TypeScript. This provides baseline configuration to support your framework with stricter type-checking and autocompletion in your editor.
TypeScript satisfies operator issues in Angular and Web Components
The satisfies operator may not work as expected in Angular and Web Components frameworks due to framework constraints. These frameworks make it difficult for Storybook to determine if a component property is required. If you encounter this issue, open a support request on GitHub Discussions.
React component types not generated for enums and forwardRef
In React projects, type inference using react-docgen may not work correctly for some patterns like TypeScript Enums and React's forwardRef. This is due to how the react-docgen package is implemented. To solve this issue, update the typescript configuration option in your Storybook configuration file to use react-docgen-typescript instead.
Workspace package inherited args missing in monorepo
When using react-docgen-typescript in a monorepo with npm/yarn/pnpm workspaces, components imported from workspace packages may be missing inherited args (like MUI's ButtonProps). This occurs because the Vite plugin creates a TypeScript program from files matching its include glob (default: **/**.tsx), which only resolves from the Storybook project's directory. Workspace package files outside that directory aren't included. To fix this, add workspace package source files to the include option in the reactDocgenTypescriptOptions configuration. For example, adjust the path (like ../../packages/ui/src/**/*.tsx) to match your monorepo layout. Note that tsconfigPath only affects compiler options used, not which files are included in the TypeScript program.
Storybook provides zero-config TypeScript support
Storybook provides zero-configuration TypeScript support for writing stories, allowing you to write stories in TypeScript without additional configuration. You can use exported generic types like Meta and StoryObj for improved type safety and code completion.
What telemetry collects
Storybook telemetry collects: timestamp of occurrence, command invoked (init, upgrade, dev, build), Storybook unique identifier (one-way hash), one-way hash of IP address, story count, Storybook version, language (TypeScript/JavaScript), supported view layers (React, Vue 3, Angular, Svelte), builder (Webpack5, Vite), meta framework (Next, Gatsby, CRA), addons, testing tools (Jest, Vitest, Playwright), package manager info (npm, yarn), monorepo info (NX, Turborepo), and in-app events.
Enable crash reports via command line flag
Use the `--enable-crash-reports` flag when running Storybook commands to enable crash reporting.
Enable crash reports via enableCrashReports config
Set the `enableCrashReports` configuration element to `true` in your Storybook configuration to enable sharing of crash reports. Storybook will sanitize the error object by removing all user paths before appending it to the telemetry event.
Boot event sent before configuration evaluation
A `boot` telemetry event containing no metadata is sent prior to evaluating the Storybook configuration file (main.js|ts). This event is unaffected by the `disableTelemetry` configuration option. To prevent the boot event from being sent, use the `STORYBOOK_DISABLE_TELEMETRY` environment variable.
Telemetry opt-out via command line flag
You can opt out of telemetry by using the `--disable-telemetry` flag when running Storybook commands.
Telemetry opt-out via disableTelemetry config
Set the `disableTelemetry` configuration element to `true` in your Storybook configuration file to opt out of telemetry data collection.
Monorepo workspace sibling packages not tracked: built output missing
In a monorepo, workspace packages typically point their `exports` or `main` fields to compiled output (e.g., `./dist/index.js`, `./esm/index.mjs`) that doesn't exist until the package is built. Storybook's resolver finds the symlink in `node_modules` but cannot resolve the entry file, so it treats the import as untrackable. Even when the package has been built, its output directories are usually `.gitignore`d, meaning the resolved files are outside the set of watched source files and changes would never trigger a story reload.
Disable change detection in configuration
Change detection is enabled by default. To disable it, set `features.changeDetection` to `false` in your Storybook configuration file (main config).
Granular filtering of change detection statuses
For more granular control of change detection statuses (for example, to view only new stories), open the filter menu next to the search bar and check or uncheck the individual statuses.
Change detection filters are off by default
Change detection filters are off by default to avoid overwhelming users with false positives. The heuristics used to determine modified and related stories are designed to be fast and work without configuration, but they can produce false positives. For example, changing a widely used utility function might mark dozens of stories as related even if the change doesn't actually affect them.
Review button for change detection
A Review button appears between the search bar and the story tree whenever you have at least one new or modified story. The button toggles both the new and modified filters together with one click.
Change detection status icons in sidebar
When a change is detected, Storybook shows one of three status icons next to relevant stories in the sidebar: (1) Sparkle (✦) means the story file is untracked or newly added in git; (2) Filled circle (●) means the story's own file or a file it directly imports was changed; (3) No icon means a file further up the story's dependency chain was changed (a transitive dependency). When multiple statuses apply to the same story, priority order is: new > modified > related.
Change detection requirements
Change detection requires two things to work: a Git repository (Storybook uses `git diff` to detect changed files), and a supported builder. Both Vite and webpack5 builders are supported. Other builders can gain support by implementing a change-detection adapter.
Change detection is development-only feature
Change detection is a development-only feature. It is active when running `storybook dev` and is not available in static builds (`storybook build`).
Monorepo workspace sibling packages not tracked: tsconfig blocking
In a monorepo, per-package `tsconfig.json` files that don't extend the root configuration can block root-level path mappings. If a package has its own `tsconfig.json`, Storybook's resolver finds that file first during directory walk-up and never sees the root-level path mappings, causing workspace dependencies to not be tracked.
Troubleshooting change detection: check logs and requirements
If status icons don't appear in the sidebar, check the dev server terminal log for messages prefixed with 'Change detection:' which surface startup errors, unsupported builder warnings, and parse failures. Also verify: you are running `storybook dev` against a supported builder (Vite or webpack5), your project is inside a git repository, and `features.changeDetection` is not set to `false` in your Storybook configuration.
Monorepo fix: add paths to root tsconfig.json
To ensure cross-workspace dependencies are tracked correctly in a monorepo, add `paths` entries to your root `tsconfig.json` pointing to the source directories of your workspace packages. Example: set `"@myorg/*": ["./packages/@myorg/*/src"]` in `compilerOptions.paths`. Storybook uses these mappings as a fallback when per-file resolution does not find the module.
Barrel-aware change detection resolution
Storybook performs barrel-aware named import resolution: when a story does `import { Button } from '@myorg/ui'`, Storybook traces through the barrel to find the actual source file (`Button.tsx`) and tracks that file instead of the barrel itself. This means a change to one component only marks stories that actually import that component as related, not every story importing from the barrel.