Autodocs causes "Cannot read properties of undefined (reading 'beforeEach')" and "Cannot redefine property: $route" errors

[lazercaveman]

Environment

Bug Report: Autodocs causes "Cannot read properties of undefined (reading 'beforeEach')" and "Cannot redefine property: $route" errors

Environment

• Operating System: Linux/macOS/Windows
• Node Version: v20.x
• Package Manager: pnpm/npm/yarn
• Nuxt Version: 3.x
• Storybook Framework: @storybook-vue/nuxt
• Storybook Version: 8.x

Reproduction

Create a minimal Nuxt + Storybook setup with the following configuration:

main.ts:

import type { StorybookConfig } from '@storybook-vue/nuxt';

const config: StorybookConfig = {
  framework: {
    name: '@storybook-vue/nuxt',
    options: {},
  },

  addons: [
    '@chromatic-com/storybook',
    '@storybook/addon-docs',
    '@storybook/addon-a11y',
    '@storybook/addon-vitest',
  ],

  stories: [
    '../app/components/**/*.stories.@(js|jsx|ts|tsx|mdx)',
  ],

  // @ts-expect-error: Storybook types don't include disableTelemetry here
  core: { disableTelemetry: true },
};

export default config;

preview.ts:

import type { Preview } from '@storybook-vue/nuxt';
import { setup } from '@storybook/vue3';
import { createPinia } from 'pinia';
import { action } from 'storybook/actions';

setup((app) => {
  const pinia = createPinia();
  app.use(pinia);

  // This makes nuxt-link work in Storybook
  app.component('NuxtLink', {
    props: {
      to: {
        type: String,
        required: true,
      },
    },
    methods: {
      log (this: { $props: { to: string } }) {
        action('link target')(this.$props.to);
      },
    },
    template: '<a @click="log()" style="cursor:pointer;"><slot>NuxtLink</slot></a>',
  });
});


// Device resolutions can be found here: https://www.webmobilefirst.com/en/devices/
// Related statistics can be found here: https://gs.statcounter.com/screen-resolution-stats/all/germany
const viewportOptions = {
  iPhone16: {
    name: 'iPhone 16',
    styles: {
      width: '393px',
      height: '852px',
    },
  },
  sm: {
    name: 'Small',
    styles: {
      width: '480px',
      height: '900px',
    },
  },
  md: {
    name: 'Medium',
    styles: {
      width: '768px',
      height: '900px',
    },
  },
  lg: {
    name: 'Large',
    styles: {
      width: '1024px',
      height: '900px',
    },
  },
  iPadAir: {
    name: 'iPadAir',
    styles: {
      width: '1180px',
      height: '820px',
    },
  },
  xl: {
    name: 'XL',
    styles: {
      width: '1344px',
      height: '960px',
    },
  },
  macbookPro: {
    name: 'macbookPro',
    styles: {
      width: '1728px',
      height: '1117px',
    },
  },
};

const customGrid = {
  cellSize: 8,
  opacity: 0.2,
  cellAmount: 8,
  offsetX: 8,
  offsetY: 4,
};

const customCanvasColors = [
  {
    name: 'white',
    value: '#ffffff',
  },
  {
    name: 'gray',
    value: '#eeeeee',
  },
  {
    name: 'dev-mode',
    value: '#0d0d10',
  },
];


const preview: Preview = {
  parameters: {
    layout: 'centered',
    backgrounds: {
      options: {
        default: 'gray',
        values: customCanvasColors,
        grid: customGrid,
      },
    },
    viewport: { viewports: viewportOptions },
    chromatic: { viewports: [viewportOptions.sm.styles.width, viewportOptions.xl.styles.width] },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
  tags: ['autodocs'],
};


export default preview;

Reproduction

Describe the bug

When enabling tags: ['autodocs'] in the preview configuration, two critical errors occur:

Error 1: Router beforeEach undefined

Error: Cannot read properties of undefined (reading 'beforeEach')
at /node_modules/nuxt/dist/app/nuxt.js?v=d2c0beda:138:60
at fn (/node_modules/nuxt/dist/app/nuxt.js?v=d2c0beda:220:44))
at Object.runWithContext (/node_modules/@vue/runtime-core/dist/runtime-core.esm-bundler.js?v=d2c0beda:4084:18))
at callWithNuxt (/node_modules/nuxt/dist/app/nuxt.js?v=d2c0beda:226:24))
at /node_modules/nuxt/dist/app/nuxt.js?v=d2c0beda:37:41

Error 2: Router property redefinition (when attempting manual router setup)

Error: Cannot redefine property: $route
at Object.install (/node_modules/vue-router/dist/vue-router.mjs?v=d2c0beda:2655:14))
at Object.use (/node_modules/@vue/runtime-core/dist/runtime-core.esm-bundler.js?v=d2c0beda:3947:18))
at /.storybook/preview.ts:26:7

Expected Behavior

• Autodocs should render components correctly without router-related errors
• The framework should handle router context properly within the Storybook environment
• Component stories should display normally while autodocs pages should generate automatically

Actual Behavior

• Individual component stories work correctly and render properly
• Autodocs pages fail to load with router context errors
• Manual router setup attempts result in property redefinition conflicts
• The Nuxt context is not properly initialized in the autodocs rendering context

.
hout)

Additional context

Additional Context

• This issue only affects autodocs pages - individual component stories render without problems
• The @storybook-vue/nuxt framework appears to provide its own router instance, causing conflicts with manual router setup
• Similar issues have been reported with other Nuxt-Storybook integrations:
  • Router context unavailable in static builds
  • Nuxt instance unavailable errors
  • Plugin initialization conflicts

Possible Root Cause

The issue seems to stem from:

1. Incomplete router context initialization during autodocs rendering
2. Conflicts between framework-provided router and manual router setup attempts
3. Missing Nuxt plugin context in the autodocs rendering environment

Workarounds Attempted

1. ✅ Removing global tags: ['autodocs'] and using selective autodocs per component
2. ❌ Manual router installation in preview.ts (causes redefine property error) (tried with and without)
3. ❌ Using storybook-vue3-router addon
4. ❌ Creating mock router without installation

Proposed Solution

The @storybook-vue/nuxt framework should:

1. Properly initialize router context for autodocs rendering
2. Ensure Nuxt plugins are available during autodocs generation
3. Provide clear documentation on router handling limitations
4. Consider supporting selective autodocs activation as a temporary workaround

Related Issues

• Similar to router context issues reported in other Nuxt-Storybook integrations
• Related to the broader ecosystem challenges with Nuxt-Storybook compatibility noted in issue State of the project #813

This bug significantly impacts the developer experience when trying to generate automatic documentation for Nuxt components, forcing developers to either disable autodocs entirely or manually create documentation for each component

[lazercaveman]

Additional Information: when adding tags: ['autodocs'] on the stories.ts file level (removing it from preview.ts) the error would still occur, even if it is only set/activated within stories.ts files of a single component, not using the router at all.

Plus: folowing the documentation (where autodocs is set within maint.ts) is leading to type errors and results in autodocs not working at all: https://storybook.nuxtjs.org/storybook/config