---
title: Static export
sidebar:
  order: 2
---

With `build: true`, `vite build` also writes the catalog as static files.

```ts
// 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`, or `static` in 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.png` in 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 `build` is enabled, `vite build` runs 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), whatever `build.cssTarget` the app sets, so `light-dark()` in your components follows the catalog's theme button
- `vite preview` serves the exported catalog at `/__zukan/` (under `base` when it is set), so you can check it before you deploy it. It sends `preview.headers`, except that on `index.html` `X-Frame-Options: DENY` becomes `SAMEORIGIN` and a Content-Security-Policy `frame-ancestors` also 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 --watch` does not write the catalog. It prints a warning and skips it
- With `build.write: false` in 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` (`dist` by default), the `build.outDir` of each environment other than the catalog's, or SvelteKit's `outDir` (`.svelte-kit`), and must not be inside the app's `publicDir` (`public`, or `static` in 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 by `createBuilder().buildApp()` from Vite's JavaScript API). `vite build --ssr` and Vite's `build()` function build a single environment and do not write it
- Next to `index.html`, `catalog.json` lists every component with its sections, code, props and `.md`, and the `.svelte` files 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.html` and `catalog.json` in the output directory) is removed. In SvelteKit, adapters often empty `build/`, so a warning is printed if the output directory overlaps with `build/`

The [demo](https://oekazuma.github.io/svelte-zukan/demo/) is the catalog of svelte-zukan's own components, exported this way.
