Configuration

Fuzor is configured through its Vite plugin. Most apps need no options:

import { defineConfig } from "vite";
import { fuzorPlugin } from "fuzor/vite";

export default defineConfig({ plugins: [fuzorPlugin()] });

Plugin options

Option	Type	Default	Meaning
`server`	`boolean`	automatic	`true` forces server delivery. `false` is an error when the app has `api/` or `server.ts`.
`inline`	`boolean`	`false`	Static SPA as one HTML file.
`platform`	`string`	`"web"` (`"desktop"` for Electron)	Selects the platform blocks retained in pages, layouts and the root `index.html` entry shell.
`markdown.linkCheck`	`"error" \| "warn" \| "off"`	`"error"`	How broken Markdown links fail. See Markdown.
`markdown.ignorePaths`	`string[]`	`[]`	Same-site path prefixes not built by Fuzor, such as `"/downloads/"`.
`markdown.highlight`	`{ theme }` or `true`	off	Build-time syntax highlighting with Shiki. See Markdown.
`redirects`	`Record<string, string>`	none	Permanent redirects. See routing.
`adapter`	`"node" \| "cloudflare"`	`"node"`	Server deployment target. `"cloudflare"` also writes a Worker and `wrangler.jsonc`, and implies server output. See deployment.
`viewTransitions`	`boolean`	`false`	Animate SPA navigation. See routing.
`prefetch`	`"intent" \| false`	`false`	Download a page's island code on link hover or focus.
`searchIndex`	`boolean \| { scope }`	`false`	Write `search-index.json` with the title, headings and text of every page (or pages below `scope`, such as `"/docs/"`) for client-side search. See Markdown.
`runtimes`	`Record<string, Record<string, string>>`	none	Extra framework versions under npm aliases, such as `{ react18: { react: "react-18", "react-dom": "react-dom-18" } }`, used by islands named `*.react18.tsx`. See islands.
`navigation`	`"auto" \| "navigation-api" \| "embedded"`	`"auto"`	Which SPA router the build includes. See router builds.
`routeTypes`	`boolean`	`true`	Write `.fuzor/routes.d.ts` for typed links.
`generator`	`boolean`	`true`	Add `<meta name="generator" content="Fuzor">` to compiled documents for technology detectors. No version, tracking or network request is included. `false` skips insertion; existing caller tags and Fuzor elements remain.

fuzorPlugin({
  markdown: { ignorePaths: ["/downloads/"] },
  redirects: { "/blog/": "/articles/", "/chat/": "https://discord.example/" }
})

How settings combine

The CLI flags --target, --server and --inline reach the plugin through environment variables. Each setting is resolved in this order:

FUZOR_TARGET (spa, mpa or electron), FUZOR_PLATFORM (a lowercase platform selector), FUZOR_ADAPTER (node or cloudflare), FUZOR_SERVER and FUZOR_INLINE (1, 0, true or false), usually set by CLI flags;
the default.

Server delivery is additionally switched on by api/ endpoints and server.ts modules, as described in build profiles.

Platform-specific entrypoints

Use fuzor:platform comments when one source tree needs small differences for web, desktop, mobile or another named platform:

<!--fuzor:platform --desktop-->
<desktop-toolbar></desktop-toolbar>
<!--/fuzor:platform-->

<!--fuzor:platform --mobile-->
<mobile-toolbar></mobile-toolbar>
<!--/fuzor:platform-->

The compiler removes non-matching blocks from pages and layouts. The same comments may wrap markup in the root index.html shell; Fuzor resolves them before rendering the Vite entrypoint, so the selected build receives only its platform shell. Blocks may list several selectors, for example . Blocks cannot be nested.

Select the entrypoint from the CLI:

fuzor dev --target electron                 # desktop by default
fuzor build --target spa --platform mobile
fuzor build --target spa --platform browser-extension-popup

In a Vite config, use fuzorPlugin({ platform: "mobile" }). The CLI flag and FUZOR_PLATFORM must not disagree with that option. Platform names use lowercase letters, digits and hyphens.

Vite settings Fuzor uses

Vite setting	Effect
`base`	A path such as `"/docs-site/"` deploys the app below that path: page links, the router, servers and API endpoints use it. Relative (`"./"`) and absolute-URL bases only affect asset URLs. See routing.
`build.outDir`	Overrides the profile folder (`dist-spa`, `dist-mpa-server/client`, …). Server builds write `server/` next to it. Builds with a custom `outDir` are written in place instead of being staged.
`root`	The folder containing `index.html`, `pages/` and the other project folders.
`plugins`	Framework plugins for islands, for example `@vitejs/plugin-react` with `include: /\.react\.[jt]sx$/`. See islands.

Build output and CI

fuzor build stages output in .fuzor-stage-<pid>/ and holds .fuzor-build.lock while it runs; add both to .gitignore.
Plain vite build works too and writes to the same profile folders, but without staging and without the CLI's summary.
Only one build per project runs at a time. A lock left by a crashed process is replaced automatically.

Vite environments

Fuzor works with Vite 6, 7 and 8. Its Environment API is detected at runtime and is never required: older or customized Vite installations use the legacy SSR module graph. When the API is available, applications may opt in to names for the internal client, server, and edge environments:

fuzorPlugin({
  experimental: {
    environments: { server: "node", edge: "cloudflare" },
    runtime: "node"
  }
})

Set runtime: "edge" when developing API or server-data modules against the configured edge environment. This remains experimental and falls back to the legacy Vite SSR module graph when the selected environment cannot load modules. Production server bundles continue to use Fuzor's deterministic generated entrypoint.

This is an internal integration point and does not change Fuzor's public module runtime contract. server remains the default for request-time modules, and unsupported production environment builds retain the deterministic generated server entry and legacy fallback.

On this page

@media (max-width: 800px) { .docs-desktop-menu { display: block; } .docs-menu { display: none; } } .docs-theme-switch, .docs-outline, fuzor-tooltip-positioner { display: none; } .docs-article fuzor-tabs-content[hidden], .docs-article fuzor-accordion-content[hidden] { display: block !important; }