コンテンツにスキップ
svelte-zukan
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

静的な書き出し

build: true にすると、vite build のときにカタログも静的なファイルとして書き出します。

// vite.config.ts
zukan({ build: true });

カタログはアプリのビルドとは別に zukan-dist/ へ書き出されます。build: { outDir: 'docs/zukan' } のように出力先も選べます。アプリのビルドの出力先とは別なので、adapter の書き出しに消されません。/zukan-dist は .gitignore に足してください。

  • 出力のパスは相対パスなので、どのサブパス(例: /docs/zukan/)に置いても動きます。サーバー側の書き換え設定は要りません
  • アプリの publicDir(public、SvelteKit では static)は _zukan/ にコピーされ、CSS や import で指定したそのファイルの URL(url('/bg.png')、import bg from '/bg.png?url')はコピーを指すようになります。マークアップに直接書いた /bg.png(<img src="/bg.png">)は書き換えられません。ホストのルートを指すので、カタログのホストがそのファイルを /bg.png で配信しているときにしか読み込めません。ファイルを import してください
  • build を有効にすると、vite build は Vite の builder モード(Environment API)で動き、全環境が 1 回の実行でビルドされます
  • カタログの CSS はアプリの build.cssTarget にかかわらず、light-dark() に対応したブラウザー(Chrome と Edge 123、Firefox 120、Safari 17.5)向けに出力します。そのため、コンポーネントの light-dark() もカタログのテーマボタンに従います
  • vite preview でも、書き出したカタログを /__zukan/(base を設定していればその下)で開けるので、公開する前に確かめられます。preview.headers も送りますが、プレビューはどれも index.html のフレームなので、index.html では X-Frame-Options: DENY を SAMEORIGIN に変え、Content-Security-Policy の frame-ancestors に 'self' を足します。カタログを公開するホストでも、同じオリジンのフレームを許可してください
  • 再デプロイの前から開いたままのカタログのタブは、前のビルドのファイルを読みにいきます。そのファイルがもう無いときは、カタログを 1 回だけ読み込み直して新しいビルドに切り替えます(10 秒に 1 回まで。それ以上はプレビューにエラーを表示します)
  • vite build --watch ではカタログを書き出しません。警告を出して飛ばします
  • Vite の設定が build.write: false のときは、カタログをビルドしますが、ファイルの書き出しも削除もしません
  • 出力先は Vite の root そのものや root を含むディレクトリにできません。アプリの build.outDir(既定は dist)、カタログ以外の各環境の build.outDir、SvelteKit の outDir(.svelte-kit)と重なってもいけません。アプリの publicDir(public、SvelteKit では static)の中にも置けません。アプリはカタログを書き出す前に publicDir をコピーするからです。どれもビルドエラーになります
  • カタログを書き出すのは vite build(Vite の JavaScript API なら createBuilder().buildApp())です。vite build --ssr と Vite の build() 関数は 1 つの環境だけをビルドするので、カタログは書き出しません
  • index.html の隣に catalog.json も書き出します。全コンポーネントのセクション、コード、props、.md と、カタログファイルのない .svelte ファイルをまとめたもので、ツールや AI エージェント向けです。dev サーバーでは同じ内容を /__zukan/catalog.json で返します
  • 書き出しの前に、前回のカタログ(出力先の _zukan/、index.html、catalog.json)だけを消します。SvelteKit では、adapter が build/ を空にすることが多いので、出力先が build/ と重なると警告を出します

デモは svelte-zukan 自身のコンポーネントのカタログをこの方法で書き出したものです。