Upgrade to v11
Nuxt Storybook v11 adds support for Storybook 11. Storybook is now served by the Nuxt dev server, every story renders in its own Nuxt app, and stories can mock auto-imports, components and server endpoints.
This guide covers the changes of the Nuxt integration. For the changes of Storybook itself, follow the Storybook 11 migration guide as well.
Requirements
| v10 | v11 | |
|---|---|---|
| Node.js | 22+ | 22+ |
| Storybook | 10.6+ | 11.x |
| Nuxt | 3.18.1+ or 4.x | 3.18.1+ or 4.x |
| Vite | 5, 6, 7 or 8 | 5, 6, 7 or 8 |
Upgrade steps
1. Upgrade Storybook
Run the Storybook upgrade command in your project root. It bumps every storybook and @storybook/* package to Storybook 11 and runs its automigrations.
pnpm dlx storybook@next upgrade
yarn dlx storybook@next upgrade
npx storybook@next upgrade
The upgrade does not cover every breaking change of Storybook itself. Read the Storybook 11 migration guide for the changes that apply to every Storybook project.
2. Upgrade the Nuxt module
pnpm add -D @nuxtjs/storybook@^11 @storybook-vue/nuxt@^11
yarn add -D @nuxtjs/storybook@^11 @storybook-vue/nuxt@^11
npm install -D @nuxtjs/storybook@^11 @storybook-vue/nuxt@^11
@storybook-vue/nuxt is a dependency of the module, but your project imports defineMain, definePreview and the mocking helpers from it: install it next to the module so these imports resolve.
3. Remove the port, host and https options
nuxt dev no longer starts a separate Storybook server on its own port. Storybook now runs inside the Nuxt dev server through @storybook/vite-plugin and is served under the route option (/_storybook/ by default), on the same host and port as your app.
export default defineNuxtConfig({
modules: ['@nuxtjs/storybook'],
storybook: {
route: '/_storybook',
- host: 'http://localhost',
- port: 6006,
- https: false,
},
})
- Storybook follows the
nuxt devsettings, for examplenuxt dev --port 4000 --https. - Open
http://localhost:3000/_storybook/instead ofhttp://localhost:6006. storybook devstill runs Storybook on its own port.
4. Move to CSF Factories (recommended)
CSF3 stories keep working. CSF Factories type parameters.nuxt and infer the props of your components. Storybook's codemod rewrites your config and stories:
npx storybook automigrate csf-factories
Then import defineMain from @storybook-vue/nuxt/node and definePreview from @storybook-vue/nuxt:
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 CSF Factories for the details.
One Nuxt app per story
Every story renders in its own Nuxt app, created from the payload of the story instead of a shared window.__NUXT__.
- The app always runs in pages mode, with an in-memory router history. A route without a page renders an empty fallback page, so a component using
useRoute()renders in projects withoutpages/. - The story starts on
/. Setparameters.nuxt.routeto start it on another route. - Navigation is blocked by default, in the router and for links to other sites. Each attempt is reported to the
navigationspy exported by@storybook-vue/nuxt. Setparameters.nuxt.navigationtotrueto let the story navigate. parameters.nuxt.runtimeConfigis deep-merged into the runtime config of your Nuxt config for this story.
import preview from '../.storybook/preview'
import MyPage from './MyPage.vue'
const meta = preview.meta({ component: MyPage })
export const Settings = meta.story({
parameters: {
nuxt: {
route: '/settings?tab=profile',
runtimeConfig: { public: { apiBase: 'https://staging.example.com' } },
},
},
})
Mocking replaces the runtime overrides
The built-in overrides of v10, such as the useRouter override and the <NuxtLink> replacement, were removed. Stories now use the real Nuxt composables and components, and you mock what a story needs with mockNuxtImport, mockComponent and registerEndpoint or using Storybook provided mocks.
Package exports
@storybook-vue/nuxtis ESM only. The CommonJS entries were removed.defineMainis exported from the new@storybook-vue/nuxt/nodeentry.getNuxtProxyConfig()was removed from@storybook-vue/nuxt/preset, along with the proxy to the Nuxt dev server.