---
title: svelte-zukan を選ぶ理由
sidebar:
  order: 5
---

svelte-zukan はコンポーネントカタログで、それ以外のことはしません。Storybook をカタログとしてだけ使っているなら、svelte-zukan でも同じカタログが作れて、インストール、設定、更新の手間はずっと少なくて済みます。

## 力を入れていること

- カタログの機能だけに絞っています。コンポーネントの一覧、スマートフォンからデスクトップまでの幅でのライブプレビュー、各例のコード、Props の一覧、ライトとダークのテーマ、アクセシビリティの検査がそろっています。アドオンの仕組みも、テストランナーも、覚えるべきストーリーの書式もありません
- 保守の手間が少なく、`devDependencies` に入るのは 1 パッケージだけです。実行時の依存 2 つ（Markdown 用の `marked` と、アクセシビリティ検査用の `axe-core`）を合わせて約 4 MB で、axe-core をブラウザーで読み込むのは検査を実行したときだけです。バージョンをそろえ続けるアドオンも、移行が必要な設定ディレクトリもありません。更新は svelte-zukan のバージョンを上げるだけです
- 導入は `vite.config.ts` に 1 行足すだけです。カタログはアプリ自身の Vite の dev サーバーで動くので、エイリアス、プラグイン、CSS の処理がそのまま適用されます。2 つ目の dev サーバーも、アプリと合わせ続ける 2 つ目のビルド設定もありません
- カタログファイルは通常の Svelte 5 コンポーネントです。コンポーネントを import し、ほかの場所と同じコードで例を書きます。そのため、Svelte が変わったときも、カタログファイルはコンポーネントと同じように直せば済みます
- `Button.zukan.svelte` と `Button.zukan.md` は `Button.svelte` の隣に置きます。そのため、コンポーネントを移したり消したりすると、そのカタログも一緒に移ったり消えたりします
- 公開もしやすく、`build: true` にすると同じ `vite build` で静的なカタログも書き出せます。書き出したカタログは GitHub Pages のように、どのパスに置いても動きます

## Storybook との比較

|                              | svelte-zukan                                                                          | Storybook                                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| インストール量<sup>1</sup>   | **4.2 MB、3 パッケージ**                                                              | 78 MB、82 パッケージ                                                                         |
| 導入                         | `vite.config.ts` に `zukan()` を足す                                                  | 専用の設定ファイルを入れた `.storybook/` ディレクトリ                                        |
| 更新                         | `svelte-zukan` のバージョンを上げる                                                   | コア、フレームワーク、アドオンのパッケージをまとめて上げる（`storybook upgrade` と自動移行） |
| 動く場所                     | アプリの dev サーバーの中（`/__zukan/`）                                              | 専用の dev サーバー                                                                          |
| 書くもの                     | `<Section>` を並べたふつうの Svelte コンポーネント                                    | Svelte CSF（`defineMeta`、`<Story>`）か CSF のストーリー                                     |
| コンポーネントごとの説明     | コンポーネントの隣に置く Markdown ファイルと、コンポーネントから読み取る Props の一覧 | MDX と autodocs                                                                              |
| コード表示                   | セクションごとに、使っている `<script>` の定義も表示                                  | あり                                                                                         |
| プレビューの幅               | プリセット、ドラッグ、数値の入力。広い幅は縮小して表示                                | ビューポートのツールバー                                                                     |
| 背景                         | ライトとダークに加えて、市松模様とグリッド                                            | あり                                                                                         |
| 検索                         | あり                                                                                  | あり                                                                                         |
| アクセシビリティの検査       | あり（axe-core。問題のある要素の枠線表示と見え方の再現つき）                          | あり（a11y アドオン）                                                                        |
| 要素の計測                   | あり（カーソルを当てた要素のボックスモデル）                                          | あり（measure アドオン）                                                                     |
| props の操作パネル           | なし。意図して入れていません（下で説明します）                                        | あり                                                                                         |
| イベントのログ               | なし                                                                                  | あり（actions）                                                                              |
| 操作テストとビジュアルテスト | なし                                                                                  | あり                                                                                         |
| SvelteKit の `$app/*`        | 本物のモジュールを既定の状態で使う                                                    | モック（`$app/state` も含む）                                                                |
| 静的な書き出し               | 自分の `vite build` で `build: true`。どのパスでも動く                                | `storybook build`                                                                            |
| 動作環境                     | Vite 8 以上、Svelte 5.57.1 以上、SvelteKit 3 以上（素の Vite + Svelte も可）          | 複数のバンドラーとフレームワーク                                                             |

<sup>1</sup> 空のディレクトリで `npm install` して測りました。どちらにも共通する peer dependencies（`svelte`、`vite`、`@sveltejs/kit`）は除いています。svelte-zukan は 0.7.0 を 2026-10-21 に、Storybook は 2026-10-19 に測りました。Storybook は `storybook` と `@storybook/sveltekit` だけで、アドオンは入れていません。

## props の操作パネルがない理由

Storybook ではパネルからコンポーネントの props を変えられます。svelte-zukan にはこの機能を意図して入れていません。`<Section>` はそれぞれコードとして書いた固定の例で、編集すると dev サーバーがすぐに反映します。こうすると、例をプルリクエストでレビューでき、props を記述するもう 1 つの方法をカタログに持ち込まずに済みます。

## Storybook を選ぶべき場面

Storybook はカタログよりずっと多くのことができます。次のどれかが必要なら、Storybook を選んでください。

- props の操作パネル、イベントのログ、操作テスト、ビジュアルリグレッションテスト
- 複数のフレームワークのコンポーネントを 1 つのカタログにまとめること
- SvelteKit 2、Vite 7 以前、または Vite 以外のバンドラー
- ストーリーごとに、SvelteKit の `page` などの `$app/*` の値を変えること

## Storybook から移る

[`migrate-svelte-zukan` スキル](/svelte-zukan/ja/skills#migrate-svelte-zukan)を使うと、移行を AI エージェントに任せられます。ストーリーはそれぞれ `<Section>` になり、`argTypes` の説明は props の JSDoc に、MDX の本文は `.zukan.md` ファイルになります。Storybook は、エージェントに削除を頼むまで残ります。`play` 関数のあるストーリーは、その操作テストをどうするか決めるまで残します。
