diff --git a/docs/_snippets/nextjs-add-framework.md b/docs/_snippets/nextjs-add-framework.md
index 1c87e051035a..011399eac75e 100644
--- a/docs/_snippets/nextjs-add-framework.md
+++ b/docs/_snippets/nextjs-add-framework.md
@@ -1,43 +1,44 @@
-```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF 3"
+```diff filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF 3"
export default {
// ...
- // framework: '@storybook/react-webpack5', π Remove this
- framework: '@storybook/nextjs', // π Add this
+- framework: '@storybook/react-webpack5',
++ framework: '@storybook/nextjs',
};
```
-```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF 3"
-import type { StorybookConfig } from '@storybook/nextjs';
+```diff filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF 3"
+- import type { StorybookConfig } from '@storybook/your-previous-framework';
++ import type { StorybookConfig } from '@storybook/nextjs';
const config: StorybookConfig = {
// ...
- // framework: '@storybook/react-webpack5', π Remove this
- framework: '@storybook/nextjs', // π Add this
+- framework: '@storybook/react-webpack5',
++ framework: '@storybook/nextjs',
};
export default config;
```
-```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
-import { defineMain } from '@storybook/your-framework/node';
+```diff filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF Next π§ͺ"
+- import { defineMain } from '@storybook/your-previous-framework/node';
++ import { defineMain } from '@storybook/nextjs/node';
export default defineMain({
// ...
- // framework: '@storybook/react-webpack5', π Remove this
- framework: '@storybook/nextjs', // π Add this
+- framework: '@storybook/react-webpack5',
++ framework: '@storybook/nextjs',
});
```
-```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
-import { defineMain } from '@storybook/your-framework/node';
+```diff filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF Next π§ͺ"
+- import { defineMain } from '@storybook/your-previous-framework/node';
++ import { defineMain } from '@storybook/nextjs/node';
export default defineMain({
// ...
- // framework: '@storybook/react-webpack5', π Remove this
- framework: '@storybook/nextjs', // π Add this
+- framework: '@storybook/react-webpack5',
++ framework: '@storybook/nextjs',
});
```
diff --git a/docs/_snippets/nextjs-app-directory-in-preview.md b/docs/_snippets/nextjs-app-directory-in-preview.md
index 8ecf8d79e6e9..1b9b7ac6c05c 100644
--- a/docs/_snippets/nextjs-app-directory-in-preview.md
+++ b/docs/_snippets/nextjs-app-directory-in-preview.md
@@ -28,7 +28,7 @@ export default preview;
```
```ts filename=".storybook/preview.ts" renderer="react" language="ts" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
+// Replace your-framework with nextjs or nextjs-vite
import { definePreview } from '@storybook/your-framework';
export default definePreview({
@@ -45,7 +45,7 @@ export default definePreview({
```js filename=".storybook/preview.js" renderer="react" language="js" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
+// Replace your-framework with nextjs or nextjs-vite
import { definePreview } from '@storybook/your-framework';
export default definePreview({
diff --git a/docs/_snippets/nextjs-configure-svgr.md b/docs/_snippets/nextjs-configure-svgr.md
index 332b6fc078aa..8b471f318893 100644
--- a/docs/_snippets/nextjs-configure-svgr.md
+++ b/docs/_snippets/nextjs-configure-svgr.md
@@ -53,7 +53,7 @@ export default config;
```
```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
+// Replace your-framework with nextjs or nextjs-vite
import { defineMain } from '@storybook/your-framework/node';
export default defineMain({
@@ -83,7 +83,7 @@ export default defineMain({
```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
+// Replace your-framework with nextjs or nextjs-vite
import { defineMain } from '@storybook/your-framework/node';
export default defineMain({
diff --git a/docs/_snippets/nextjs-image-static-dirs.md b/docs/_snippets/nextjs-image-static-dirs.md
index af077340e6e3..8bb085e50fa6 100644
--- a/docs/_snippets/nextjs-image-static-dirs.md
+++ b/docs/_snippets/nextjs-image-static-dirs.md
@@ -28,7 +28,7 @@ export default config;
```
```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
+// Replace your-framework with nextjs or nextjs-vite
import { defineMain } from '@storybook/your-framework/node';
export default defineMain({
@@ -45,7 +45,7 @@ export default defineMain({
```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
+// Replace your-framework with nextjs or nextjs-vite
import { defineMain } from '@storybook/your-framework/node';
export default defineMain({
diff --git a/docs/_snippets/nextjs-remove-addons.md b/docs/_snippets/nextjs-remove-addons.md
index 065a5d713d1f..fb08932d0173 100644
--- a/docs/_snippets/nextjs-remove-addons.md
+++ b/docs/_snippets/nextjs-remove-addons.md
@@ -11,7 +11,8 @@ export default {
```
```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF 3"
-import type { StorybookConfig } from '@storybook/nextjs';
+// Replace your-framework with nextjs or nextjs-vite
+import type { StorybookConfig } from '@storybook/your-framework';
const config: StorybookConfig = {
// ...
@@ -27,7 +28,7 @@ export default config;
```
```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
+// Replace your-framework with nextjs or nextjs-vite
import { defineMain } from '@storybook/your-framework/node';
export default defineMain({
@@ -44,7 +45,7 @@ export default defineMain({
```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
+// Replace your-framework with nextjs or nextjs-vite
import { defineMain } from '@storybook/your-framework/node';
export default defineMain({
diff --git a/docs/_snippets/nextjs-vite-add-framework.md b/docs/_snippets/nextjs-vite-add-framework.md
index 137479e97e3d..32b50f024ce7 100644
--- a/docs/_snippets/nextjs-vite-add-framework.md
+++ b/docs/_snippets/nextjs-vite-add-framework.md
@@ -1,43 +1,44 @@
-```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF 3"
+```diff filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF 3"
export default {
// ...
- // framework: '@storybook/react-webpack5', π Remove this
- framework: '@storybook/nextjs-vite', // π Add this
+- framework: '@storybook/react-webpack5',
++ framework: '@storybook/nextjs-vite',
};
```
-```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF 3"
-import type { StorybookConfig } from '@storybook/nextjs-vite';
+```diff filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF 3"
+- import type { StorybookConfig } from '@storybook/your-previous-framework';
++ import type { StorybookConfig } from '@storybook/nextjs-vite';
const config: StorybookConfig = {
// ...
- // framework: '@storybook/react-webpack5', π Remove this
- framework: '@storybook/nextjs-vite', // π Add this
+- framework: '@storybook/react-webpack5',
++ framework: '@storybook/nextjs-vite',
};
export default config;
```
-```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
-import { defineMain } from '@storybook/your-framework/node';
+```diff filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF Next π§ͺ"
+- import { defineMain } from '@storybook/your-previous-framework/node';
++ import { defineMain } from '@storybook/nextjs-vite/node';
export default defineMain({
// ...
- // framework: '@storybook/react-webpack5', π Remove this
- framework: '@storybook/nextjs-vite', // π Add this
+- framework: '@storybook/react-webpack5',
++ framework: '@storybook/nextjs-vite',
});
```
-```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
-import { defineMain } from '@storybook/your-framework/node';
+```diff filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF Next π§ͺ"
+- import { defineMain } from '@storybook/your-previous-framework/node';
++ import { defineMain } from '@storybook/nextjs-vite/node';
export default defineMain({
// ...
- // framework: '@storybook/react-webpack5', π Remove this
- framework: '@storybook/nextjs-vite', // π Add this
+- framework: '@storybook/react-webpack5',
++ framework: '@storybook/nextjs-vite',
});
```
diff --git a/docs/_snippets/nextjs-vite-remove-addons.md b/docs/_snippets/nextjs-vite-remove-addons.md
deleted file mode 100644
index 0a28992d16bd..000000000000
--- a/docs/_snippets/nextjs-vite-remove-addons.md
+++ /dev/null
@@ -1,59 +0,0 @@
-```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF 3"
-export default {
- // ...
- addons: [
- // ...
- // π These can both be removed
- // 'storybook-addon-next',
- // 'storybook-addon-next-router',
- ],
-};
-```
-
-```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF 3"
-import type { StorybookConfig } from '@storybook/nextjs-vite';
-
-const config: StorybookConfig = {
- // ...
- addons: [
- // ...
- // π These can both be removed
- // 'storybook-addon-next',
- // 'storybook-addon-next-router',
- ],
-};
-
-export default config;
-```
-
-```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
-import { defineMain } from '@storybook/your-framework/node';
-
-export default defineMain({
- // ...
- addons: [
- // ...
- // π These can both be removed
- // 'storybook-addon-next',
- // 'storybook-addon-next-router',
- ],
-});
-```
-
-
-
-```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
-import { defineMain } from '@storybook/your-framework/node';
-
-export default defineMain({
- // ...
- addons: [
- // ...
- // π These can both be removed
- // 'storybook-addon-next',
- // 'storybook-addon-next-router',
- ],
-});
-```
diff --git a/docs/_snippets/rsc-feature-flag.md b/docs/_snippets/rsc-feature-flag.md
index 1084b10054c7..438c6a6428d3 100644
--- a/docs/_snippets/rsc-feature-flag.md
+++ b/docs/_snippets/rsc-feature-flag.md
@@ -22,7 +22,7 @@ export default config;
```
```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
+// Replace your-framework with nextjs or nextjs-vite
import { defineMain } from '@storybook/your-framework/node';
export default defineMain({
@@ -36,7 +36,7 @@ export default defineMain({
```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF Next π§ͺ"
-// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
+// Replace your-framework with nextjs or nextjs-vite
import { defineMain } from '@storybook/your-framework/node';
export default defineMain({
diff --git a/docs/api/cli-options.mdx b/docs/api/cli-options.mdx
index 6890686804ce..f33b476e0f38 100644
--- a/docs/api/cli-options.mdx
+++ b/docs/api/cli-options.mdx
@@ -123,13 +123,15 @@ Options include:
| `-s`, `--skip-install` | Skips the dependency installation step. Used only when you need to configure Storybook manually. `storybook init --skip-install` |
| `-t`, `--type` | Defines the [framework](../configure/integration/frameworks.mdx) to use for your Storybook instance. `storybook init --type solid` |
| `-y`, `--yes` | Skips interactive prompts and automatically installs Storybook per specified version, including all features. `storybook init --yes` |
-| `--features [...values]` | Use these features when installing, skipping the prompt. Supported values are `docs`, `test` and `a11y`, space separated. `storybook init --features docs test a11y` |
+| `--features [...values]` | Use these features when installing, skipping the prompt. Supported values are `docs`, `test`, and `a11y`, space separated. `storybook init --features docs test a11y` |
| `--package-manager` | Sets the package manager to use when installing Storybook. Available package managers include `npm`, `yarn`, and `pnpm`. `storybook init --package-manager pnpm` |
| `--use-pnp` | Enables [Plug'n'Play](https://yarnpkg.com/features/pnp) support for Yarn. This option is only available when using Yarn as your package manager. `storybook init --use-pnp` |
| `-p`, `--parser` | Sets the [jscodeshift parser](https://github.com/facebook/jscodeshift#parser). Available parsers include `babel`, `babylon`, `flow`, `ts`, and `tsx`. `storybook init --parser tsx` |
| `--debug` | Outputs more logs in the CLI to assist debugging. `storybook init --debug` |
| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#how-to-opt-out). `storybook init --disable-telemetry` |
| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default). `storybook init --enable-crash-reports` |
+| `--loglevel ` | Controls level of logging during initialization. Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent` `storybook init --loglevel debug` |
+| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided. `storybook init --logfile /tmp/debug-storybook.log` |
| `--no-dev` | Complete the initialization of Storybook without running the Storybook dev server. `storybook init --no-dev` |
### `add`
@@ -149,6 +151,8 @@ Options include:
| `--package-manager` | Sets the package manager to use when installing the addon. Available package managers include `npm`, `yarn`, and `pnpm`. `storybook add [addon] --package-manager pnpm` |
| `-s`, `--skip-postinstall` | Skips post-install configuration. Used only when you need to configure the addon yourself. `storybook add [addon] --skip-postinstall` |
| `--debug` | Outputs more logs in the CLI to assist debugging. `storybook add --debug` |
+| `--loglevel ` | Controls level of logging during addon installation. Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent` `storybook add [addon] --loglevel debug` |
+| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided. `storybook add [addon] --logfile /tmp/debug-storybook.log` |
### `remove`
@@ -366,11 +370,13 @@ Options include:
| `-s`, `--skip-install` | Skips the dependency installation step. Used only when you need to configure Storybook manually. `create storybook --skip-install` |
| `-t`, `--type` | Defines the [framework](../configure/integration/frameworks.mdx) to use for your Storybook instance. `create storybook --type solid` |
| `-y`, `--yes` | Skips interactive prompts and automatically installs Storybook per specified version, including all features. `create storybook --yes` |
-| `--features [...values]` | Use these features when installing, skipping the prompt. Supported values are `docs`, `test` and `a11y`, space separated. `create storybook --features docs test a11y` |
+| `--features [...values]` | Use these features when installing, skipping the prompt. Supported values are `docs`, `test`, and `a11y`, space separated. `create storybook --features docs test a11y` |
| `--package-manager` | Sets the package manager to use when installing Storybook. Available package managers include `npm`, `yarn`, and `pnpm`. `create storybook --package-manager pnpm` |
| `--use-pnp` | Enables [Plug'n'Play](https://yarnpkg.com/features/pnp) support for Yarn. This option is only available when using Yarn as your package manager. `create storybook --use-pnp` |
| `-p`, `--parser` | Sets the [jscodeshift parser](https://github.com/facebook/jscodeshift#parser). Available parsers include `babel`, `babylon`, `flow`, `ts`, and `tsx`. `create storybook --parser tsx` |
| `--debug` | Outputs more logs in the CLI to assist debugging. `create storybook --debug` |
| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#how-to-opt-out). `create storybook --disable-telemetry` |
| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default). `create storybook --enable-crash-reports` |
+| `--loglevel ` | Controls level of logging during initialization. Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent` `storybook init --loglevel debug` |
+| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided. `storybook init --logfile /tmp/debug-storybook.log` |
| `--no-dev` | Complete the initialization of Storybook without running the Storybook dev server. `create storybook --no-dev` |
diff --git a/docs/get-started/frameworks/nextjs-vite.mdx b/docs/get-started/frameworks/nextjs-vite.mdx
new file mode 100644
index 000000000000..12b66b6329b0
--- /dev/null
+++ b/docs/get-started/frameworks/nextjs-vite.mdx
@@ -0,0 +1,954 @@
+---
+title: Storybook for Next.js with Vite
+hideRendererSelector: true
+sidebar:
+ order: 2
+ title: Next.js (Vite)
+---
+
+Storybook for Next.js (Vite) is the **recommended** [framework](../../contribute/framework.mdx) for developing and testing UI components in isolation for [Next.js](https://nextjs.org/) applications. It uses [Vite](https://vitejs.dev/) for faster builds and better performance. It includes:
+
+* π Routing
+* πΌ Image optimization
+* β€΅οΈ Absolute imports
+* π¨ Styling
+* β‘ Vite-powered builds
+* π« and more!
+
+This Vite-based framework offers several advantages over the Webpack-based [`@storybook/nextjs`](./nextjs.mdx) framework:
+
+* β‘ **Faster builds** - Vite's build system is significantly faster than Webpack
+* π§ **Modern tooling** - Uses the latest build tools and optimizations
+* π§ͺ **Better test support** - Full support for the [Vitest addon](../../writing-tests/integrations/vitest-addon.mdx) and other testing features
+* π¦ **Simpler configuration** - No need for Babel or complex Webpack configurations
+* π― **Better development experience** - Faster HMR (Hot Module Replacement) and dev server startup
+
+## Requirements
+
+* Next.js β₯ 14.1
+
+## Getting started
+
+### In a project without Storybook
+
+When you run `storybook init` in your Next.js project, Storybook will automatically detect your project and select the `@storybook/nextjs-vite` framework **unless** your project has custom Webpack or Babel configurations that may be incompatible with Vite.
+
+Follow the prompts after running this command in your Next.js project's root directory:
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+[More on getting started with Storybook.](../install.mdx)
+
+
+
+If your project has a custom `webpack.config.js` or `.babelrc` file, `storybook init` will prompt you to choose between:
+
+- **`@storybook/nextjs-vite`** (recommended) - Faster, more modern, supports latest testing features
+- **`@storybook/nextjs`** (Webpack 5) - Better compatibility with custom Webpack/Babel configurations
+
+Choose `nextjs-vite` if you're willing to migrate your custom configurations to Vite. Choose `nextjs` (Webpack 5) if you need to keep your existing Webpack/Babel setup.
+
+
+
+### In a project with Storybook
+
+This framework is designed to work with Storybook 10+. If you're not already using v10, upgrade with this command:
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+#### Automatic migration
+
+When running the `upgrade` command above, you should get a prompt asking you to migrate to `@storybook/nextjs-vite`, which should handle everything for you. In case that auto-migration does not work for your project, refer to the manual migration below.
+
+You can also use the [`nextjs-to-nextjs-vite` automigration](#migrating-from-webpack) to migrate from the Webpack-based `@storybook/nextjs` framework to this Vite-based framework.
+
+#### Manual migration
+
+First, install the framework:
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+Then, update your `.storybook/main.js|ts` to change the framework property:
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+
+
+If your Storybook configuration contains custom Webpack operations in [`webpackFinal`](../../api/main-config/main-config-webpack-final.mdx), you will likely need to create equivalents in [`viteFinal`](../../api/main-config/main-config-vite-final.mdx).
+
+For more information, see the [Vite builder documentation](../../builders/vite.mdx#migrating-from-webpack).
+
+
+
+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:
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+#### Migrating from Webpack
+
+Storybook provides a migration tool for migrating to this framework from the Webpack-based Next.js framework, `@storybook/nextjs`. To migrate, run this command:
+
+```bash
+npx storybook automigrate nextjs-to-nextjs-vite
+```
+
+This automigration tool performs the following actions:
+
+1. Updates `package.json` files to replace `@storybook/nextjs` with `@storybook/nextjs-vite`
+2. Updates `.storybook/main.js|ts` to change the framework property
+3. Scans and updates import statements in your story files and configuration files
+
+
+
+If 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](../builders/vite.mdx#migrating-from-webpack) for more information.
+
+
+
+## Run the Setup Wizard
+
+If all goes well, you should see a setup wizard that will help you get started with Storybook introducing you to the main concepts and features, including how the UI is organized, how to write your first story, and how to test your components' response to various inputs utilizing [controls](../../essentials/controls.mdx).
+
+
+
+If you skipped the wizard, you can always run it again by adding the `?path=/onboarding` query parameter to the URL of your Storybook instance, provided that the example stories are still available.
+
+## Next.js's Image component
+
+This framework allows you to use Next.js's [next/image](https://nextjs.org/docs/pages/api-reference/components/image) with no configuration.
+
+### Local images
+
+[Local images](https://nextjs.org/docs/pages/building-your-application/optimizing/images#local-images) are supported.
+
+```jsx title="index.jsx"
+import Image from 'next/image';
+import profilePic from '../public/me.png';
+
+function Home() {
+ return (
+ <>
+
My Homepage
+
+
Welcome to my homepage!
+
+ );
+}
+```
+
+### Remote images
+
+[Remote images](https://nextjs.org/docs/pages/building-your-application/optimizing/images#remote-images) are also supported.
+
+```jsx title="index.jsx"
+import Image from 'next/image';
+
+export default function Home() {
+ return (
+ <>
+
My Homepage
+
+
Welcome to my homepage!
+
+ );
+}
+```
+
+## Next.js font optimization
+
+[next/font](https://nextjs.org/docs/pages/building-your-application/optimizing/fonts) is partially supported in Storybook. The packages `next/font/google` and `next/font/local` are supported.
+
+### `next/font/google`
+
+You don't have to do anything. `next/font/google` is supported out of the box.
+
+### `next/font/local`
+
+For local fonts you have to define the [src](https://nextjs.org/docs/pages/building-your-application/optimizing/fonts#local-fonts) property.
+The path is relative to the directory where the font loader function is called.
+
+If the following component defines your localFont like this:
+
+```js title="src/components/MyComponent.js"
+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.
+
+### Not supported features of `next/font`
+
+The following features are not supported (yet). Support for these features might be planned for the future:
+
+* [Support font loaders configuration in next.config.js](https://nextjs.org/docs/pages/building-your-application/optimizing/fonts#local-fonts)
+* [fallback](https://nextjs.org/docs/pages/api-reference/components/font#fallback) option
+* [adjustFontFallback](https://nextjs.org/docs/pages/api-reference/components/font#adjustfontfallback) option
+* [preload](https://nextjs.org/docs/pages/api-reference/components/font#preload) option gets ignored. Storybook handles Font loading its own way.
+* [display](https://nextjs.org/docs/pages/api-reference/components/font#display) option gets ignored. All fonts are loaded with display set to "block" to make Storybook load the font properly.
+
+### Mocking fonts during testing
+
+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](https://github.com/vercel/next.js/blob/725ddc7371f80cca273779d37f961c3e20356f95/packages/font/src/google/fetch-css-from-google-fonts.ts#L36) via a JavaScript module located where the env var `NEXT_FONT_GOOGLE_MOCKED_RESPONSES` references.
+
+For example, using [GitHub Actions](https://www.chromatic.com/docs/github-actions):
+
+```yaml title=".github/workflows/ci.yml"
+- 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:
+
+```js title="mocked-google-fonts.js"
+//π 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 routing
+
+[Next.js's router](https://nextjs.org/docs/pages/building-your-application/routing) is automatically stubbed for you so that when the router is interacted with, all of its interactions are automatically logged to the [Actions panel](../../essentials/actions.mdx).
+
+
+
+You should only use `next/router` in the `pages` directory. In the `app` directory, it is necessary to use `next/navigation`.
+
+
+
+### Overriding defaults
+
+Per-story overrides can be done by adding a `nextjs.router` property onto the story [parameters](../../writing-stories/parameters.mdx). The framework will shallowly merge whatever you put here into the router.
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+
+
+These overrides can also be applied to [all stories for a component](../../api/parameters.mdx#meta-parameters) or [all stories in your project](../../api/parameters.mdx#project-parameters). Standard [parameter inheritance](../../api/parameters.mdx#parameter-inheritance) rules apply.
+
+
+
+### Default router
+
+The default values on the stubbed router are as follows (see [globals](../../essentials/toolbars-and-globals.mdx#globals) for more details on how globals work).
+
+```ts
+// 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](https://nextjs.org/docs/pages/api-reference/functions/use-router#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](https://vitest.dev/api/mock.html).
+
+To override these defaults, you can use [parameters](../../writing-stories/parameters.mdx) and [`beforeEach`](../../writing-stories/mocking-data-and-modules/mocking-modules.mdx#setting-up-and-cleaning-up):
+
+```ts title=".storybook/preview.js|ts"
+import type { Preview } from '@storybook/nextjs-vite';
+
+// π Must include the `.mock` portion of filename to have mocks typed correctly
+import { getRouter } from "@storybook/nextjs-vite/router.mock";
+
+const preview: Preview = {
+ parameters: {
+ nextjs: {
+ // π Override the default router properties
+ router: {
+ basePath: '/app/',
+ },
+ },
+ },
+ async beforeEach() {
+ // π Manipulate the default router method mocks
+ getRouter().push.mockImplementation(() => {
+ /* ... */
+ });
+ },
+};
+```
+
+## Next.js navigation
+
+
+
+Please note that [`next/navigation`](https://nextjs.org/docs/app/building-your-application/routing) can only be used in components/pages in the `app` directory.
+
+
+
+### Set `nextjs.appDirectory` to `true`
+
+If your story imports components that use `next/navigation`, you need to set the parameter `nextjs.appDirectory` to `true` in for that component's stories:
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+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`](../../configure/index.mdx#configure-story-rendering) file to apply it to all stories.
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+### Overriding defaults
+
+Per-story overrides can be done by adding a `nextjs.navigation` property onto the story [parameters](../../writing-stories/parameters.mdx). The framework will shallowly merge whatever you put here into the router.
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+
+
+These overrides can also be applied to [all stories for a component](../../api/parameters.mdx#meta-parameters) or [all stories in your project](../../api/parameters.mdx#project-parameters). Standard [parameter inheritance](../../api/parameters.mdx#parameter-inheritance) rules apply.
+
+
+
+### `useSelectedLayoutSegment`, `useSelectedLayoutSegments`, and `useParams` hooks
+
+The `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.
+
+{/* prettier-ignore-start */}
+
+
+
+With the above configuration, the component rendered in the stories would receive the following values from the hooks:
+
+```js title="NavigationBasedComponent.js"
+import { useSelectedLayoutSegment, useSelectedLayoutSegments, useParams } from 'next/navigation';
+
+export default function NavigationBasedComponent() {
+ const segment = useSelectedLayoutSegment(); // dashboard
+ const segments = useSelectedLayoutSegments(); // ["dashboard", "analytics"]
+ const params = useParams(); // {}
+ // ...
+}
+```
+
+{/* prettier-ignore-end */}
+
+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.
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+With the above configuration, the component rendered in the stories would receive the following values from the hooks:
+
+```js title="ParamsBasedComponent.js"
+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](../../api/parameters.mdx#story-parameters) or [all stories in your project](../../api/parameters.mdx#project-parameters). Standard [parameter inheritance](../../api/parameters.mdx#parameter-inheritance) rules apply.
+
+
+
+The default value of `nextjs.navigation.segments` is `[]` if not set.
+
+### Default navigation context
+
+The default values on the stubbed navigation context are as follows:
+
+```ts
+// Default navigation context
+const defaultNavigationContext = {
+ pathname: '/',
+ query: {},
+};
+```
+
+Additionally, the [`router` object](https://nextjs.org/docs/app/api-reference/functions/use-router#userouter) 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](https://vitest.dev/api/mock.html).
+
+To override these defaults, you can use [parameters](../../writing-stories/parameters.mdx) and [`beforeEach`](../../writing-stories/mocking-data-and-modules/mocking-modules.mdx#setting-up-and-cleaning-up):
+
+```ts title=".storybook/preview.js|ts"
+import type { Preview } from '@storybook/nextjs-vite';
+
+// π Must include the `.mock` portion of filename to have mocks typed correctly
+import { getRouter } from '@storybook/nextjs-vite/navigation.mock';
+
+const preview: Preview = {
+ parameters: {
+ nextjs: {
+ // π Override the default navigation properties
+ navigation: {
+ pathname: '/app/',
+ },
+ },
+ },
+ async beforeEach() {
+ // π Manipulate the default navigation method mocks
+ getRouter().push.mockImplementation(() => {
+ /* ... */
+ });
+ },
+};
+```
+
+## Next.js Head
+
+[`next/head`](https://nextjs.org/docs/pages/api-reference/components/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.
+
+## Sass/Scss
+
+[Global Sass/Scss stylesheets](https://nextjs.org/docs/pages/building-your-application/styling/sass) are supported without any additional configuration as well. Just import them into [`.storybook/preview.js|ts`](../../configure/index.mdx#configure-story-rendering)
+
+```js title=".storybook/preview.js|ts"
+import '../styles/globals.scss';
+```
+
+This will automatically include any of your [custom Sass configurations](https://nextjs.org/docs/pages/building-your-application/styling/sass#customizing-sass-options) in your `next.config.js` file.
+
+```js title="next.config.js"
+import * as path from 'path';
+
+export default {
+ // Any options here are included in Sass compilation for your stories
+ sassOptions: {
+ includePaths: [path.join(process.cwd(), 'styles')],
+ },
+};
+```
+
+## CSS/Sass/Scss Modules
+
+[CSS modules](https://nextjs.org/docs/pages/building-your-application/styling/css-modules) work as expected.
+
+```jsx title="src/components/Button.jsx"
+// This import will work in Storybook
+import styles from './Button.module.css';
+// Sass/Scss is also supported
+// import styles from './Button.module.scss'
+// import styles from './Button.module.sass'
+
+export function Button() {
+ return (
+
+ );
+}
+```
+
+## PostCSS
+
+Next.js lets you [customize PostCSS config](https://nextjs.org/docs/pages/building-your-application/configuring/post-css). Thus this framework will automatically handle your PostCSS config for you.
+
+This allows for cool things like zero-config Tailwind! (See [Next.js' example](https://github.com/vercel/next.js/tree/canary/packages/create-next-app/templates/default-tw))
+
+## Absolute imports
+
+[Absolute imports](https://nextjs.org/docs/pages/building-your-application/configuring/absolute-imports-and-module-aliases#absolute-imports) from the root directory are supported.
+
+```jsx title="index.jsx|tsx"
+// All good!
+import Button from 'components/button';
+// Also good!
+import styles from 'styles/HomePage.module.css';
+
+export default function HomePage() {
+ return (
+ <>
+
Hello World
+
+
+ );
+}
+```
+
+Also OK for global styles in `.storybook/preview.js|ts`!
+
+```js title=".storybook/preview.js|ts"
+import 'styles/globals.scss';
+
+// ...
+```
+
+
+
+Absolute imports **cannot** be mocked in stories/tests. See the [Mocking modules](#mocking-modules) section for more information.
+
+
+
+## Module aliases
+
+[Module aliases](https://nextjs.org/docs/app/building-your-application/configuring/absolute-imports-and-module-aliases#module-aliases) are also supported.
+
+```jsx title="index.jsx|tsx"
+// All good!
+import Button from '@/components/button';
+// Also good!
+import styles from '@/styles/HomePage.module.css';
+
+export default function HomePage() {
+ return (
+ <>
+
Hello World
+
+
+ );
+}
+```
+
+## Subpath imports
+
+As an alternative to [module aliases](#module-aliases), you can use [subpath imports](https://nodejs.org/api/packages.html#subpath-imports) to import modules. This follows Node package standards and has benefits when [mocking modules](#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:
+
+```json title="package.json"
+{
+ "imports": {
+ "#*": ["./*", "./*.ts", "./*.tsx"]
+ }
+}
+```
+
+
+
+Because subpath imports replace module aliases, you can remove the path aliases from your TypeScript configuration.
+
+
+
+Which can then be used like this:
+
+```jsx title="index.jsx|tsx"
+import Button from '#components/button';
+import styles from '#styles/HomePage.module.css';
+
+export default function HomePage() {
+ return (
+ <>
+
Hello World
+
+
+ );
+}
+```
+
+## Mocking modules
+
+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](../../writing-stories/mocking-data-and-modules/mocking-modules.mdx) to control and assert their behavior.
+
+### Built-in mocked modules
+
+This framework provides mocks for many of Next.js' internal modules:
+
+1. [`@storybook/nextjs-vite/cache.mock`](#storybooknextjs-vitecachemock)
+2. [`@storybook/nextjs-vite/headers.mock`](#storybooknextjs-viteheadersmock)
+3. [`@storybook/nextjs-vite/navigation.mock`](#storybooknextjs-vitenavigationmock)
+4. [`@storybook/nextjs-vite/router.mock`](#storybooknextjs-viteroutermock)
+
+### Mocking other modules
+
+To mock other modules, use [automocking](../../writing-stories/mocking-data-and-modules/mocking-modules.mdx#automocking) or one of the [alternative methods](../../writing-stories/mocking-data-and-modules/mocking-modules.mdx#alternative-methods) documented in the mocking modules guide.
+
+## Runtime config
+
+Next.js allows for [Runtime Configuration](https://nextjs.org/docs/pages/api-reference/next-config-js/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](https://nextjs.org/docs/pages/api-reference/next-config-js/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:
+
+```js title="next.config.js"
+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:
+
+```jsonc
+// Runtime config
+{
+ "serverRuntimeConfig": {},
+ "publicRuntimeConfig": {
+ "staticFolder": "/static"
+ }
+}
+```
+
+## Custom Vite configuration
+
+You can customize the [Vite configuration](../../builders/vite.mdx#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](https://vitejs.dev/guide/).
+
+## Typescript
+
+Storybook handles most [Typescript](https://www.typescriptlang.org/) configurations, but this framework adds additional support for Next.js's support for [Absolute Imports and Module path aliases](https://nextjs.org/docs/pages/building-your-application/configuring/absolute-imports-and-module-aliases). In short, it takes into account your `tsconfig.json`'s [baseUrl](https://www.typescriptlang.org/tsconfig#baseUrl) and [paths](https://www.typescriptlang.org/tsconfig#paths). Thus, a `tsconfig.json` like the one below would work out of the box.
+
+```json title="tsconfig.json"
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "paths": {
+ "@/components/*": ["components/*"]
+ }
+ }
+}
+```
+
+## React Server Components (RSC)
+
+(β οΈ **Experimental**)
+
+If your app uses [React Server Components (RSC)](https://nextjs.org/docs/app/building-your-application/rendering/server-components), Storybook can render them in stories in the browser.
+
+To enable this set the `experimentalRSC` feature flag in your `.storybook/main.js|ts` config:
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+Setting this flag automatically wraps your story in a [Suspense](https://react.dev/reference/react/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](https://storybook.js.org/docs/writing-stories/parameters) at the global/component/story level:
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+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](https://vitejs.dev/config/shared-options.html#resolve-alias) or an addon like [storybook-addon-module-mock](https://storybook.js.org/addons/storybook-addon-module-mock).
+
+If your server components access data via the network, we recommend using the [MSW Storybook Addon](https://storybook.js.org/addons/msw-storybook-addon) to mock network requests.
+
+In the future we will provide better mocking support in Storybook and support for [Server Actions](https://nextjs.org/docs/app/api-reference/functions/server-actions).
+
+## FAQ
+
+### Stories for pages/components which fetch data
+
+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](https://vitejs.dev/config/dep-optimization-options.html#optimizedeps-exclude) in your Storybook's [`viteFinal` configuration](../../builders/vite.mdx#configuration).
+
+**Before**
+
+```jsx title="app/my-page/index.jsx"
+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**
+
+```jsx title="app/my-page/index.jsx"
+// 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 ;
+}
+```
+
+### Statically imported images won't load
+
+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:
+
+```jsonc
+// 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](https://nextjs.org/docs/pages/building-your-application/optimizing/images#local-images) for more detail on how Next.js treats static image imports.
+
+### Error: You are importing avif images, but you don't have sharp installed. You have to install sharp in order to use image optimization features in Next.js.
+
+`sharp` is a dependency of Next.js's image optimization feature. If you see this error, you need to install `sharp` in your project.
+
+```bash
+npm install sharp
+```
+
+```bash
+yarn add sharp
+```
+
+```bash
+pnpm add sharp
+```
+
+You can refer to the [Install `sharp` to Use Built-In Image Optimization](https://nextjs.org/docs/messages/install-sharp) in the Next.js documentation for more information.
+
+### Should I use the Vite or Webpack version?
+
+We recommend using `@storybook/nextjs-vite` (this framework) for most projects because it offers:
+
+* Faster builds and development server startup
+* Better support for modern testing features like the [Vitest addon](../../writing-tests/integrations/vitest-addon.mdx)
+* Simpler configuration without Babel
+* Better developer experience with faster HMR
+
+However, if your project has custom Webpack configurations that are incompatible with Vite, or you need specific Webpack features, you should use [`@storybook/nextjs`](./nextjs.mdx) (Webpack 5) instead.
+
+## API
+
+### Modules
+
+The `@storybook/nextjs-vite` package exports several modules that enable you to [mock](#mocking-modules) Next.js's internal behavior.
+
+#### `@storybook/nextjs-vite/cache.mock`
+
+Type: `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](../../writing-stories/play-function.mdx).
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+#### `@storybook/nextjs-vite/headers.mock`
+
+Type: [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies#cookiessetname-value-options), [`headers`](https://nextjs.org/docs/app/api-reference/functions/headers) and [`draftMode`](https://nextjs.org/docs/app/api-reference/functions/draft-mode) 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()`](https://nextjs.org/docs/app/api-reference/functions/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 header
+* **`headers().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](https://vitest.dev/api/mock.html) in your stories, like `headers().getAll.mock.calls`.
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+#### `@storybook/nextjs-vite/navigation.mock`
+
+Type: `typeof import('next/navigation') & getRouter: () => ReturnType`
+
+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`](https://nextjs.org/docs/app/api-reference/functions/use-router#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](../../writing-stories/play-function.mdx).
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+#### `@storybook/nextjs-vite/router.mock`
+
+Type: `typeof import('next/router') & getRouter: () => ReturnType`
+
+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`](https://nextjs.org/docs/pages/api-reference/functions/use-router#router-object), 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](../../writing-stories/play-function.mdx).
+
+{/* prettier-ignore-start */}
+
+
+
+{/* prettier-ignore-end */}
+
+### Options
+
+You can pass an options object for additional configuration if needed:
+
+```js title=".storybook/main.js"
+import * as path from 'path';
+
+export default {
+ // ...
+ framework: {
+ name: '@storybook/nextjs-vite',
+ options: {
+ image: {
+ loading: 'eager',
+ },
+ nextConfigPath: path.resolve(process.cwd(), 'next.config.js'),
+ },
+ },
+};
+```
+
+The available options are:
+
+#### `builder`
+
+Type: `Record`
+
+Configure options for the [framework's builder](../../api/main-config/main-config-framework.mdx#optionsbuilder). For Next.js with Vite, available options can be found in the [Vite builder docs](../../builders/vite.mdx).
+
+#### `image`
+
+Type: `object`
+
+Props to pass to every instance of `next/image`. See [next/image docs](https://nextjs.org/docs/pages/api-reference/components/image) for more details.
+
+#### `nextConfigPath`
+
+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.
+
+### Parameters
+
+This framework contributes the following [parameters](../../writing-stories/parameters.mdx) to Storybook, under the `nextjs` namespace:
+
+#### `appDirectory`
+
+Type: `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](../../api/parameters.mdx#story-parameters), [all stories for a component](../../api/parameters.mdx#meta-parameters), or [every story in your Storybook](../../api/parameters.mdx#project-parameters). See [Next.js Navigation](#nextjs-navigation) for more details.
+
+#### `navigation`
+
+Type:
+
+```ts
+{
+ asPath?: string;
+ pathname?: string;
+ query?: Record;
+ segments?: (string | [string, string])[];
+}
+```
+
+Default value:
+
+```js
+{
+ segments: [];
+}
+```
+
+The router object that is passed to the `next/navigation` context. See [Next.js's navigation docs](https://nextjs.org/docs/app/building-your-application/routing) for more details.
+
+#### `router`
+
+Type:
+
+```ts
+{
+ asPath?: string;
+ pathname?: string;
+ query?: Record;
+}
+```
+
+The router object that is passed to the `next/router` context. See [Next.js's router docs](https://nextjs.org/docs/pages/building-your-application/routing) for more details.
+
diff --git a/docs/get-started/frameworks/nextjs.mdx b/docs/get-started/frameworks/nextjs.mdx
index 208cfce1e302..01e583d9b668 100644
--- a/docs/get-started/frameworks/nextjs.mdx
+++ b/docs/get-started/frameworks/nextjs.mdx
@@ -1,12 +1,12 @@
---
-title: Storybook for Next.js
+title: Storybook for Next.js with Webpack
hideRendererSelector: true
sidebar:
- order: 2
- title: Next.js
+ order: 3
+ title: Next.js (Webpack)
---
-Storybook for Next.js is a [framework](../../contribute/framework.mdx) that makes it easy to develop and test UI components in isolation for [Next.js](https://nextjs.org/) applications. It includes:
+Storybook for Next.js (Webpack) is a [framework](../../contribute/framework.mdx) that makes it easy to develop and test UI components in isolation for [Next.js](https://nextjs.org/) applications using Webpack 5. It includes:
* π Routing
* πΌ Image optimization
@@ -15,6 +15,17 @@ Storybook for Next.js is a [framework](../../contribute/framework.mdx) that make
* π Webpack & Babel config
* π« and more!
+
+
+**We recommend using [`@storybook/nextjs-vite`](./nextjs-vite.mdx)** for most Next.js projects. The Vite-based framework is faster, more modern, and offers better support for testing features.
+
+Use this Webpack-based framework (`@storybook/nextjs`) only if:
+- Your project has custom Webpack configurations that are incompatible with Vite
+- Your project has custom Babel configurations that require Webpack
+- You need specific Webpack features not available in Vite
+
+
+
## Requirements
* Next.js β₯ 14.1
@@ -23,6 +34,21 @@ Storybook for Next.js is a [framework](../../contribute/framework.mdx) that make
### In a project without Storybook
+When you run `storybook init` in your Next.js project, Storybook will automatically detect your project and select the [`@storybook/nextjs-vite`](./nextjs-vite.mdx) framework (which we recommend) unless your project has custom Webpack or Babel configurations that may be incompatible with Vite.
+
+
+
+If your project has custom Webpack/Babel configurations
+
+If `storybook init` detects a custom Webpack configuration in your Next.js config file or `.babelrc` file, it will prompt you to choose between:
+
+- **`@storybook/nextjs-vite`** (recommended) - Faster, more modern, supports latest testing features, but may be incompatible with your custom Webpack/Babel config
+- **`@storybook/nextjs`** (Webpack 5) - Better compatibility with custom Webpack/Babel configurations
+
+Choose `@storybook/nextjs` (Webpack 5) if you need to keep your existing Webpack/Babel setup and cannot migrate to Vite.
+
+
+
Follow the prompts after running this command in your Next.js project's root directory:
{/* prettier-ignore-start */}
@@ -73,37 +99,9 @@ Finally, if you were using Storybook plugins to integrate with Next.js, those ar
{/* prettier-ignore-end */}
-#### With Vite
-
-Storybook recommends using the `@storybook/nextjs-vite` framework, which is based on Vite and removes the need for Webpack and Babel. It supports all of the features documented here.
-
-{/* prettier-ignore-start */}
-
-
-
-{/* prettier-ignore-end */}
-
-Then, update your `.storybook/main.js|ts` to change the framework property:
-
-{/* prettier-ignore-start */}
-
-
-
-{/* prettier-ignore-end */}
-
-
- If your Storybook configuration contains custom Webpack operations in [`webpackFinal`](../../api/main-config/main-config-webpack-final.mdx), you will likely need to create equivalents in [`viteFinal`](../../api/main-config/main-config-vite-final.mdx).
+#### Migrating to Vite
- For more information, see the [Vite builder documentation](../../builders/vite.mdx#migrating-from-webpack).
-
-
-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:
-
-{/* prettier-ignore-start */}
-
-
-
-{/* prettier-ignore-end */}
+Please refer to the [migration instructions for `@storybook/nextjs-vite`](./nextjs-vite.mdx#migrating-from-webpack).
## Run the Setup Wizard
@@ -184,10 +182,6 @@ const localRubikStorm = localFont({ src: './fonts/RubikStorm-Regular.ttf' });
#### `staticDir` mapping
-
- You can safely skip this section if you are using [`@storybook/nextjs-vite`](#with-vite) instead of `@storybook/nextjs`. The Vite-based framework takes care of the mapping automatically.
-
-
You have to tell Storybook where the `fonts` directory is located, via the [`staticDirs` configuration](../../api/main-config/main-config-static-dirs.mdx#with-configuration-objects). The `from` value is relative to the `.storybook` directory. The `to` value is relative to the execution context of Storybook. Very likely it is the root of your project.
{/* prettier-ignore-start */}
@@ -298,11 +292,10 @@ Additionally, the [`router` object](https://nextjs.org/docs/pages/api-reference/
To override these defaults, you can use [parameters](../../writing-stories/parameters.mdx) and [`beforeEach`](../../writing-stories/mocking-data-and-modules/mocking-modules.mdx#setting-up-and-cleaning-up):
```ts title=".storybook/preview.js|ts"
-// Replace your-framework with nextjs or nextjs-vite
-import type { Preview } from '@storybook/your-framework';
+import type { Preview } from '@storybook/nextjs';
// π Must include the `.mock` portion of filename to have mocks typed correctly
-import { getRouter } from "@storybook/your-framework/router.mock";
+import { getRouter } from "@storybook/nextjs/router.mock";
const preview: Preview = {
parameters: {
@@ -427,11 +420,10 @@ Additionally, the [`router` object](https://nextjs.org/docs/app/api-reference/fu
To override these defaults, you can use [parameters](../../writing-stories/parameters.mdx) and [`beforeEach`](../../writing-stories/mocking-data-and-modules/mocking-modules.mdx#setting-up-and-cleaning-up):
```ts title=".storybook/preview.js|ts"
-// Replace your-framework with nextjs or nextjs-vite
-import type { Preview } from '@storybook/your-framework';
+import type { Preview } from '@storybook/nextjs';
// π Must include the `.mock` portion of filename to have mocks typed correctly
-import { getRouter } from '@storybook/your-framework/navigation.mock';
+import { getRouter } from '@storybook/nextjs/navigation.mock';
const preview: Preview = {
parameters: {
@@ -695,11 +687,6 @@ Calls to `getConfig` would return the following object when called within Storyb
## Custom Webpack config
-
- You can safely skip this section if you are using `@storybook/nextjs-vite` instead of `@storybook/nextjs`.
- The Vite-based Next.js framework does not support Webpack settings.
-
-
Next.js comes with a lot of things for free out of the box like Sass support, but sometimes you add [custom Webpack config modifications to Next.js](https://nextjs.org/docs/pages/api-reference/next-config-js/webpack). This framework takes care of most of the Webpack modifications you would want to add. If Next.js supports a feature out of the box, then that feature will work out of the box in Storybook. If Next.js doesn't support something out of the box, but makes it easy to configure, then this framework will do the same for that thing for Storybook.
Any Webpack modifications desired for Storybook should be made in [`.storybook/main.js|ts`](../../builders/webpack.mdx#extending-storybooks-webpack-config).
@@ -840,9 +827,9 @@ See [local images](https://nextjs.org/docs/pages/building-your-application/optim
You might get this if you're using Yarn v2 or v3. See [Notes for Yarn v2 and v3 users](#notes-for-yarn-v2-and-v3-users) for more details.
-### What if I'm using the Vite builder?
+### Should I use the Vite or Webpack version?
-Storybook provides a Vite-based framework for Next.js. Follow the [installation instructions](#with-vite) and replace all instances of `@storybook/nextjs` with `@storybook/nextjs-vite`.
+We recommend using [`@storybook/nextjs-vite`](./nextjs-vite.mdx) (Vite-based) for most projects because it offers faster builds, better test support, and a simpler configuration. However, if your project has custom Webpack configurations that are incompatible with Vite, use this framework instead.
### Error: You are importing avif images, but you don't have sharp installed. You have to install sharp in order to use image optimization features in Next.js.
@@ -866,7 +853,7 @@ You can refer to the [Install `sharp` to Use Built-In Image Optimization](https:
### Modules
-The `@storybook/nextjs`Β package exportsΒ several modules that enableΒ you to [mock](#mocking-modules) Next.js's internal behavior.
+The `@storybook/nextjs` package exports several modules that enable you to [mock](#mocking-modules) Next.js's internal behavior.
#### `@storybook/nextjs/export-mocks`
@@ -961,11 +948,10 @@ You can pass an options object for additional configuration if needed:
```js title=".storybook/main.js"
import * as path from 'path';
-// Replace your-framework with nextjs or nextjs-vite
export default {
// ...
framework: {
- name: '@storybook/your-framework',
+ name: '@storybook/nextjs',
options: {
image: {
loading: 'eager',
diff --git a/docs/get-started/frameworks/preact-vite.mdx b/docs/get-started/frameworks/preact-vite.mdx
index 5c219e2a30a7..0446cb48d8d0 100644
--- a/docs/get-started/frameworks/preact-vite.mdx
+++ b/docs/get-started/frameworks/preact-vite.mdx
@@ -1,9 +1,9 @@
---
-title: Storybook for Preact & Vite
+title: Storybook for Preact with Vite
hideRendererSelector: true
sidebar:
- order: 3
- title: Preact & Vite
+ order: 4
+ title: Preact (Vite)
---
Storybook for Preact & Vite is a [framework](../../contribute/framework.mdx) that makes it easy to develop and test UI components in isolation for [Preact](https://preactjs.com/) applications built with [Vite](https://vitejs.dev/). It includes:
diff --git a/docs/get-started/frameworks/react-native-web-vite.mdx b/docs/get-started/frameworks/react-native-web-vite.mdx
index e7ea86eaa857..8d1acd47b1ca 100644
--- a/docs/get-started/frameworks/react-native-web-vite.mdx
+++ b/docs/get-started/frameworks/react-native-web-vite.mdx
@@ -2,7 +2,7 @@
title: Storybook for React Native Web
hideRendererSelector: true
sidebar:
- order: 6
+ order: 7
title: React Native Web
---
@@ -27,6 +27,25 @@ Storybook for React Native Web is a [framework](../../contribute/framework.mdx)
### In a project without Storybook
+When you run `storybook init` in your React Native project, Storybook will detect your project and present you with a prompt to choose which type of Storybook you want to install:
+
+**React Native options:**
+
+- **"React Native"**: Storybook on your device/simulator
+ - High-fidelity, runs in your actual React Native application
+ - Limited feature set compared to web version
+ - Best for projects that rely on native modules or device-specific features
+
+- **"React Native Web"**: Storybook on web for docs, test, and sharing
+ - Feature-rich web-based Storybook
+ - Full support for documentation, testing, and accessibility features
+ - Best for projects that want web-based sharing and testing
+
+- **"Both"**: Add both native and web Storybooks
+ - Installs and configures both environments
+ - Allows you to run Storybook for both native and web in the same project
+ - Best for projects that want both native fidelity and web features
+
Follow the prompts after running this command in your React Native project's root directory:
{/* prettier-ignore-start */}
@@ -116,7 +135,16 @@ So, which option is right for you?
## Using both React Native and React Native Web
-The easiest way to use React Native and React Native Web is to select the "Both" option when installing Storybook. This will install and create configurations for both environments, allowing you to run Storybook for both in the same project.
+The easiest way to use React Native and React Native Web is to select the **"Both"** option when installing Storybook. This will install and create configurations for both environments, allowing you to run Storybook for both in the same project.
+
+When you select "Both", the installation will:
+1. Install and configure React Native Storybook (on-device)
+2. Install and configure React Native Web Storybook (web-based)
+3. Set up both configurations in your project
+
+After installation, you'll see instructions for both environments:
+- React Native Storybook will require additional manual configuration steps (replacing app entry, wrapping metro config)
+- React Native Web Storybook can be started immediately using the `storybook` command
However, you can install them separately if one version is installed. You can add a React Native Web Storybook alongside an existing React Native Storybook by running the install command and selecting "React Native Web" in the setup wizard, and vice versa.
diff --git a/docs/get-started/frameworks/react-vite.mdx b/docs/get-started/frameworks/react-vite.mdx
index f4c78d57009e..0f57a8115432 100644
--- a/docs/get-started/frameworks/react-vite.mdx
+++ b/docs/get-started/frameworks/react-vite.mdx
@@ -1,9 +1,9 @@
---
-title: Storybook for React & Vite
+title: Storybook for React with Vite
hideRendererSelector: true
sidebar:
- order: 4
- title: React & Vite
+ order: 5
+ title: React (Vite)
---
Storybook for React & Vite is a [framework](../../contribute/framework.mdx) that makes it easy to develop and test UI components in isolation for [React](https://react.dev/) applications built with [Vite](https://vitejs.dev/). It includes:
diff --git a/docs/get-started/frameworks/react-webpack5.mdx b/docs/get-started/frameworks/react-webpack5.mdx
index e66ae4c64932..90c9792f5f5a 100644
--- a/docs/get-started/frameworks/react-webpack5.mdx
+++ b/docs/get-started/frameworks/react-webpack5.mdx
@@ -1,9 +1,9 @@
---
-title: Storybook for React & Webpack
+title: Storybook for React with Webpack
hideRendererSelector: true
sidebar:
- order: 5
- title: React & Webpack
+ order: 6
+ title: React (Webpack)
---
Storybook for React & Webpack is a [framework](../../contribute/framework.mdx) that makes it easy to develop and test UI components in isolation for [React](https://react.dev/) applications built with [Webpack](https://webpack.js.org/).
diff --git a/docs/get-started/frameworks/svelte-vite.mdx b/docs/get-started/frameworks/svelte-vite.mdx
index f38d41573155..d02e46d9feae 100644
--- a/docs/get-started/frameworks/svelte-vite.mdx
+++ b/docs/get-started/frameworks/svelte-vite.mdx
@@ -1,9 +1,9 @@
---
-title: Storybook for Svelte & Vite
+title: Storybook for Svelte with Vite
hideRendererSelector: true
sidebar:
- order: 8
- title: Svelte & Vite
+ order: 9
+ title: Svelte (Vite)
---
Storybook for Svelte & Vite is a [framework](../../contribute/framework.mdx) that makes it easy to develop and test UI components in isolation for applications using [Svelte](https://svelte.dev/) built with [Vite](https://vitejs.dev/).
diff --git a/docs/get-started/frameworks/sveltekit.mdx b/docs/get-started/frameworks/sveltekit.mdx
index 84b787e96a3c..47c459b16b4a 100644
--- a/docs/get-started/frameworks/sveltekit.mdx
+++ b/docs/get-started/frameworks/sveltekit.mdx
@@ -2,7 +2,7 @@
title: Storybook for SvelteKit
hideRendererSelector: true
sidebar:
- order: 7
+ order: 8
title: SvelteKit
---
diff --git a/docs/get-started/frameworks/vue3-vite.mdx b/docs/get-started/frameworks/vue3-vite.mdx
index f51e3c8f50a2..85e864bfcc0e 100644
--- a/docs/get-started/frameworks/vue3-vite.mdx
+++ b/docs/get-started/frameworks/vue3-vite.mdx
@@ -1,9 +1,9 @@
---
-title: Storybook for Vue & Vite
+title: Storybook for Vue with Vite
hideRendererSelector: true
sidebar:
- order: 9
- title: Vue & Vite
+ order: 10
+ title: Vue (Vite)
---
Storybook for Vue & Vite is a [framework](../../contribute/framework.mdx) that makes it easy to develop and test UI components in isolation for [Vue](https://vuejs.org/) applications built with [Vite](https://vitejs.dev/). It includes:
diff --git a/docs/get-started/frameworks/web-components-vite.mdx b/docs/get-started/frameworks/web-components-vite.mdx
index f228ec9fc270..91705283d339 100644
--- a/docs/get-started/frameworks/web-components-vite.mdx
+++ b/docs/get-started/frameworks/web-components-vite.mdx
@@ -1,9 +1,9 @@
---
-title: Storybook for Web components & Vite
+title: Storybook for Web components with Vite
hideRendererSelector: true
sidebar:
- order: 10
- title: Web components & Vite
+ order: 11
+ title: Web components (Vite)
---
Storybook for Web components & Vite is a [framework](../../contribute/framework.mdx) that makes it easy to develop and test UI components in isolation for applications using [Web components](https://www.webcomponents.org/introduction) built with [Vite](https://vitejs.dev/).
diff --git a/docs/get-started/install.mdx b/docs/get-started/install.mdx
index d33a5b017e3f..cfd6809002f0 100644
--- a/docs/get-started/install.mdx
+++ b/docs/get-started/install.mdx
@@ -7,50 +7,10 @@ sidebar:
Use the Storybook CLI to install it in a single command. Run this inside your projectβs root directory:
-{/* prettier-ignore-start */}
-
-{/* prettier-ignore-end */}
-
-
- Install a specific version
-
- For installing Storybook 8.3 or newer, you can use the `create` command with a specific version:
-
- {/* prettier-ignore-start */}
-
-
-
- {/* prettier-ignore-end */}
-
- To install a Storybook version prior to 8.3, you must use the `init` command:
-
- {/* prettier-ignore-start */}
-
-
-
- {/* prettier-ignore-end */}
-
- For either command, you can specify either an npm tag such as `latest` or `next`, or a (partial) version number. For example:
-
- * `storybook@latest init` will initialize the latest version
- * `storybook@7.6.10 init` will initialize `7.6.10`
- * `storybook@7 init` will initialize the newest `7.x.x` version
-
-
-
-
Storybook will look into your project's dependencies during its install process and provide you with the best configuration available.
-The command above will make the following changes to your local environment:
-
-* π¦ Install the required dependencies.
-* π Setup the necessary scripts to run and build Storybook.
-* π Add the default Storybook configuration.
-* π Add some boilerplate stories to get you started.
-* π‘ Set up telemetry to help us improve Storybook. Read more about it [here](../configure/telemetry.mdx).
-
## Project requirements
@@ -95,6 +55,71 @@ You can use Storybook with older browsers in two ways:
+## Installation
+
+Run this command inside your project's root directory to install the latest version of Storybook:
+
+
+
+
+ Install a specific version
+
+ For installing Storybook 8.3 or newer, you can use the `create` command with a specific version:
+
+ {/* prettier-ignore-start */}
+
+
+
+ {/* prettier-ignore-end */}
+
+ To install a Storybook version prior to 8.3, you must use the `init` command:
+
+ {/* prettier-ignore-start */}
+
+
+
+ {/* prettier-ignore-end */}
+
+ For either command, you can specify either an npm tag such as `latest` or `next`, or a (partial) version number. For example:
+
+ * `storybook@latest init` will initialize the latest version
+ * `storybook@7.6.10 init` will initialize `7.6.10`
+ * `storybook@7 init` will initialize the newest `7.x.x` version
+
+
+
+When installing, Storybook will present you with a series of interactive prompts to help customize your installation:
+
+**New to Storybook?**
+
+Storybook will ask if you're new to Storybook. If you select "Yes":
+
+* You will be welcomed with an interactive tour
+* Example stories will be created to help you learn
+
+If you're experienced with Storybook, you can skip the onboarding to get a minimal setup.
+
+**What configuration should we install?**
+
+Storybook will ask what type of configuration you want to install:
+
+* **Recommended**: Includes component development, [documentation](../writing-docs/autodocs.mdx), [testing](../writing-tests/integrations/vitest-addon.mdx), and [accessibility](../writing-tests/accessibility-testing.mdx) features
+* **Minimal**: Just the essentials for component development
+
+You can also manually select these features using the `--features` flag. For example:
+
+```bash
+npm create storybook@latest --features docs test a11y
+```
+
+After completing the prompts, the command above will make the following changes to your local environment:
+
+* π¦ Install the required dependencies.
+* π Set up the necessary scripts to run and build Storybook.
+* π Add the default Storybook configuration.
+* π Add some boilerplate stories to get you started.
+* π‘ Set up telemetry to help us improve Storybook. Read more about it [here](../configure/telemetry.mdx).
+
## Run the Setup Wizard
diff --git a/docs/writing-tests/accessibility-testing.mdx b/docs/writing-tests/accessibility-testing.mdx
index fbc0af4b00bd..592ffb9d6adf 100644
--- a/docs/writing-tests/accessibility-testing.mdx
+++ b/docs/writing-tests/accessibility-testing.mdx
@@ -33,6 +33,48 @@ Your Storybook will now include some features to check the accessibility of your
+### Integration with Vitest addon
+
+The accessibility addon is designed to integrate with the [Vitest addon](./integrations/vitest-addon.mdx), so that you can [run accessibility tests](#run-accessibility-tests) alongside your component tests.
+
+**Automatic configuration:**
+
+When you run `npx storybook add @storybook/addon-vitest` in a project that already has `@storybook/addon-a11y` installed, Storybook will automatically:
+
+1. Update `.storybook/vitest.setup.ts` to include the Accessibility addon's annotations
+2. Configure accessibility tests to run alongside component tests
+
+This allows you to run accessibility tests automatically with your component tests in both the Storybook UI and in CI environments.
+
+**Manual configuration:**
+
+If you need to configure this manually (for example, if the automigration was skipped), you can add the following to your `.storybook/vitest.setup.ts`:
+
+```ts
+import * as previewAnnotations from '@storybook/preview-api';
+// Replace your-renderer with the renderer you are using, e.g. react, svelte, vue3, etc.
+import { setProjectAnnotations } from '@storybook/your-renderer';
+import * as a11yAddonAnnotations from '@storybook/addon-a11y/preview';
+
+const annotations = setProjectAnnotations([
+ previewAnnotations,
+ a11yAddonAnnotations,
+]);
+
+// Run Storybook's beforeAll hook
+beforeAll(annotations.beforeAll);
+```
+
+
+
+
+
+If you are using [CSF Factories](../api/csf/csf-next.mdx) for _all_ of the stories in your Storybook, you do not need to update `.storybook/vitest.setup.ts`.
+
+
+
+
+
## Check for violations
When you navigate to a story, automated accessibility checks are run and the results are reported in the Accessibility addon panel.
diff --git a/docs/writing-tests/integrations/vitest-addon.mdx b/docs/writing-tests/integrations/vitest-addon.mdx
index 50148d992e2c..8fa89ae17263 100644
--- a/docs/writing-tests/integrations/vitest-addon.mdx
+++ b/docs/writing-tests/integrations/vitest-addon.mdx
@@ -34,27 +34,46 @@ You can also run tests in watch mode, which will automatically re-run tests when
Before installing, make sure your project meets the following requirements:
-- A Storybook framework that uses Vite (e.g. [`vue3-vite`](../../get-started/frameworks/vue3-vite.mdx), [`react-vite`](../../get-started/frameworks/react-vite.mdx), [`preact-vite`](../../get-started/frameworks/preact-vite.mdx), [`nextjs-vite`](../../get-started/frameworks/nextjs.mdx#with-vite), [`sveltekit`](../../get-started/frameworks/sveltekit.mdx), etc.)
+- A Storybook framework that uses Vite (e.g. [`vue3-vite`](../../get-started/frameworks/vue3-vite.mdx), [`react-vite`](../../get-started/frameworks/react-vite.mdx), [`preact-vite`](../../get-started/frameworks/preact-vite.mdx), [`nextjs-vite`](../../get-started/frameworks/nextjs-vite.mdx), [`sveltekit`](../../get-started/frameworks/sveltekit.mdx), etc.)
- Vitest β₯ 3.0
- - If you're not yet using Vitest, it will be installed and configured for you when you install the addon
+ - If you're not yet using Vitest, it will be installed and configured for you automatically
- (optional) MSW β₯ 2.0
- If MSW is installed, it must be v2.0.0 or later to not conflict with Vitest's dependency
- **Using with Next.js** β The Vitest addon is supported in Next.js β₯ 14.1 projects, but you must be using the [`@storybook/nextjs-vite` framework](../../get-started/frameworks/nextjs.mdx#with-vite). When you run the setup command below, you will be prompted to install and use the framework if you haven't already.
+ **Using with Next.js** β The Vitest addon is supported in Next.js β₯ 14.1 projects, but you must be using the [`@storybook/nextjs-vite` framework](../../get-started/frameworks/nextjs-vite.mdx). If you are using the [`@storybook/nextjs` framework](../../get-started/frameworks/nextjs.mdx), you will need to [migrate to the Vite-based framework](../../get-started/frameworks/nextjs-vite.mdx#migrating-from-webpack) to use the Vitest addon.
### Automatic setup
-Run the following command to install and configure the addon, which contains the plugin to run your stories as tests using Vitest:
+Run the following command to install and configure the addon automatically:
-That [`add` command](../../addons/install-addons.mdx#automatic-installation) will install and register the Vitest addon. It will also inspect your project's Vite and Vitest setup, and install and configure them with sensible defaults, if necessary. You may need to adjust the configuration to fit your project's needs. The full configuration options can be found in the [API section](#options), below.
+The [`add` command](../../addons/install-addons.mdx#automatic-installation) will:
-### Manual setup
+* Install and register the Vitest addon
+* Inspect your project's Vite and Vitest setup
+* Install and configure Vitest with sensible defaults if necessary
+* Set up browser mode using Playwright's Chromium browser
+* **Prompt you to install Playwright browser binaries** if needed
+
+The setup is fully automated and handles all configuration for you. The full configuration options can be found in the [API section](#options), below.
+
+
+
+If you're prompted to install Playwright browser binaries during setup, select "Yes" to install them. These are required for running tests in browser mode, which is the recommended setup for component testing.
+
+You can install the Playwright browser binaries at any time by running [`playwright install`](https://playwright.dev/docs/browsers#install-browsers).
+
+
+
+### Manual setup (advanced)
+
+
+Manual setup instructions (only needed if automatic setup fails)
For some project setups, the `add` command may be unable to automate the addon and plugin setup and ask you to complete additional setup steps. Here's what to do:
@@ -65,6 +84,8 @@ For some project setups, the `add` command may be unable to automate the addon a
1. Adjust your Vitest configuration to include the plugin and reference the setup file. You can use the [example configuration files](#example-configuration-files) as a guide.
- For projects with existing Vitest tests, we recommend using a separate [test project](https://vitest.dev/guide/projects) if you're using Vitest β₯ 4.0 and a [workspace file](https://v3.vitest.dev/config/#workspace) if you're using Vitest 3.x to define separate configurations for your Storybook tests and other tests. You can run them in isolation or together, depending on your needs.
+
+
### Example configuration files
When the addon is set up automatically, it will create or adjust your Vitest configuration files for you. If you're setting up manually, you can use the following examples as a reference when configuring your project.