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.
Application-wide providers in Angular with Vite stories
If a component relies on application-wide providers (such as those returned by provide-style functions or set up by modules using the forRoot pattern), use the applicationConfig decorator to supply them via the bootstrapApplication function.
Angular dependencies in stories
If a component has dependencies on other Angular directives and modules, supply them using the moduleMetadata decorator either for all stories of a component or for individual stories.
Zoneless change detection in Angular with Vite
By default, @storybook/angular-vite runs with zoneless change detection (zoneless: true). To opt into Zone.js-based change detection, set the zoneless option to false on the Storybook builder target in angular.json. When zoneless is false, zone.js is automatically imported at the start of the preview.
Custom Vite configuration in Angular with Vite
Extend Vite configuration used by Storybook in .storybook/main.ts via viteFinal. Example: import type { StorybookConfig } from '@storybook/angular-vite'; const config: StorybookConfig = { framework: '@storybook/angular-vite', async viteFinal(config) { const { mergeConfig } = await import('vite'); return mergeConfig(config, { /* your overrides */ }); } }; export default config;
TypeScript paths in Angular with Vite
@storybook/angular-vite does not automatically map tsconfig.json paths aliases into Vite's module resolver. Vite resolves modules on disk and does not read the paths compiler option, so imports like @app/shared will fail unless registered. The simplest fix is the vite-tsconfig-paths plugin, which reads baseUrl and paths from tsconfig.json and adds matching aliases. Install it as npm install --save-dev vite-tsconfig-paths, then add it to viteFinal.
TypeScript paths configuration example
Example of configuring vite-tsconfig-paths in .storybook/main.ts: import type { StorybookConfig } from '@storybook/angular-vite'; const config: StorybookConfig = { framework: '@storybook/angular-vite', async viteFinal(config) { const { mergeConfig } = await import('vite'); const { default: tsconfigPaths } = await import('vite-tsconfig-paths'); return mergeConfig(config, { plugins: [tsconfigPaths()] }); } }; export default config;
Migrating from @storybook/angular to @storybook/angular-vite
Run npx storybook automigrate to update the project automatically. For manual migration: install @storybook/angular-vite, update .storybook/main.ts to change the framework property to @storybook/angular-vite, update angular.json builder references from @storybook/angular to @storybook/angular-vite, and remove the browserTarget option from the builder options.
webpackFinal migration to viteFinal
If your Storybook configuration contains a webpackFinal hook, migrate it to viteFinal when upgrading from @storybook/angular to @storybook/angular-vite.
Vitest addon support in Angular with Vite
@storybook/angular-vite is a Vite-based framework that supports the Vitest addon for running component tests directly inside Storybook.
Standalone Vitest configuration for Angular
Example vitest.config.ts for standalone yarn vitest: import { storybookAngularVitest } from '@storybook/angular-vite/vitest'; import { storybookTest } from '@storybook/addon-vitest/vitest-plugin'; import { defineConfig } from 'vitest/config'; export default defineConfig({ test: { projects: [{ plugins: [storybookAngularVitest({ /* styles, stylePreprocessorOptions, assets, zoneless */ }), storybookTest({ configDir: '.storybook' })], test: { browser: { enabled: true, provider: 'playwright', instances: [{ browser: 'chromium' }] } } }] } });
Vitest addon installation for Angular
Run a command to install and configure the Vitest addon automatically. This installs @storybook/addon-vitest, configures Vitest in browser mode using Playwright's Chromium browser, sets up the Vitest plugin, and for Angular projects scaffolds storybookAngularVitest({}) next to storybookTest() in vitest.config.ts so standalone yarn vitest runs pick up Angular build options automatically.
Story compatibility between Angular and Angular with Vite
The story format (CSF), decorators (moduleMetadata, applicationConfig, componentWrapperDecorator), parameters, and compodoc integration are identical between @storybook/angular and @storybook/angular-vite. Stories files will only require changes to the framework import paths, which are handled automatically during migration.
Module aliases support
Module aliases defined in tsconfig.json are supported. For example, @/components/* mapping works in Storybook.
Install Storybook in Next.js project
To install Storybook in an existing Next.js project, run the create command in the project's root directory. The command will prompt you to choose between the Webpack framework (@storybook/nextjs) and the Vite framework (@storybook/nextjs-vite). For more control over the installation process, refer to the installation guide.
Run Storybook development server
To run Storybook for a Next.js project, use the storybook dev command. To build Storybook for production, use the build-storybook command. The build output is placed in the configured outputDir, which defaults to storybook-static.
Next.js image optimization support
Storybook for Next.js supports next/image with no configuration required. Local images (imported as files) are supported with automatic width and height properties. Remote images are also supported but require explicit width and height props. The blurDataURL is set to equal the image itself for local images in this framework, and the placeholder="blur" option is available.
Next.js router stubbing
Next.js router from next/router is automatically stubbed so that router interactions are logged to the Actions panel. Default router values include: locale (from globals), asPath '/', basePath '/', isFallback false, isLocaleDomain false, isReady true, isPreview false, route '/', pathname '/', and query {}. Router methods like push() and replace() are mock functions that can be manipulated and asserted on.
Configure useSelectedLayoutSegment, useSelectedLayoutSegments, and useParams
The useSelectedLayoutSegment, useSelectedLayoutSegments, and useParams hooks are supported. Set the nextjs.navigation.segments parameter as an array of strings (for segments) or arrays of [key, value] pairs (for params). For example, ['dashboard', 'analytics'] returns those values from useSelectedLayoutSegments(), and [['slug', 'hello'], ['framework', 'nextjs']] provides those values to useParams(). The default value is an empty array.
Default Next.js navigation context
The default navigation context values are: pathname '/', query {}. All router methods like push() and replace() are mock functions that can be manipulated and asserted on using regular mock APIs.
Absolute imports in Storybook
Absolute imports from the root directory are supported. For example, import Button from 'components/button' works in Storybook stories and in .storybook/preview.tsx for global styles. However, absolute imports cannot be mocked in stories or tests.
Subpath imports as alternative to module aliases
Subpath imports can be used as an alternative to module aliases by defining the imports property in package.json. For example, {"imports": {"#*": ["./*", "./*.ts", "./*.tsx"]}} enables usage like import Button from '#components/button'. Subpath imports follow Node package standards and have benefits when mocking modules. They can replace module aliases, allowing removal of path aliases from TypeScript configuration.
Router mock module
@storybook/nextjs/router.mock exports mocked implementations of next/router exports and a getRouter() function returning a mocked version of Next.js's router object from useRouter. Properties can be manipulated and asserted on, allowing mock implementations or assertions in story play functions.
React Server Components (RSC) experimental support
Storybook can render React Server Components in stories. Enable this by setting the experimentalRSC feature flag in .storybook/main.js|ts. This automatically wraps stories in a Suspense wrapper to render asynchronous components in Next.js's version of React.
RSC server-side resource limitation
Wrapping server components in Suspense does not help if server components access server-side resources like the file system or Node-specific libraries. To work around this, mock the data access layer using Webpack aliases or addons like storybook-addon-module-mock. For network-accessed data, use the MSW Storybook Addon.
Manual Next.js framework installation steps
To manually install the Next.js Webpack framework: (1) Install the @storybook/nextjs package, (2) Update .storybook/main.js|ts to set the framework property to @storybook/nextjs, (3) Remove any Storybook plugins that were previously used for Next.js integration as they are no longer necessary.
Migrate from Webpack to Vite framework
To migrate from @storybook/nextjs (Webpack) to @storybook/nextjs-vite (Vite), refer to the migration instructions in the nextjs-vite documentation.
Stories for pages with data fetching
Next.js pages in the app directory can fetch data in server components with Node.js-only module imports. Importing these pages in Storybook will crash the Webpack build because those modules don't run in browsers. Workaround: extract the component into a separate file and import the pure component in stories, or polyfill those modules in Storybook's webpackFinal configuration.
Statically imported images loading
Image imports must be treated the same as in normal Next.js development. Image imports now return an object with properties (src, height, width, blurDataURL) rather than just the raw path. Ensure components expect the object and access its src property appropriately.
Framework options configuration
The @storybook/nextjs framework accepts an options object in .storybook/main.js|ts. Available options are: builder (Record<string, any>) for configuring the Webpack builder options, and nextConfigPath (string) for specifying the absolute path to next.config.js when it's not in the project root.
nextjs.image parameter
The nextjs.image parameter is of type object and passes props to every instance of next/image. See Next.js next/image documentation for available props.
nextjs.router parameter
The nextjs.router parameter is of type {asPath?: string, pathname?: string, query?: Record<string, string>}. It controls the router object passed to the next/router context.
getPackageAliases export mock utility
@storybook/nextjs/export-mocks exports getPackageAliases({ useESM?: boolean }) function that generates aliases needed to set up portable stories. This helper is useful in jest.config.ts for configuring moduleNameMapper with the returned aliases.
Next.js Webpack framework requirements
Storybook for Next.js with Webpack requires Next.js version ≥ 14.1 and Webpack version 5.
Mock network requests for RSC
If your server components access data via the network, use the MSW Storybook Addon to mock network requests.
Stories for pages with data fetching
Next.js pages can fetch data directly within server components, which often include module imports that only run in a node environment. This does not work within Storybook because importing from a Next.js page file containing those node module imports in your stories will crash the Storybook Vite build. To work around this, extract the component in your page file into a separate file and import that pure component in your stories. Alternatively, configure Vite to handle those modules in your Storybook viteFinal configuration.
Next.js with Vite is the recommended framework
Storybook for Next.js (Vite) is the recommended framework for developing and testing UI components in isolation for Next.js applications. It uses Vite for faster builds, better performance, and Storybook Testing support.
Install Storybook in Next.js project
To install Storybook in an existing Next.js project, run the create command in your project's root directory. You can then get started writing stories, running tests, and documenting your components.
Next.js with Vite requirements
Next.js with Vite framework requires Next.js version ≥ 14.1 and Vite version ≥ 5.
Vite framework advantages over Webpack
The Vite-based nextjs-vite framework offers faster builds (Vite is significantly faster than Webpack), modern tooling with latest build tools, better test support with full Vitest addon support, simpler configuration without Babel or complex Webpack configurations, and better development experience with faster HMR and dev server startup.
Storybook framework auto-detection for Next.js
Storybook will automatically detect your project and select the nextjs-vite framework unless your project has custom Webpack or Babel configurations. If you have custom configurations, Storybook will ask you which framework to install.
Run Storybook dev server
To run Storybook for a Next.js project, run the storybook dev command in your project directory.
Next.js features supported in Storybook
Storybook for Next.js with Vite supports image optimization, font optimization, routing and navigation, next/head, absolute imports, styling (Sass/SCSS, CSS/Sass/SCSS modules, styled-jsx, Tailwind, PostCSS), module mocking, and React Server Components (experimental).
nextjs.appDirectory parameter
Type: boolean. Default: false. If your story imports components that use next/navigation, set nextjs.appDirectory to true. This is a parameter that can be applied to a single story, all stories for a component, or every story in your Storybook.
nextConfigPath option for framework
Type: string. The absolute path to the next.config.js file. This is necessary if you have a custom next.config.js file that is not in the root directory of your project.
Framework options configuration
You can pass an options object to the framework for additional configuration in .storybook/main.js|ts.
nextjs.router parameter
Type: { asPath?: string; pathname?: string; query?: Record<string, string>; }. The router object passed to the next/router context.
Next.js router is automatically stubbed
Next.js's router is automatically stubbed for you so that when the router is interacted with, all of its interactions are automatically logged to the Actions panel.
pages vs app directory for Next.js router
Use next/router only in the pages directory. In the app directory, use next/navigation.
Override router in stories with parameters
Per-story router overrides can be done by adding a nextjs.router property onto the story parameters. The framework will shallowly merge whatever you put here into the router. These overrides can also be applied to all stories for a component or all stories in your project using standard parameter inheritance rules.
Default router values
The default values on the stubbed router are: locale (from globals), asPath: '/', basePath: '/', isFallback: false, isLocaleDomain: false, isReady: true, isPreview: false, route: '/', pathname: '/', query: {}. The router object contains all original methods (push, replace, etc.) as mock functions.
next/navigation only in app directory
next/navigation can only be used in components and pages in the app directory.
Enable app directory with nextjs.appDirectory parameter
If your story imports components that use next/navigation, set the parameter nextjs.appDirectory to true. This can be set for a single component's stories, or applied to all stories in the Storybook project by setting it in the .storybook/preview.tsx file.
Override navigation context in stories
Per-story navigation overrides can be done by adding a nextjs.navigation property onto the story parameters. The framework will shallowly merge whatever you put here into the navigation context. These overrides can also be applied to all stories for a component or all stories in your project.
Next.js Runtime Configuration support
Next.js Runtime Configuration feature works fine in Storybook with this framework. Components will only see what they normally see on the client side (publicRuntimeConfig) but not serverRuntimeConfig.
useSelectedLayoutSegment hooks support
The useSelectedLayoutSegment, useSelectedLayoutSegments, and useParams hooks are supported in Storybook. Set the nextjs.navigation.segments parameter to return the segments or params you want to use.
useParams hook with subpath imports
To use the useParams hook, you must use a segments array where each element is an array containing two strings: the param key and the param value.
Default navigation context values
The default values on the stubbed navigation context are: pathname: '/', query: {}. The router object contains all original methods (push, replace, etc.) as mock functions that can be manipulated and asserted on using regular mock APIs.
Default nextjs.navigation.segments value
The default value of nextjs.navigation.segments is an empty array if not set.
next/head support
next/head is supported out of the box in Storybook. You can use it in your stories like you would in your Next.js application. The Head children are placed into the head element of the iframe that Storybook uses to render your stories.