Migration

Upgrade to v11

Upgrade Nuxt Storybook from v10 to v11 and Storybook 11.

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

v10v11
Node.js22+22+
Storybook10.6+11.x
Nuxt3.18.1+ or 4.x3.18.1+ or 4.x
Vite5, 6, 7 or 85, 6, 7 or 8
Nuxt Storybook v11 does not support Storybook 10 anymore. Stay on v10 of the module if you cannot upgrade Storybook yet.

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

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

@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.

nuxt.config.ts
 export default defineNuxtConfig({
   modules: ['@nuxtjs/storybook'],
   storybook: {
     route: '/_storybook',
-    host: 'http://localhost',
-    port: 6006,
-    https: false,
   },
 })
  • Storybook follows the nuxt dev settings, for example nuxt dev --port 4000 --https.
  • Open http://localhost:3000/_storybook/ instead of http://localhost:6006.
  • storybook dev still runs Storybook on its own port.

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',
})

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 without pages/.
  • The story starts on /. Set parameters.nuxt.route to 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 navigation spy exported by @storybook-vue/nuxt. Set parameters.nuxt.navigation to true to let the story navigate.
  • parameters.nuxt.runtimeConfig is deep-merged into the runtime config of your Nuxt config for this story.
components/MyPage.stories.ts
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/nuxt is ESM only. The CommonJS entries were removed.
  • defineMain is exported from the new @storybook-vue/nuxt/node entry.
  • getNuxtProxyConfig() was removed from @storybook-vue/nuxt/preset, along with the proxy to the Nuxt dev server.