Static export
With build: true, vite build also writes the catalog as static files.
// vite.config.ts
zukan({ build: true });
The catalog is written to zukan-dist/, separately from the app build. You can choose another directory with build: { outDir: 'docs/zukan' }. Because it is separate from the app’s build output, an adapter’s output step does not delete it. Add /zukan-dist to .gitignore.
- Output paths are relative, so the catalog works under any subpath (for example,
/docs/zukan/). No server-side rewrites are needed - The app’s
publicDir(public, orstaticin SvelteKit) is copied into_zukan/, and a URL of one of its files in CSS or in an import (url('/bg.png'),import bg from '/bg.png?url') points at that copy. A literal/bg.pngin markup (<img src="/bg.png">) can’t be rewritten: it names the root of the host, so it loads only when the catalog’s host serves the file at/bg.png. Import the file instead - When
buildis enabled,vite buildruns in Vite’s builder mode (Environment API), and all environments are built in one run - The catalog’s CSS targets browsers with
light-dark()(Chrome and Edge 123, Firefox 120, Safari 17.5), whateverbuild.cssTargetthe app sets, solight-dark()in your components follows the catalog’s theme button vite previewserves the exported catalog at/__zukan/(underbasewhen it is set), so you can check it before you deploy it. It sendspreview.headers, except that onindex.htmlX-Frame-Options: DENYbecomesSAMEORIGINand a Content-Security-Policyframe-ancestorsalso allows'self', because each preview is a frame of that page. A host you deploy the catalog to must allow the same- A catalog tab left open across a redeploy still asks for the previous build’s files. When one of them is gone, the catalog reloads once to pick up the new build (at most once every 10 seconds; after that, the preview shows the error)
vite build --watchdoes not write the catalog. It prints a warning and skips it- With
build.write: falsein the Vite config, the catalog is built but no file is written or removed - The output directory must not be Vite’s root or contain it, and must not overlap the app’s
build.outDir(distby default), thebuild.outDirof each environment other than the catalog’s, or SvelteKit’soutDir(.svelte-kit), and must not be inside the app’spublicDir(public, orstaticin SvelteKit), which the app copies before the catalog is written. Each of these is a build error - The catalog is written by
vite build(and bycreateBuilder().buildApp()from Vite’s JavaScript API).vite build --ssrand Vite’sbuild()function build a single environment and do not write it - Next to
index.html,catalog.jsonlists every component with its sections, code, props and.md, and the.sveltefiles without a catalog file, for tools and AI agents. The dev server serves the same data at/__zukan/catalog.json - Before writing, only the previous catalog (
_zukan/,index.htmlandcatalog.jsonin the output directory) is removed. In SvelteKit, adapters often emptybuild/, so a warning is printed if the output directory overlaps withbuild/
The demo is the catalog of svelte-zukan’s own components, exported this way.