svelte-zukan を選ぶ理由
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 | |
|---|---|---|
| インストール量1 | 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 も可) | 複数のバンドラーとフレームワーク |
1 空のディレクトリで 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 スキルを使うと、移行を AI エージェントに任せられます。ストーリーはそれぞれ <Section> になり、argTypes の説明は props の JSDoc に、MDX の本文は .zukan.md ファイルになります。Storybook は、エージェントに削除を頼むまで残ります。play 関数のあるストーリーは、その操作テストをどうするか決めるまで残します。