Vue CLI Plugin for Storybook

Common errors

• Cannot find module '@storybook/core/server'

  cause This error typically occurs during a Storybook 7 migration due to package consolidation and path changes within the Storybook ecosystem.
  fix Try running `npx sb@latest upgrade` to ensure Storybook dependencies are correctly updated and migrated. If the problem persists, manually check and update Storybook-related packages in `package.json` to their latest compatible versions.

• TypeError: server.buildDev is not a function

  cause Similar to the `Cannot find module` error, this is often seen during Storybook migrations (e.g., to v7) when the internal Storybook API changes and the plugin's integration expects an older method.
  fix Ensure all `@storybook/*` packages are aligned to the same major version. Running `npx sb@latest upgrade` is the recommended first step. If issues persist, check the `vue-cli-plugin-storybook` GitHub issues for workarounds or compatible Storybook versions.

• [Vue warn]: You are using the runtime-only build of Vue where the template compiler is not available.

  cause Storybook might be trying to use the runtime-only build of Vue while stories require the full compiler, often due to webpack alias misconfiguration or Storybook not properly detecting the Vue setup.
  fix In your `.storybook/webpack.config.js`, ensure Vue's alias points to the full build. Example: `config.resolve.alias['vue$'] = 'vue/dist/vue.esm-bundler.js';` (for Vue 3 ESM) or `'vue/dist/vue.esm.js'` (for Vue 2 ESM).

• Module build failed (from ./node_modules/sass-loader/dist/cjs.js): [...] (usually related to CSS preprocessors like Stylus/Sass)

  cause Storybook's internal webpack configuration may not include the necessary loaders or plugin whitelisting for CSS preprocessors (e.g., Sass, Stylus) or custom webpack plugins used in the Vue CLI project.
  fix Extend Storybook's webpack config in `.storybook/webpack.config.js` to include the specific loaders for your CSS preprocessor. For custom plugins, add their names to the `pluginOptions.storybook.allowedPlugins` array in `vue.config.js`.

Warnings

• deprecated The underlying Vue CLI is in 'Maintenance Mode'. For new Vue projects, `create-vue` (Vite-based) is now recommended. This plugin's development aligns with Vue CLI's status, meaning its future major version updates are uncertain.
  Fix: For new projects, consider using `npm create storybook@latest` directly, which integrates with Vite and the latest Vue versions without relying on Vue CLI plugins.
• breaking Storybook versions 7 and higher introduce significant breaking changes, including the removal of the `storiesOf` API and the `*.stories.mdx` format. Projects using this plugin that attempt to upgrade Storybook versions might encounter errors requiring manual migration to Component Story Format (CSF) 3 and `.mdx` files with CSF.
  Fix: Refer to the official Storybook migration guides (e.g., from v6 to v8, or v7 to v8) for detailed instructions on updating story files and configuration. Specifically, convert `storiesOf` to CSF 3 named exports.
• gotcha Node.js version compatibility can be an issue. Storybook 8 requires Node.js 18+ and Storybook 9 requires Node.js 20+. If you update Storybook independently of the `vue-cli-plugin-storybook`, you might face Node.js compatibility errors if your project's Node.js version is too old.
  Fix: Ensure your Node.js version meets the requirements of your Storybook version. If using Storybook 8+, upgrade to Node.js 18 or higher; for Storybook 9+, use Node.js 20 or higher. Use a Node Version Manager (like `nvm`) to easily switch versions.
• gotcha Webpack alias resolution issues, particularly for paths starting with `@` (e.g., `@/components/MyComponent.vue`), can occur because Storybook uses its own webpack config. While the plugin aims to resolve this, manual intervention might be needed.
  Fix: Manually extend Storybook's webpack configuration in `.storybook/webpack.config.js` to include the correct alias resolution for `@` or other custom paths. For example, add `defaultConfig.resolve.alias = { ...defaultConfig.resolve.alias, '@': path.resolve(__dirname, '../src') };`
• breaking Upgrading Vue CLI to v5, which includes Webpack 5, can introduce breaking changes that might affect existing Storybook configurations generated by older versions of this plugin. This could manifest as compilation errors or unexpected behavior.
  Fix: If migrating a Vue CLI project to v5, consider using `vue add storybook@next` or re-running `vue add storybook` to regenerate Storybook configuration tailored for Vue CLI 5. Review Vue CLI's own migration guide for Webpack 5 changes.

Install

• npm install vue-cli-plugin-storybook npm
• yarn add vue-cli-plugin-storybook yarn
• pnpm add vue-cli-plugin-storybook pnpm

Imports

• Add Plugin via Vue CLI
  wrong:

  npm install vue-cli-plugin-storybook

  correct:

  vue add storybook

  This is a CLI command to invoke the plugin, not a JavaScript import. `npm install` alone will not configure the project correctly.
• configure
  wrong:

  const { configure } = require('@storybook/vue');

  correct:

  import { configure } from '@storybook/vue';

  Used in `.storybook/config.js` for Storybook versions < 7 to load stories and register global components/plugins. Newer Storybook versions (7+) primarily use CSF 3 with `main.js` and `preview.js`.
• setup
  wrong:

  const { setup } = require('@storybook/vue3-vite');

  correct:

  import { setup } from '@storybook/vue3-vite';

  For Storybook 7+ with Vue 3 and Vite, `setup` is used in `.storybook/preview.js` to extend the Vue application instance (e.g., install plugins, register global components) before stories render. This replaces aspects of the older `configure` function.
• storiesOf

  import { storiesOf } from '@storybook/vue';

  This API for defining stories (`storiesOf('Component').add(...)`) is part of Component Story Format (CSF) 2. It is deprecated and removed in Storybook 7.x and later, which relies on CSF 3 with named exports from a default meta object.

Quickstart

Demonstrates how to add the plugin to a Vue CLI project, defines a sample Vue component, and creates a basic Storybook story using modern Component Story Format (CSF) 3, concluding with instructions to launch Storybook.

npx @vue/cli create my-storybook-app --default
cd my-storybook-app

# Add the Storybook plugin (choose Vue 3 preset if prompted, for this example)
vue add storybook

# The plugin adds Storybook commands and configuration.
# Example `src/components/MyButton.vue`:
// <template>
//   <button :style="{ backgroundColor }" @click="$emit('click')">
//     {{ label }}
//   </button>
// </template>
//
// <script lang="ts">
// import { defineComponent } from 'vue';
// export default defineComponent({
//   name: 'MyButton',
//   props: {
//     label: { type: String, required: true },
//     backgroundColor: { type: String, default: '#42b983' },
//   },
// });
// </script>
//
// <style scoped>
// button {
//   font-family: 'Open Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
//   font-weight: 700;
//   border: 0;
//   border-radius: 3em;
//   cursor: pointer;
//   display: inline-block;
//   line-height: 1;
//   font-size: 14px;
//   padding: 10px 16px;
//   color: white;
// }
// </style>

# Example Story file `src/stories/MyButton.stories.ts` (using CSF 3, compatible with Storybook 7+)
import type { Meta, StoryObj } from '@storybook/vue3';
import MyButton from '../components/MyButton.vue';

const meta: Meta<typeof MyButton> = {
  title: 'Example/MyButton',
  component: MyButton,
  tags: ['autodocs'],
  argTypes: {
    backgroundColor: { control: 'color' },
    onClick: { action: 'clicked' },
  },
};

export default meta;

type Story = StoryObj<typeof MyButton>;

export const Primary: Story = {
  args: {
    label: 'Button',
    backgroundColor: '#3f51b5',
  },
};

export const Secondary: Story = {
  args: {
    label: 'Secondary Button',
    backgroundColor: '#f50057',
  },
};

# To run Storybook after installation:
npm run storybook:serve
# or
yarn storybook:serve