Setup
Installation
The Storybook CLI provides a convenient way to integrate Storybook with Nuxt. Run the following command in your project's root directory:
pnpm dlx storybook@next init
yarn dlx storybook@next init
npx storybook@next init
This command installs Storybook along with the Nuxt module, sets up the scripts and configuration files, and adds some boilerplate stories to get you started. Please check the Storybook documentation for more information.
next tag until its release: storybook@latest still installs Storybook 10, which only works with v10 of the module.Alternatively, you can install Storybook and the Nuxt module manually.
- Add
@nuxtjs/storybookas a development dependency to your project:
npx nuxi@latest module add storybook
pnpm i -D @nuxtjs/storybook @storybook-vue/nuxt storybook@next
yarn add -D @nuxtjs/storybook @storybook-vue/nuxt storybook@next
npm install -D @nuxtjs/storybook @storybook-vue/nuxt storybook@next
- If not using
nuxiabove, add the module@nuxtjs/storybookto your Nuxt configuration:
export default defineNuxtConfig({
modules: ['@nuxtjs/storybook'],
})
- Create the Storybook config files.
The manual installation method is useful if you want to use a specific version of Storybook. The following versions of Storybook are compatible with the Nuxt module:
| Module Version | Storybook | Nuxt | Node.js |
|---|---|---|---|
| v11.x | 11.x | 4.x / 5.x | 22+ |
| v10.x | 10.x | 3.18.1+ / 4.x | 22+ |
| v9.x | 8.x / 9.x | 3.x | 20+ |
| v4.x | 6.x | 2.x |
Upgrading from v10? See the migration guide.
Usage
When you run your Nuxt app in development mode, Storybook is served by the Nuxt dev server itself, on the same host and port, under /_storybook/ by default. The URL is displayed in the console.
If you want to start Storybook without running your Nuxt app, you can use the following command:
pnpm storybook
yarn storybook
npm run storybook
storybook dev -p 6006
When you install Storybook using the CLI, you will find a few stories in the stories directory to get you started. You can add your own stories to this directory or create a new directory for your stories (in which case you will need to update the Storybook configuration).
The Storybook server will automatically detect changes to your stories and update the UI accordingly.
Storybook Devtools tab.For more information on how to write stories and the next steps, refer to the Storybook documentation.
Preview Builds
You can test the latest code from the main branch using pkg.pr.new, without waiting for a stable npm release.
Opting in to preview builds
To use the latest preview version, follow these steps:
- Modify the
@nuxtjs/storybookdependency in yourpackage.json:{ "devDependencies": { "@nuxtjs/storybook": "https://pkg.pr.new/@nuxtjs/storybook@main" } } - Remove the lockfile and reinstall dependencies so the preview build is resolved.
Every pull request is also published to pkg.pr.new, so you can test a specific PR with:
{
"devDependencies": {
"@nuxtjs/storybook": "https://pkg.pr.new/@nuxtjs/storybook@<pr-number>"
}
}
Opting out of preview builds
If you need to revert to the stable release, follow these steps:
- Change the
@nuxtjs/storybookdependency inpackage.jsonback to the stable version:{ "devDependencies": { "@nuxtjs/storybook": "next" } } - Remove the lockfile and reinstall the dependencies to revert to the stable release.
Storybook config Files
When running nuxt dev, this module looks for these files:
.storybook/main.{ts,js}.storybook/preview.{ts,js}
import { defineMain } from '@storybook-vue/nuxt/node'
export default defineMain({
stories: ['../components/**/*.stories.ts'],
addons: ['@storybook/addon-docs'],
framework: '@storybook-vue/nuxt',
})
import addonDocs from '@storybook/addon-docs'
import { definePreview } from '@storybook-vue/nuxt'
export default definePreview({
addons: [addonDocs()],
})
See the Storybook configuration for the details.
Module options
You can customize the Nuxt module's behavior by using the storybook property in nuxt.config:
export default defineNuxtConfig({
storybook: {
// Options
route: '/_storybook',
},
})
See the module options.