静的な書き出し
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 自身のコンポーネントのカタログをこの方法で書き出したものです。