Change detection feature preview status
Change detection is currently in preview. The experience may change in future releases. Feedback and contributions are welcome to help improve this feature.
Storybook · Setup · all subjects
configuration
333 notes in this subject, read out of this brain and free to use. This is page 2 of 6.
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.
Supported barrel patterns for change detection
Storybook resolves these barrel patterns to the underlying source file: (1) Direct named re-exports: `export { Button } from './Button'`; (2) Wildcard re-exports: `export * from './Button'`.
Debug change detection dependency graph
Set the `STORYBOOK_CHANGE_DETECTION_DEBUG` environment variable to dump a JSON snapshot of the dependency graph when Storybook starts. Use `STORYBOOK_CHANGE_DETECTION_DEBUG=1` to write `storybook-graph-debug.json` in the project root, or `STORYBOOK_CHANGE_DETECTION_DEBUG=/path/to/output.json` to write to a specified path. The snapshot includes: all story-to-dependency edges tracked at startup, the reverse index showing which stories depend on each dependency file (with BFS depth), and a barrel resolution trace showing which named imports were resolved to which source files.
Import directly from component source to improve change detection
If your barrel uses unsupported patterns or you need the most precise tracking possible, import components directly from their source paths. For example, instead of `import { Button } from '@myorg/ui'`, use `import { Button } from '@myorg/ui/Button'`. Whether this is practical depends on the library and whether it publishes deep-import paths.
How change detection works
When running `storybook dev`, Storybook builds its own dependency graph by parsing each story file and its imports with oxc and resolves module specifiers through the builder's resolve config. The builder ships a small change-detection adapter that forwards file-system events into Storybook so the graph stays current. A git diff provider watches the working tree for changes and runs `git diff` to identify modified or new files. Storybook then traces each changed file through the dependency graph to find all story files that depend on it — directly or transitively. Stories with the shortest import distance are marked modified; those at greater distance are marked related. New untracked files are marked new.
URL parameters for UI configuration
Storybook UI features can be configured via URL query parameters: enableShortcuts → shortcuts query param accepts 'false'. fullscreen → full query param accepts 'true' or 'false'. show sidebar → nav query param accepts 'true' or 'false'. show panel → panel query param accepts 'false', 'right', or 'bottom'. selectedPanel → addonPanel query param accepts any panel ID. showTabs → tabs query param accepts 'true'. instrumentation → instrument query param accepts 'false' or 'true'. change detection statuses → statuses query param accepts semicolon-separated status values: 'new', 'modified', 'related' (prefix with '!' to exclude).
Pitfall: hiding sidebar and panel may break navigation
The showSidebar and showToolbar functions let you hide parts of the UI that are essential to Storybook's functionality. If misused, they can make navigation impossible. When hiding the sidebar, ensure the displayed page provides an alternative means of navigation.
showToolbar function parameters and context
The showToolbar function for toolbar customization receives the following parameters: path (String): Path to the page being displayed. Example: '/story/components-button--default'. viewMode (String): Whether the current page is a story or docs. Values: 'docs' or 'story'. singleStory (Boolean): Whether the current page is the only story for a component. Example: true or false. storyId (String): The id of the current story or docs page. Example: 'blocks-unstyled--docs'. index (Object): The index containing statically analysed metadata for every story. Example: { 'blocks-unstyled--docs': { tags: ['autodocs'] } }. layout (Object): The current layout state with properties: isFullscreen (Boolean), panelPosition (String: 'bottom' or 'right'), showNav (Boolean), showPanel (Boolean), showToolbar (Boolean). The function must return a boolean value to show or hide the toolbar.
showPanel function parameters and context
The showPanel function for addon panel customization receives the following parameters: path (String): Path to the page being displayed. Example: '/story/components-button--default'. viewMode (String): Whether the current page is a story or docs. Values: 'docs' or 'story'. singleStory (Boolean): Whether the current page is the only story for a component. Example: true or false. storyId (String): The id of the current story or docs page. Example: 'blocks-unstyled--docs'. index (Object): The index containing statically analysed metadata for every story. Example: { 'blocks-unstyled--docs': { tags: ['autodocs'] } }. layout (Object): The current layout state with properties: isFullscreen (Boolean), panelPosition (String: 'bottom' or 'right'), showNav (Boolean), showPanel (Boolean), showToolbar (Boolean). The function must return a boolean value to show or hide the addon panel.
showSidebar function parameters and context
The showSidebar function in layoutCustomisations receives the following parameters: path (String): Path to the page being displayed. Example: '/story/components-button--default'. viewMode (String): Whether the current page is a story or docs. Values: 'docs' or 'story'. singleStory (Boolean): Whether the current page is the only story for a component. Example: true or false. storyId (String): The id of the current story or docs page. Example: 'blocks-unstyled--docs'. index (Object): The index containing statically analysed metadata for every story. Example: { 'blocks-unstyled--docs': { tags: ['autodocs'] } }. layout (Object): The current layout state with properties: isFullscreen (Boolean), panelPosition (String: 'bottom' or 'right'), showNav (Boolean), showPanel (Boolean), showToolbar (Boolean). The function must return a boolean value to show or hide the sidebar.
layoutCustomisations configuration options
The layoutCustomisations namespace in addons.setConfig accepts the following options: showSidebar (Function): Toggle visibility for the sidebar. Example: ({ storyId }, defaultValue) => storyId === 'landing' ? false : defaultValue. showToolbar (Function): Toggle visibility for the toolbar. Example: ({ viewMode }, defaultValue) => viewMode === 'docs' ? false : defaultValue.
Toolbar configuration options
The toolbar namespace in addons.setConfig accepts toolbar item visibility control: [id] (String): Toggle visibility for a specific toolbar item using the addon ID (e.g., 'title', 'zoom'). Example: { hidden: false }.
Sidebar configuration options
The sidebar namespace in addons.setConfig accepts the following options: showRoots (Boolean): Display the top-level nodes as a 'root' in the sidebar. Example: false. collapsedRoots (Array): Set of root node IDs to visually collapse by default. Example: ['misc', 'other']. renderLabel (Function): Create a custom label for tree nodes; must return a ReactNode. Example: (item, api) => <abbr title="...">{item.name}</abbr>.
addons.setConfig layout options in manager.js
The addons.setConfig API in .storybook/manager.js controls Storybook UI layout. The configuration object accepts the following properties: navSize (Number, pixels): The size of the sidebar that shows a list of stories. Example: 300. bottomPanelHeight (Number, pixels): The size of the addon panel when in the bottom position. Example: 200. rightPanelWidth (Number, pixels): The size of the addon panel when in the right position. Example: 200. panelPosition (String): Where to show the addon panel. Accepts 'bottom' or 'right'. enableShortcuts (Boolean): Enable or disable shortcuts. Example: true. showToolbar (Boolean): Show or hide the toolbar. Example: true. theme (Object): Storybook Theme object. Default: undefined. selectedPanel (String): ID to select an addon panel. Example: 'storybook/actions/panel'. initialActive (String): Select the default active tab on Mobile. Accepts 'sidebar', 'canvas', or 'addons'. layoutCustomisations (Object): Layout customisation options with showSidebar and showToolbar functions. sidebar (Object): Sidebar options including showRoots and collapsedRoots. toolbar (Object): Modify toolbar items using addon IDs. Example: { fullscreen: { hidden: false } }.
Revert to start case title formatting with renderLabel configuration
If you need the previous behavior where auto-generated titles used Lodash startCase formatting, add the `renderLabel` configuration in `./storybook/manager.js` to restore this pattern.
Story Indexers define story file naming and title generation rules
Story Indexers are heuristics that crawl the filesystem based on glob patterns to find story files and generate the sidebar index. The default indexer searches for files matching `*.stories.@(js|jsx|mjs|ts|tsx)`. Custom indexers can support different naming conventions and customize automatic title generation beyond simple prefixes.
Auto-titles automatically apply titlePrefix configuration
When using CSF 3.0 auto-titles with a configuration object that includes a `titlePrefix` property, Storybook automatically prefixes all matching story titles with the specified prefix value.
Auto-titles remove redundant filenames
Starting with Storybook 6.5, auto-generated titles omit redundant names when the filename matches the directory name or is named `index.stories.js|ts`. For example, `components/MyComponent/MyComponent.stories.js` now generates the title `Components/MyComponent` instead of `Components/MyComponent/MyComponent`. To preserve the old naming, explicitly add a `title` element in the CSF meta export.
Auto-title filename casing is preserved in Storybook 6.5+
Starting with Storybook 6.5, auto-generated story titles preserve the case of the filename instead of converting it to start case. For example, a file named `MyComponent.stories.js` will generate the title `MyComponent` instead of `Mycomponent`.
CSF 3.0 auto-titles infer story titles from file location
When using CSF 3.0 format, you can omit the `title` element from the meta export and let Storybook automatically infer titles based on the file's physical location relative to the configured story directory. For example, a story at `src/components/MyComponent.stories.js` will have the title `components/MyComponent`.
Manually set story ID to preserve permalinks during refactoring
You can manually set a story's `id` property to maintain a permalink when renaming or moving stories. This prevents existing links from breaking. When an `id` is provided, it takes priority over the title for ID generation.
Story IDs are automatically generated from title and story name
Storybook automatically generates a story `id` based on the component title and story name, which is used to construct the URL. For example, a story with title `Foo Bar` and story name `Baz` will have the id `foo-bar--baz` and URL `?path=/story/foo-bar--baz`.
Disable root sections using sidebar.showRoots
To display top-level nodes as folders instead of roots, set `sidebar.showRoots` to `false` in the `./storybook/manager.js` configuration file.
Top-level nodes display as roots by default
By default, Storybook treats top-level nodes in the sidebar as roots, which are displayed as sections of the hierarchy. Lower-level groups appear as folders.
Sidebar can display status icons for story changes
Storybook can show status icons in the sidebar to highlight new and modified stories using the change detection feature.
Mirror component filesystem paths in story titles
Use a nesting scheme in story titles that reflects the actual filesystem structure of your components. For example, if a component is located at `components/modals/Alert.js`, the CSF file should be named `components/modals/Alert.stories.js` and titled `Components/Modals/Alert`.
Use forward slashes in story titles to create sidebar groups
Add forward slash separators to the `title` field in CSF files to group stories hierarchically in the sidebar. Storybook automatically groups stories by common prefixes. For example, a story with title `Components/Modals/Alert` creates a nested group structure.
Storybook learning path after basics
After learning the basics of Storybook, next steps include learning workflows for building app UIs through in-depth guides on the tutorials page, writing stories, documenting components and design systems, and viewing example Storybooks from leading companies like GitHub, Airbnb, and Stripe.
Toolbar customization with globals and addons
The toolbar is customizable. You can use globals to quickly toggle themes and languages, or install Storybook toolbar addons from the community to enable advanced workflows.
Component discovery workflow in Storybook
The typical workflow for finding and reusing components from Storybook is: use the sidebar to find a suitable component, review its stories to pick a variant that suits your needs, and copy/paste the story definition into your app code and wire it up to data. The story definition can be accessed from the stories file or from the published Storybook using the Docs addon.
Toolbar tools for component inspection
The Storybook toolbar contains the following built-in tools: Zoom for visually scaling the component, Background for changing the rendered background, Grid for verifying component alignment, Measure for inspecting component dimensions, Outline for displaying the component's bounding box, and Viewport for rendering the component in various dimensions and orientations to check responsiveness.
Keyboard navigation with F6 and Shift+F6
Storybook supports fast keyboard navigation between landmark regions using F6 and Shift+F6 to navigate between the sidebar, toolbar, preview, and addons panel.
Sidebar contains search, explorer, and testing widget
The Storybook sidebar has three main areas: sidebar search for finding stories by name, story explorer for navigating between stories by clicking, and a testing widget at the bottom for running component tests for all stories.
Stories file naming convention
Story files must be named with the pattern *.stories.js, *.stories.ts, or *.stories.svelte. Each stories file defines all stories for a component.
Compodoc built into @storybook/angular
Compodoc is now built into the @storybook/angular framework, so it does not need to be called explicitly or run as a separate npm script. When migrating from older Storybook versions, remove explicit compodoc script entries from package.json.
Angular framework options for Storybook
The Angular framework accepts an options object with a 'builder' property of type Record<string, any>. The builder property configures options for the framework's builder. For the Webpack version, available options are found in the Webpack builder documentation.
Multiple projects in Angular workspace with Storybook
For multiple projects in an Angular workspace, each project should have a dedicated .storybook folder at its project root. Configure storybook and build-storybook entries separately in angular.json for each project, and update package.json scripts for each project. Run 'npx storybook@latest init' sequentially for each project to automatically set up configuration. Multiple Storybooks can be combined using Storybook composition.
Migrate Angular project to Storybook builder
To migrate to the Angular Storybook builder: (1) Run 'npx storybook@latest automigrate' for automatic detection and fixing, or manually adjust configuration. (2) For single projects, add storybook and build-storybook entries in angular.json architect section. (3) Update package.json scripts to use 'ng run <project-name>:storybook' and 'ng run <project-name>:build-storybook' instead of direct Storybook commands. (4) Note that compodoc is now built into @storybook/angular, so remove explicit compodoc script calls from package.json.
applicationConfig decorator for Angular providers
Use the applicationConfig decorator to apply application-wide providers to all stories when components rely on modules like BrowserAnimationsModule or other modules using the forRoot pattern. This provides components with the bootstrapApplication function used in Storybook.
moduleMetadata decorator for Angular dependencies
Use the moduleMetadata decorator to supply Angular directives and module dependencies to components in Storybook stories. Apply it at the component level (in Meta) to apply to all stories, or at the individual story level for story-specific dependencies. The decorator accepts imports (for ngModules or standalone components), declarations (for components used in templates), and providers (for dependency injection).
Manual Compodoc setup for Angular Storybook
To manually set up Compodoc: (1) Install @compodoc/compodoc as a dev dependency with 'npm install --save-dev @compodoc/compodoc'. (2) Add 'compodoc': true and compodocArgs to both storybook and build-storybook builders in angular.json. The compodocArgs should include ['-e', 'json', '-d', '.'] where the -d parameter specifies where documentation is stored, typically the Angular project root. (3) Add Compodoc output to .storybook/preview.ts.
Compodoc integration for Angular components
Compodoc automatically generates documentation for Angular components by parsing JSDoc comments. It is particularly useful to add explanatory comments above @Inputs and @Outputs, as these are the main elements displayed in Storybook's user interface and are interactive as controls.
Build Storybook in Angular project
To build Storybook for an Angular project, run 'ng run <your-project>:build-storybook'. The output is placed in the configured outputDir, which defaults to dist/storybook/<your-project>.
Run Storybook in Angular project
To run Storybook for a particular Angular project, execute 'ng run <your-project>:storybook' from the command line.
Angular Storybook builder configuration options
Angular Storybook builder configuration includes: browserTarget (build target in format 'example-project:builder:config'), debugWebpack (boolean to debug Webpack config), tsConfig (path to TypeScript config), preserveSymlinks (boolean), port (default 6006), host (custom host URL), configDir (config directory location, default '.storybook'), https (boolean, requires certificate), sslCa (SSL certificate authority), sslCert (SSL certificate, required for https), sslKey (SSL key), smokeTest (exit after successful start), ci (CI mode, no prompts), open (auto-open browser), quiet (filter verbose output), enableProdMode (disable Angular dev mode), docs (documentation mode), compodoc (execute compodoc before start), compodocArgs (Compodoc options array), styles (array of style file paths), stylePreprocessorOptions (preprocessor customization object), assets (static asset paths array), initialPath (URL path appended on first visit), webpackStatsJson (write Webpack stats to disk), previewUrl (custom preview file), loglevel (trace/debug/info/warn/error/silent), sourceMap (boolean), experimentalZoneless (zoneless change detection boolean).
Angular ≥ 21 should use Vite-based framework
For Angular version 21 and above, consider using @storybook/angular-vite instead of the Webpack version for faster builds and Vitest addon support. It provides the same authoring surface with full Vitest integration.
Angular Storybook framework requirements
Storybook for Angular (Webpack) requires Angular ≥ 18.0 and < 23.0, and Webpack 5.
Community-maintained frameworks
Storybook includes an active community that supports additional frameworks and libraries beyond the officially supported ones. These community-maintained frameworks are actively developed and maintained by community contributors.
Supported frameworks availability
Storybook has a list of officially supported frameworks displayed on the frameworks documentation page.
Manual Compodoc configuration in Angular with Vite
Install @compodoc/compodoc as a dev dependency, then configure Storybook to run Compodoc via framework.options in .storybook/main.ts with compodoc: true and compodocArgs (defaulting to ['-e', 'json', '-d', '.']). Storybook generates documentation.json once per run: every storybook dev, every storybook build, and every Vitest run. Compodoc scans the whole project in one pass, so there is no per-component regeneration.
Running Storybook with Angular CLI
After registering builders in angular.json, run Storybook with ng run your-project:storybook for development and ng run your-project:build-storybook for production builds.
Angular CLI builder configuration for Storybook
Register start-storybook and build-storybook builders in angular.json. The start-storybook builder uses @storybook/angular-vite:start-storybook with options including configDir (default .storybook) and port (default 6006). The build-storybook builder uses @storybook/angular-vite:build-storybook with options including configDir (.storybook) and outputDir (e.g., dist/storybook/your-project). Unlike the Webpack-based @storybook/angular, these builders do not take a browserTarget parameter because Vite resolves TypeScript and assets directly.
Angular Webpack vs Vite framework comparison
Use @storybook/angular-vite when you want faster builds and HMR than the Webpack-based @storybook/angular framework, full support for the Vitest addon and in-browser component testing, and a simpler configuration without Babel and smaller dependency footprint. Use @storybook/angular (Webpack 5) if your project requires Angular ≤ 20 or has custom Webpack configurations you cannot migrate.
Angular with Vite minimum version requirements
@storybook/angular-vite requires Angular ≥ 21 and Vite ≥ 8.
Angular with Vite framework preview status
@storybook/angular-vite is currently in preview. The framework is feature-complete for documented use cases, but APIs and defaults may change based on feedback before it is marked stable. Users should report issues and share feedback on GitHub.
Compodoc behavior during development
Editing a component while Storybook is running does not update its metadata because controls, descriptions, and JSDoc tags come from the documentation generated at startup. Restart Storybook to pick up component changes. Running tests from a running Storybook reuses that Storybook's documentation rather than scanning again, so the test run starts quickly.
Compodoc automatic setup for Angular
When installing Storybook via npx storybook@latest init, Compodoc can be set up automatically. Compodoc reads JSDoc comments above components, directives, and other Angular code parts and surfaces them as automatic documentation and controls in Storybook.
Compodoc lock and run files
Two files appear next to the Compodoc output: .compodoc.lock while a run is in progress, and .compodoc.run recording which run produced the current documentation. Together they let several Storybook processes share a single Compodoc run instead of each starting their own. Both are safe to add to .gitignore. Only documentation.json is published into the output directory.
Compodoc with Angular CLI builders invocation
When using ng run app:storybook, the framework runs Compodoc at start-up so documentation.json is generated before stories render. The Vitest addon panel inside a running storybook dev inherits builder options from the parent process automatically. Standalone yarn vitest (without a parent storybook dev) is supported via storybookAngularVitest from @storybook/angular-vite/vitest, which forwards Angular build options into the channel the framework reads.