Type a query or navigate docs links...
Project structure
Fuzor finds your app by convention. Everything below is relative to the Vite root, usually the folder with vite.config.ts.
my-app/
├── index.html
├── vite.config.ts
├── pages/
│ ├── index.html | index.md
│ ├── layout.html
│ ├── not-found.html | not-found.md
│ ├── error.html | error.md
│ ├── account/
│ │ ├── index.html
│ │ └── server.ts
│ └── blog/[slug]/
│ ├── index.md
│ └── paths.ts
├── layouts/
├── components/
├── islands/
├── api/
└── public/Root files
| File | Purpose |
|---|---|
index.html | The document shell. It must contain <!--fuzor:outlet-start--><!--fuzor:outlet-end-->; a <head> is required for page metadata. Scripts and styles linked here are processed by Vite. Wrap platform-specific shell markup in fuzor:platform blocks. |
vite.config.ts | Adds fuzorPlugin(); see configuration. |
pages/
Each folder with an index file is a route. pages/index.html or pages/index.md (the / route) is required.
| Name | Meaning | Docs |
|---|---|---|
index.html, index.md | The page for this folder's URL. Only one per folder. | Routing |
layout.html | Wraps this folder's page and every page below it. Needs a <slot></slot>. | Layouts |
[name]/, [...name]/ | A dynamic route whose values are listed at build time. | Dynamic routes |
paths.ts | Lists the values of a dynamic folder. | Dynamic routes |
not-found.html, not-found.md | Shown for unknown URLs in this folder and below. | Not-found and error pages |
error.html, error.md | Shown when a page in this folder fails to render in the SPA router or server. | Not-found and error pages |
server.ts | Request-time data for the page in the same folder. Makes the build server-backed. | Server data |
Folders and files starting with . are ignored. paths and server modules can also end in .mts, .js or .mjs.
Other folders
| Folder | Meaning | Docs |
|---|---|---|
layouts/ | Layouts that are not inside pages/: Markdown pages can pick layouts/<name>.html by name, or layouts/docs.html can override the built-in docs layout. | Layouts |
components/ | Build-time HTML components. components/site-card.html is used as <site-card>. Optional. | Components |
islands/ | Interactive modules. islands/charts/sales.tsx is <fuzor-island src="charts/sales">. | Islands |
api/ | HTTP endpoints. api/users/[id].ts answers /api/users/42. Makes the build server-backed. Files and folders starting with _ are private helpers. | API endpoints |
public/ | Files copied unchanged to the build output (Vite's public directory). Markdown links to files are checked against it. | Markdown |
Elements Fuzor compiles
| Element | Becomes |
|---|---|
<fuzor-link href="/about/"> | A normal <a>; the SPA router handles it. |
<fuzor-island src="name"> | An island host; see islands. |
<fuzor-param name="slug"> | The escaped value of a dynamic route parameter. |
<fuzor-data name="user.name">fallback</fuzor-data> | A slot filled with server data after the page loads. |
<fuzor-loading delay="200" min="500"> | A hidden indicator shown while an island's code or the page's server data is slow to load; see islands. |
<fuzor-toc> | The page's heading list, for Markdown pages and their layouts. |
<fuzor-nav scope="/docs/"> | Generated navigation for pages below a path. |
<slot> | Where a layout or component places its content. |
Build output
| Profile | Folder |
|---|---|
| Static SPA | dist-spa/ |
| Static MPA | dist-mpa/ |
| SPA with server | dist-spa-server/client/ and dist-spa-server/server/entry.mjs |
| MPA with server | dist-mpa-server/client/ and dist-mpa-server/server/entry.mjs |
With searchIndex enabled, the client folder also contains search-index.json. Fuzor also writes .fuzor/ in the project root: routes.d.ts for typed links and chunks-*.json for fuzor routes. Add dist-*/, .fuzor/, .fuzor-stage-*/ and .fuzor-build.lock to .gitignore; the starter template already does.