NuxtにStorybookを導入する方法 | @nuxtjs/storybookで環境構築

この記事では、公式モジュールである@nuxtjs/storybookを使用して、最新のNuxt環境にStorybookを導入する手順を解説します。

「そもそもStorybookって何？」「導入するとどんなメリットがあるの？」と思った方は、まず以下の記事をご覧ください。Storybookの基本から活用シーンまで詳しく解説しています。

あわせて読みたい

Storybook導入で何が解決する？メリット・デメリットと最適な活用シーンを解説 この記事で解決できるお悩み コンポーネントの管理が煩雑で、同じようなパーツを何度も作り直している デザイナーとエンジニア間で認識のズレが生じて、手戻りが多い UI…

前提条件・実行環境

本記事では、以下の環境を前提として解説します。

Nuxt 4の場合：
　Nuxtバージョン： 4.x
　Node.jsバージョン： 20.19+、22.12+、または 24+
　Storybookバージョン： 10.x
　パッケージマネージャー： pnpm

Nuxt 3の場合：
　Nuxtバージョン： 3.13.0以降
　Node.jsバージョン： 18.0+、20.x、または 22.x
　Storybookバージョン： 9.x
　パッケージマネージャー： npm

@nuxtjs/storybookについて

概要

@nuxtjs/storybookは、NuxtアプリケーションにStorybookを統合するための公式モジュールです。このモジュールを使用することで、Nuxtの設定や機能をそのままStorybookで利用できるようになります。

本記事では、Storybookの公式CLIを使用した導入方法を推奨しています。

公式CLIを使用すると、内部的に@nuxtjs/storybookも含めた必要なパッケージが自動的にインストールされます。さらに、以下のファイルも自動生成されるため、手動での設定作業が不要になります：

• サンプルストーリーファイル（.stories.ts）
• .storybook/main.ts（Storybookのメイン設定ファイル）
• .storybook/preview.ts（プレビュー設定ファイル）

公式CLIを使用する理由

npx nuxi module add storybookとの違い

npx nuxi module add storybookだけでは、.storybook/main.tsなどの設定ファイルが生成されないため、手動で作成する必要があります。一方、Storybookの公式CLIを使用すれば、すべてが自動的にセットアップされます。

バージョン管理がシンプル

公式CLIが依存関係を一括で管理してくれるため、バージョンの不整合が起きにくくなります。

設定ファイルが自動生成される

.storybook/main.tsや.storybook/preview.ts、サンプルストーリーが自動的に生成されるため、すぐに使い始められます。

サポートするバージョン

@nuxtjs/storybookは、Nuxt 3とNuxt 4、Storybook 10をサポートしています。以前のバージョンについては以下の対応表を参考にしてください。

導入手順

Storybookの導入手順は、Nuxt 3系とNuxt 4系で異なります。お使いのNuxtバージョンに合わせて、以下の手順を参照してください。

Nuxt 3での導入手順

Nuxt 3では、依存関係の調整が必要なため、以下の手順で進めます。

実際に検証した環境：
　Node.js: 22.16.0
　npm: 10.9.2
　Nuxt: 3.21.0
　Storybook: 9.0.5
　@nuxtjs/storybook: 9.0.1

npm create storybook@9 --legacy-peer-deps

npm uninstall @chromatic-com/storybook

npm install -D storybook@9.0.5 @storybook/addon-a11y@9.0.5 @storybook/addon-docs@9.0.5 --legacy-peer-deps

npm run storybook

Nuxt 4での導入手順

Nuxt 4では、比較的スムーズにStorybookを導入できます。

実際に検証した環境：
　Node.js: 22.16.0
　pnpm: 10.28.2
　Nuxt: 4.3.0
　Storybook: 10.2.3
　@nuxtjs/storybook: 9.0.1

pnpm create storybook@latest

pnpm storybook

最初のストーリーを作成

それでは、実際にコンポーネントとそのストーリーを作成してみましょう。

STEP

コンポーネントの作成

まず、簡単なボタンコンポーネントを作成します。

<template>
  <button :class="['button', `button--${variant}`]" @click="handleClick">
    {{ label }}
  </button>
</template>

<script setup lang="ts">
interface Props {
  label: string;
  variant?: "primary" | "secondary" | "danger";
}

const props = withDefaults(defineProps<Props>(), {
  variant: "primary",
});

const emit = defineEmits<{
  click: [];
}>();

const handleClick = () => {
  emit("click");
};
</script>

<style scoped>
.button {
  padding: 8px 16px;
  border-radius: 4px;
  font-weight: 600;
  border: none;
  cursor: pointer;
  transition: background-color 0.2s;
  font-size: 14px;
}

.button--primary {
  background-color: #3b82f6;
  color: white;
}

.button--primary:hover {
  background-color: #2563eb;
}

.button--secondary {
  background-color: #6b7280;
  color: white;
}

.button--secondary:hover {
  background-color: #4b5563;
}

.button--danger {
  background-color: #ef4444;
  color: white;
}

.button--danger:hover {
  background-color: #dc2626;
}
</style>

STEP

ストーリーファイルの作成

次に、このコンポーネントのストーリーを作成します。ストーリーファイルは通常、コンポーネントと同じディレクトリ、またはstories/ディレクトリに配置します。

import type { Meta, StoryObj } from "@nuxtjs/storybook";
import Button from "./Button.vue";

const meta: Meta<typeof Button> = {
  title: "Components/Button",
  component: Button,
  tags: ["autodocs"],
  argTypes: {
    variant: {
      control: "select",
      options: ["primary", "secondary", "danger"],
    },
    label: {
      control: "text",
    },
  },
};

export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {
    label: "Primary Button",
    variant: "primary",
  },
};

export const Secondary: Story = {
  args: {
    label: "Secondary Button",
    variant: "secondary",
  },
};

export const Danger: Story = {
  args: {
    label: "Danger Button",
    variant: "danger",
  },
};

STEP

Storybookを起動して確認

Storybookを開くと、左側のサイドバーに「Components > Button」が表示され、3つのバリエーション（Primary、Secondary、Danger）を確認できます。

まとめ

最後まで読んでいただき、ありがとうございました！

今回は、「NuxtにおけるStorybook導入方法」についてご紹介させていただきました。

@nuxtjs/storybookを使えば、Nuxtの設定を引き継ぎながらスムーズにStorybookを導入できます。コンポーネント駆動開発を実践することで、再利用性の高い品質の良いコンポーネントを効率的に開発できるようになります。

最初は設定やストーリーの書き方に戸惑うかもしれませんが、一度環境を整えてしまえば、開発体験が大きく向上します。コンポーネントを独立した環境でテストできるため、バグの早期発見にもつながりますし、デザイナーやPMとのコミュニケーションツールとしても活用できます。

ぜひ、あなたのNuxtプロジェクトにもStorybookを導入して、コンポーネント開発を加速させてください！