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
`deployment`	`"static" \| "github-pages" \| "node" \| "cloudflare"`	none	Validate hosting capabilities; static targets reject request-rendered routes.
`entry`	`string`	none	Select a static SPA subtree for an inline downloaded client.
`server`	`boolean`	automatic	`true` forces server delivery. `false` is an error when the app has `api/` or `server.ts`.
`serverExternal`	`readonly string[]`	`["fuzor", "effect"]`	Packages left as runtime imports in the server bundle. List only host-provided packages; everything else is bundled. See server dependencies.
`routeTree`	`readonly RouteDefinition[]`	none	Explicit SPA hierarchy with unique IDs and JSON handles. Labels existing routes; creates no pages or layouts. See route hierarchies.
`clientRoutes`	`Record<string, string>`	none	Maps runtime SPA patterns to compiled templates. See runtime route templates.
`ui.brand`	`string`	none	Emit `defineBrand(prefix)` before browser application activation. Register components and supply styling separately. See UI brands.
`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

CLI settings reach the plugin through FUZOR_TARGET, FUZOR_PLATFORM, FUZOR_ADAPTER, FUZOR_SERVER and FUZOR_INLINE. An environment/CLI setting and an explicit plugin option must agree; a contradiction fails instead of silently choosing one. When only one is provided it is used, otherwise the default applies. Boolean environment values accept 1, 0, true and false; malformed values fail. Targets are spa, mpa and electron; with no target the default is the mixed web build described in rendering.

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 (`.fuzor/web/dist-spa`, `.fuzor/web/dist-mpa`, …). Backend builds write `.fuzor/dist-backend/` independently of 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. Ignore .fuzor/ to cover outputs, metadata, staging and the lock together.
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; }