Getting Started

Setup

Using Storybook in your Nuxt project is only one command away ✨

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

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.

Storybook 11 is published under the 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.

  1. Add @nuxtjs/storybook as a development dependency to your project:
npx nuxi@latest module add storybook
  1. If not using nuxi above, add the module @nuxtjs/storybook to your Nuxt configuration:
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/storybook'],
})
  1. Create the Storybook config files.
That's it! You can now use Storybook in your Nuxt app ✨

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 VersionStorybookNuxtNode.js
v11.x11.x4.x / 5.x22+
v10.x10.x3.18.1+ / 4.x22+
v9.x8.x / 9.x3.x20+
v4.x6.x2.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

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.

Discover your Stories directly within the 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/storybook dependency in your package.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/storybook dependency in package.json back 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',
})

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:

nuxt.config.ts
export default defineNuxtConfig({
  storybook: {
    // Options
    route: '/_storybook',
  },
})

See the module options.