docs/get-started/frameworks/nextjs-vite.mdx
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.
To install Storybook in an existing Next.js project, run this command in your project's root directory:
<CodeSnippets path="create-command.md" variant="new-users" copyEvent="CreateCommandCopy" />You can then get started writing stories, running tests and documenting your components. For more control over the installation process, refer to the installation guide.
<GetStartedVersions versions={[{ name: 'Next.js', range: '≥ 14.1', icon: '/images/logos/renderers/logo-nextjs.svg' }, { name: 'Vite', range: '≥ 5', icon: '/images/logos/builders/vite.svg' }]} />
This Vite-based framework offers several advantages over the Webpack-based @storybook/nextjs framework, and is the recommended option:
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.
Choose nextjs-vite if you're willing to migrate existing Babel or Webpack configurations to Vite. Choose nextjs (Webpack 5) if you need to keep your existing Webpack/Babel setup.
To run Storybook for a particular project, run the following:
<CodeSnippets path="storybook-run-dev.md" />To build Storybook, run:
<CodeSnippets path="build-storybook-production-mode.md" />You will find the output in the configured outputDir (default is storybook-static).
Storybook for Next.js with Vite supports many Next.js features including:
next/headThis framework allows you to use Next.js's next/image with no configuration.
Local images are supported.
import Image from 'next/image';
import profilePic from '../public/me.png';
function Home() {
return (
<>
<h1>My Homepage</h1>
<Image
src={profilePic}
alt="Picture of the author"
// width={500} automatically provided
// height={500} automatically provided
// blurDataURL="../public/me.png" set to equal the image itself (for this framework)
// placeholder="blur" // Optional blur-up while loading
/>
<p>Welcome to my homepage!</p>
</>
);
}
Remote images are also supported.
import Image from 'next/image';
export default function Home() {
return (
<>
<h1>My Homepage</h1>
<Image src="/me.png" alt="Picture of the author" width={500} height={500} />
<p>Welcome to my homepage!</p>
</>
);
}
next/font is partially supported in Storybook. The packages next/font/google and next/font/local are supported.
next/font/googleYou don't have to do anything. next/font/google is supported out of the box.
next/font/localFor local fonts you have to define the src property. The path is relative to the directory where the font loader function is called.
If the following component defines your localFont like this:
import localFont from 'next/font/local';
const localRubikStorm = localFont({ src: './fonts/RubikStorm-Regular.ttf' });
The Vite-based framework automatically handles font path mapping, so you don't need to configure staticDirs for fonts like you would with the Webpack-based framework.
next/fontThe following features are not supported (yet). Support for these features might be planned for the future:
Occasionally fetching fonts from Google may fail as part of your Storybook build step. It is highly recommended to mock these requests, as those failures can cause your pipeline to fail as well. Next.js supports mocking fonts via a JavaScript module located where the env var NEXT_FONT_GOOGLE_MOCKED_RESPONSES references.
For example, using GitHub Actions:
- uses: chromaui/action@latest
env:
#👇 the location of mocked fonts to use
NEXT_FONT_GOOGLE_MOCKED_RESPONSES: ${{ github.workspace }}/mocked-google-fonts.js
with:
projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
token: ${{ secrets.GITHUB_TOKEN }}
Your mocked fonts will look something like this:
//👇 Mocked responses of google fonts with the URL as the key
module.exports = {
'https://fonts.googleapis.com/css?family=Inter:wght@400;500;600;800&display=block': `
/* cyrillic-ext */
@font-face {
font-family: 'Inter';
font-style: normal;
font-weight: 400;
font-display: block;
src: url(https://fonts.gstatic.com/s/inter/v12/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZJhiJ-Ek-_EeAmM.woff2) format('woff2');
unicode-range: U+0460-052F, U+1C80-1C88, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
}
/* more font declarations go here */
/* latin */
@font-face {
font-family: 'Inter';
font-style: normal;
font-weight: 400;
font-display: block;
src: url(https://fonts.gstatic.com/s/inter/v12/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZ9hiJ-Ek-_EeA.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}`,
};
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.
<Callout>You should only use next/router in the pages directory. In the app directory, it is necessary to use next/navigation.
Per-story 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. Standard parameter inheritance rules apply.
</Callout>The default values on the stubbed router are as follows (see globals for more details on how globals work).
// Default router
const defaultRouter = {
// The locale should be configured globally: https://storybook.js.org/docs/essentials/toolbars-and-globals#globals
locale: globals?.locale,
asPath: '/',
basePath: '/',
isFallback: false,
isLocaleDomain: false,
isReady: true,
isPreview: false,
route: '/',
pathname: '/',
query: {},
};
Additionally, the router object contains all of the original methods (such as push(), replace(), etc.) as mock functions that can be manipulated and asserted on using regular mock APIs.
To override these defaults, you can use parameters and beforeEach:
Please note that next/navigation can only be used in components/pages in the app directory.
nextjs.appDirectory to trueIf your story imports components that use next/navigation, you need to set the parameter nextjs.appDirectory to true in for that component's stories:
If your Next.js project uses the app directory for every page (in other words, it does not have a pages directory), you can set the parameter nextjs.appDirectory to true in the .storybook/preview.js|ts file to apply it to all stories.
Per-story 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 router.
These overrides can also be applied to all stories for a component or all stories in your project. Standard parameter inheritance rules apply.
</Callout>useSelectedLayoutSegment, useSelectedLayoutSegments, and useParams hooksThe useSelectedLayoutSegment, useSelectedLayoutSegments, and useParams hooks are supported in Storybook. You have to set the nextjs.navigation.segments parameter to return the segments or the params you want to use.
With the above configuration, the component rendered in the stories would receive the following values from the hooks:
import { useSelectedLayoutSegment, useSelectedLayoutSegments, useParams } from 'next/navigation';
export default function NavigationBasedComponent() {
const segment = useSelectedLayoutSegment(); // dashboard
const segments = useSelectedLayoutSegments(); // ["dashboard", "analytics"]
const params = useParams(); // {}
// ...
}
To use useParams, you have to use a segments array where each element is an array containing two strings. The first string is the param key and the second string is the param value.
With the above configuration, the component rendered in the stories would receive the following values from the hooks:
import { useSelectedLayoutSegment, useSelectedLayoutSegments, useParams } from 'next/navigation';
export default function ParamsBasedComponent() {
const segment = useSelectedLayoutSegment(); // hello
const segments = useSelectedLayoutSegments(); // ["hello", "nextjs"]
const params = useParams(); // { slug: "hello", framework: "nextjs" }
...
}
These overrides can also be applied to a single story or all stories in your project. Standard parameter inheritance rules apply.
</Callout>The default value of nextjs.navigation.segments is [] if not set.
The default values on the stubbed navigation context are as follows:
// Default navigation context
const defaultNavigationContext = {
pathname: '/',
query: {},
};
Additionally, the router object contains all of the original methods (such as push(), replace(), etc.) as mock functions that can be manipulated and asserted on using regular mock APIs.
To override these defaults, you can use parameters and beforeEach:
next/head is supported out of the box. You can use it in your stories like you would in your Next.js application. Please keep in mind, that the Head children are placed into the head element of the iframe that Storybook uses to render your stories.
Global Sass/SCSS stylesheets are also supported without any additional configuration. Just import them into the preview config file.
<CodeSnippets path="nextjs-styling-sass-preview.md" />This will automatically include any of your custom Sass configurations in your Next.js config file.
<CodeSnippets path="nextjs-styling-sass-config.md" />CSS modules work as expected.
<CodeSnippets path="nextjs-styling-css-modules.md" />The built-in CSS-in-JS solution for Next.js is styled-jsx, and this framework supports that out of the box, too, with zero config.
<CodeSnippets path="nextjs-styling-styled-jsx-component.md" />Tailwind in Next.js is supported via PostCSS. Storybook will automatically handle the PostCSS config for you, including any custom PostCSS configuration, so that you can import your global CSS directly into the preview config file:
<CodeSnippets path="nextjs-styling-tailwind.md" />Next.js lets you customize PostCSS config. Thus this framework will automatically handle your PostCSS config for you.
Absolute imports from the root directory are supported.
// All good!
import Button from 'components/button';
// Also good!
import styles from 'styles/HomePage.module.css';
export default function HomePage() {
return (
<>
<h1 className={styles.title}>Hello World</h1>
<Button />
</>
);
}
Also OK for global styles in .storybook/preview.js|ts!
import 'styles/globals.scss';
// ...
Absolute imports cannot be mocked in stories/tests. See the Mocking modules section for more information.
</Callout>Module aliases are also supported.
// All good!
import Button from '@/components/button';
// Also good!
import styles from '@/styles/HomePage.module.css';
export default function HomePage() {
return (
<>
<h1 className={styles.title}>Hello World</h1>
<Button />
</>
);
}
As an alternative to module aliases, you can use subpath imports to import modules. This follows Node package standards and has benefits when mocking modules.
To configure subpath imports, you define the imports property in your project's package.json file. This property maps the subpath to the actual file path. The example below configures subpath imports for all modules in the project:
{
"imports": {
"#*": ["./*", "./*.ts", "./*.tsx"]
}
}
Because subpath imports replace module aliases, you can remove the path aliases from your TypeScript configuration.
</Callout>Which can then be used like this:
import Button from '#components/button';
import styles from '#styles/HomePage.module.css';
export default function HomePage() {
return (
<>
<h1 className={styles.title}>Hello World</h1>
<Button />
</>
);
}
Components often depend on modules that are imported into the component file. These can be from external packages or internal to your project. When rendering those components in Storybook or testing them, you may want to mock those modules to control and assert their behavior.
This framework provides mocks for many of Next.js' internal modules:
@storybook/nextjs-vite/cache.mock@storybook/nextjs-vite/headers.mock@storybook/nextjs-vite/navigation.mock@storybook/nextjs-vite/router.mockTo mock other modules, use automocking or one of the alternative methods documented in the mocking modules guide.
Next.js allows for Runtime Configuration which lets you import a handy getConfig function to get certain configuration defined in your next.config.js file at runtime.
In the context of Storybook with this framework, you can expect Next.js's Runtime Configuration feature to work just fine.
Note, because Storybook doesn't server render your components, your components will only see what they normally see on the client side (i.e. they won't see serverRuntimeConfig but will see publicRuntimeConfig).
For example, consider the following Next.js config:
module.exports = {
serverRuntimeConfig: {
mySecret: 'secret',
secondSecret: process.env.SECOND_SECRET, // Pass through env variables
},
publicRuntimeConfig: {
staticFolder: '/static',
},
};
Calls to getConfig would return the following object when called within Storybook:
// Runtime config
{
"serverRuntimeConfig": {},
"publicRuntimeConfig": {
"staticFolder": "/static"
}
}
You can customize the Vite configuration used by Storybook in your .storybook/main.js|ts file. By default, Storybook's configuration extends the Vite configuration used by your project, but you can configure it to not do so.
Not all Vite modifications are copy/paste-able between next.config.js and .storybook/main.js|ts. It is recommended to do your research on how to properly make your modification to Storybook's Vite config and on how Vite works.
Storybook handles most Typescript configurations, but this framework adds additional support for Next.js's support for Absolute Imports and Module path aliases. In short, it takes into account your tsconfig.json's baseUrl and paths. Thus, a tsconfig.json like the one below would work out of the box.
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/components/*": ["components/*"]
}
}
}
(⚠️ Experimental)
If your app uses React Server Components (RSC), Storybook can render them in stories in the browser.
To enable this set the experimentalRSC feature flag in your .storybook/main.js|ts config:
Setting this flag automatically wraps your story in a Suspense wrapper, which is able to render asynchronous components in NextJS's version of React.
If this wrapper causes problems in any of your existing stories, you can selectively disable it using the react.rsc parameter at the global/component/story level:
Note that wrapping your server components in Suspense does not help if your server components access server-side resources like the file system or Node-specific libraries. To work around this, you'll need to mock out your data access layer using Vite aliases or an addon like storybook-addon-module-mock.
If your server components access data via the network, we recommend using the MSW Storybook Addon to mock network requests.
In the future we will provide better mocking support in Storybook and support for Server Actions.
nextjs (Webpack 5) addon?Storybook provides a migration tool for migrating to this framework from the Webpack-based Next.js framework, @storybook/nextjs. To migrate, run this command:
npx storybook automigrate nextjs-to-nextjs-vite
This automigration tool performs the following actions:
package.json files to replace @storybook/nextjs with @storybook/nextjs-vite.storybook/main.js|ts to change the framework propertyIf your project has custom Webpack configurations in .storybook/main.js|ts (via webpackFinal), you'll need to migrate those to Vite configuration (via viteFinal) after running this automigration. See the Vite builder documentation for more information.
First, install the framework:
<CodeSnippets path="nextjs-vite-install.md" />Then, update your .storybook/main.js|ts to change the framework property:
If your Storybook configuration contains custom Webpack operations in webpackFinal, you will likely need to create equivalents in viteFinal.
For more information, see the Vite builder documentation.
</Callout>Finally, if you were using Storybook plugins to integrate with Next.js, those are no longer necessary when using this framework and can be removed:
<CodeSnippets path="nextjs-remove-addons.md" />Next.js pages can fetch data directly within server components in the app directory, which often include module imports that only run in a node environment. This does not (currently) work within Storybook, because if you import from a Next.js page file containing those node module imports in your stories, your Storybook's Vite build will crash because those modules will not run in a browser. To get around this, you can extract the component in your page file into a separate file and import that pure component in your stories. Or, if that's not feasible for some reason, you can configure Vite to handle those modules in your Storybook's viteFinal configuration.
Before
async function getData() {
const res = await fetch(...);
// ...
}
// Using this component in your stories will break the Storybook build
export default async function Page() {
const data = await getData();
return // ...
}
After
// Use this component in your stories
import MyPage from './components/MyPage';
async function getData() {
const res = await fetch(...);
// ...
}
export default async function Page() {
const data = await getData();
return <MyPage {...data} />;
}
Make sure you are treating image imports the same way you treat them when using next/image in normal development.
Before using this framework, image imports would import the raw path to the image (e.g. 'static/media/stories/assets/logo.svg'). Now image imports work the "Next.js way", meaning that you now get an object when importing an image. For example:
// Image import object
{
"src": "static/media/stories/assets/logo.svg",
"height": 48,
"width": 48,
"blurDataURL": "static/media/stories/assets/logo.svg"
}
Therefore, if something in Storybook isn't showing the image properly, make sure you expect the object to be returned from an import instead of only the asset path.
See local images for more detail on how Next.js treats static image imports.
sharp is a dependency of Next.js's image optimization feature. If you see this error, you need to install sharp in your project.
npm install sharp
yarn add sharp
pnpm add sharp
You can refer to the Install sharp to Use Built-In Image Optimization in the Next.js documentation for more information.
We recommend using @storybook/nextjs-vite (this framework) for most projects because it offers:
However, if your project has custom Webpack configurations that are incompatible with Vite, or you need specific Webpack features, you should use @storybook/nextjs (Webpack 5) instead.
The @storybook/nextjs-vite package exports several modules that enable you to mock Next.js's internal behavior.
@storybook/nextjs-vite/cache.mockType: typeof import('next/cache')
This module exports mocked implementations of the next/cache module's exports. You can use it to create your own mock implementations or assert on mock calls in a story's play function.
@storybook/nextjs-vite/headers.mockType: cookies, headers and draftMode from Next.js
This module exports writable mocked implementations of the next/headers module's exports. You can use it to set up cookies or headers that are read in your story, and to later assert that they have been called.
Next.js's default headers() export is read-only, but this module exposes methods allowing you to write to the headers:
headers().append(name: string, value: string): Appends the value to the header if it exists already.headers().delete(name: string): Deletes the headerheaders().set(name: string, value: string): Sets the header to the value provided.For cookies, you can use the existing API to write them. E.g., cookies().set('firstName', 'Jane').
Because headers(), cookies() and their sub-functions are all mocks you can use any mock utilities in your stories, like headers().getAll.mock.calls.
@storybook/nextjs-vite/navigation.mockType: typeof import('next/navigation') & getRouter: () => ReturnType<typeof import('next/navigation')['useRouter']>
This module exports mocked implementations of the next/navigation module's exports. It also exports a getRouter function that returns a mocked version of Next.js's router object from useRouter, allowing the properties to be manipulated and asserted on. You can use it mock implementations or assert on mock calls in a story's play function.
@storybook/nextjs-vite/router.mockType: typeof import('next/router') & getRouter: () => ReturnType<typeof import('next/router')['useRouter']>
This module exports mocked implementations of the next/router module's exports. It also exports a getRouter function that returns a mocked version of Next.js's router object from useRouter, allowing the properties to be manipulated and asserted on. You can use it mock implementations or assert on mock calls in a story's play function.
You can pass an options object for additional configuration if needed:
<CodeSnippets path="nextjs-framework-options-next-config-path.md" />The available options are:
builderType: Record<string, any>
Configure options for the framework's builder. For Next.js with Vite, available options can be found in the Vite builder docs.
imageType: object
Props to pass to every instance of next/image. See next/image docs for more details.
nextConfigPathType: 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.
This framework contributes the following parameters to Storybook, under the nextjs namespace:
appDirectoryType: boolean
Default: false
If your story imports components that use next/navigation, you need to set the parameter nextjs.appDirectory to true. Because this is a parameter, you can apply it to a single story, all stories for a component, or every story in your Storybook. See Next.js Navigation for more details.
navigationType:
{
asPath?: string;
pathname?: string;
query?: Record<string, string>;
segments?: (string | [string, string])[];
}
Default value:
{
segments: [];
}
The router object that is passed to the next/navigation context. See Next.js's navigation docs for more details.
routerType:
{
asPath?: string;
pathname?: string;
query?: Record<string, string>;
}
The router object that is passed to the next/router context. See Next.js's router docs for more details.