Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions docs/guide/app-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,48 @@ At the edge, the resolution order is:

**Deploy:** `void deploy` or `void deploy --dir <path>` uploads static files directly. Assets are served from the edge with automatic caching.

## Adding a backend to a static site

A static site generator plus a few API routes is a Void app, not a static site. Auto-detection sees the SSG dependency first (priority 2 below), so if you leave `inference.appType` unset, `void deploy` refuses rather than deploying the site and silently dropping `routes/`. Tell it which you meant.

To deploy the site **and** the backend, run both builds from one command and let Void's build fold the generated site into its client output:

```json
// void.json
{
"inference": {
"appType": "void",
"build": "vitepress build && vite build"
}
}
```

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { voidPlugin } from 'void';

export default defineConfig({
plugins: [voidPlugin()],
// The SSG's output becomes the static assets of the Void build.
publicDir: '.vitepress/dist',
});
Comment thread
Brooooooklyn marked this conversation as resolved.
Resolved
```

`vitepress build` emits the site, then `vite build` copies `publicDir` into `dist/client` and emits the worker into `dist/ssr`. Keep `voidPlugin()` in the **root** `vite.config.ts` only — not in the generator's own config (e.g. `.vitepress/config.ts`).

Because the worker now owns unmatched requests, add [`routing.notFound`](../reference/config.md#routing-notfound) if you want the generator's `404.html` instead of the SPA-style `index.html` fallback:

```json
{ "routing": { "notFound": "404-page" } }
```

To deploy the static output only and **not** the backend, say so explicitly:

```json
{ "inference": { "appType": "static" } }
```

## Auto-Detection

When running `void deploy` and no `inference.appType` is set in `void.json`, the detection logic runs in this order:
Expand All @@ -81,6 +123,7 @@ When running `void deploy` and no `inference.appType` is set in `void.json`, the
| -------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| 1 | `--dir` flag | Static (or SPA with `--spa`) |
| 2 | Known SSG in dependencies (`vitepress`, `@docusaurus/core`) | Static, builds with SSG CLI |
| 2a | ...and backend files also exist | Refused — set `inference.appType` yourself |
| 3 | `@tanstack/react-start`, `@react-router/dev`, `@sveltejs/kit`, `nuxt`, `@analogjs/platform`, or `astro` in deps | Framework |
| 4 | Backend files exist (`routes/`, `pages/`, `middleware/`, `crons/`, `queues/`, SSR entry) | Void app |
| 5 | `vite` or `vite-plus` in dependencies, no backend files | SPA, builds with `vite build` or `vp build` |
Expand Down
23 changes: 23 additions & 0 deletions docs/guide/edge/static-assets.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,29 @@ This is the path needed for preview auth and other middleware. Cloudflare's plat

For Void apps with only `/api` routes, Void keeps the platform SPA fallback and scopes `run_worker_first` to `/api` and `/api/*`. Static assets and non-API SPA navigations stay on the asset platform. API requests, including browser document navigations such as OAuth callbacks, reach the worker instead of being rewritten to `index.html`.

### Unmatched requests

`not_found_handling` decides what the asset layer does with a request that matched no asset and no worker route. Void infers it:

| App shape | Inferred value | Result for an unknown URL |
| ------------------------------------------------- | -------------------------------- | -------------------------------- |
| Pages or SSR | `none` | The worker's own 404 |
| Worker owns HTML, no `pages/`, no SSR entry | `none` + worker fallback | `index.html` with status **200** |
| Asset-first (only `/api` routes, or none) | `single-page-application` | `index.html` with status **200** |
| Framework deploy (SvelteKit, Nuxt, Analog, Astro) | `none` — pinned, not overridable | The framework worker's own 404 |

The middle row is a worker with `middleware/`, a route outside `/api`, a document websocket, or Live, but no `pages/` and no SSR entry. `run_worker_first: ['/**']` sends everything to the worker, which bypasses the platform's SPA switch, so the generated worker does that fallback itself for HTML navigations — after your middleware has run, so auth gates and OAuth callbacks still see the request first.

The SPA fallback is right for a single-page app, where deep links must boot the client router. It is wrong for a site whose HTML was generated per page: unknown URLs return 200 instead of 404, and the generator's `404.html` is never served. Nothing in a built asset tree distinguishes the two, so Void does not guess — override it with [`routing.notFound`](../../reference/config.md#routing-notfound):

```json
{ "routing": { "notFound": "404-page" } }
```

Accepted values are `"single-page-application"`, `"404-page"`, and `"none"`. `run_worker_first` keeps its inferred value, so API routes, auth, and `/__void/*` still reach the worker first. Setting anything other than `"single-page-application"` also turns off the worker-side `index.html` fallback described above — otherwise it would answer the request before `not_found_handling` was ever consulted. With `"404-page"` the worker serves whatever the asset binding returns for the unmatched path, which is Cloudflare's nearest `404.html` — but only for HTML navigations (requests whose `Accept` includes `text/html`), so an API route that deliberately returns a 404 keeps its own body, status and headers. If the build has no `404.html`, the worker's own 404 is kept.

The last row is the exception: `routing.notFound` is **ignored** for SvelteKit, Nuxt, Analog, and Astro deploys, and `void deploy` warns when you set it. Those deploys emit no `run_worker_first`, so the asset layer already answers first and real prerendered files win — `not_found_handling` would only change what the framework's own `env.ASSETS.fetch()` delegation returns, where `"single-page-application"` turns genuine 404s into the prerendered home page at 200 and `"404-page"` takes the 404 away from the framework's own error route. TanStack Start and React Router deploys are not affected; they follow the rows above.

### Generated config

Void owns the generated asset routing policy during dev and build. If a root `wrangler.jsonc` contains stale `not_found_handling` or `run_worker_first` values, Void replaces those fields so generated config cannot accidentally change which layer sees a request first.
Expand Down
1 change: 1 addition & 0 deletions docs/integrations/frameworks/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ Most configuration is inferred automatically. Use `void.json` to override defaul
| `routing.prerender` | Paths to prerender as static HTML at deploy time |
| `routing.revalidate` | Default revalidation TTL in seconds for cached responses |
| `inference.bindings` | Override inferred bindings. You only need this if auto-detection is not doing what you want. Accepts `true` or a custom binding name such as `"db": "MY_DB"`. |
| `routing.notFound` | **Ignored.** SvelteKit, Nuxt, Analog, and Astro pin `not_found_handling` to `"none"` — the framework worker owns unmatched HTML. `void deploy` warns if set. |

See [Configuration](../../reference/config.md) for the full reference.

Expand Down
28 changes: 27 additions & 1 deletion docs/reference/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -378,6 +378,24 @@ Paths to prerender as static HTML at deploy time. Each path must start with `/`.
}
```

#### `routing.notFound`

Override how the asset layer answers a request that matched no asset and no worker route. One of `"single-page-application"`, `"404-page"`, or `"none"`. If omitted, Void infers it — see [Static Assets](../guide/edge/static-assets.md#unmatched-requests).

```json
{
"routing": {
"notFound": "404-page"
}
}
```

Set `"404-page"` when your assets come from a static site generator (VitePress, Docusaurus, …) and you want unknown URLs to serve the generator's own `404.html` with a real HTTP 404. Without it, an app whose only backend is API routes keeps the inferred SPA fallback, so every unknown URL returns `index.html` with a `200` — correct for a single-page app, wrong for a generated site, and bad for crawlers.

`run_worker_first` is untouched, so API routes, auth, and `/__void/*` still reach the worker first. When the worker owns HTML routing it also serves the resolved behavior itself, since `run_worker_first: ["/**"]` means the platform switch never runs — see [Unmatched requests](../guide/edge/static-assets.md#unmatched-requests).

This does **not** apply to SvelteKit, Nuxt, Analog, or Astro deploys: those pin `not_found_handling` to `"none"` because the framework's own worker owns unmatched HTML, and `void deploy` warns if you set `routing.notFound` anyway.

### `inference`

Configuration for build-time inference, including how Void detects your app type, bindings, and build process.
Expand All @@ -403,12 +421,20 @@ Custom names are used in the deploy manifest, Wrangler config generation/sync, r

#### `inference.build`

Override the build command. Useful for frameworks with their own CLIs (Nuxt, Astro) or static apps with custom build scripts. If omitted, the CLI uses the detected default build command for the current app type.
Override the build command. Useful for frameworks with their own CLIs (Nuxt, Astro) or static apps with custom build scripts. If omitted, the CLI uses the detected default build command for the current app type. It applies to every app type, including `"void"` (where the default is `vite build`).

```json
{ "inference": { "build": "nuxt build --preset cloudflare-module" } }
```

The command is run through a shell from the project root, with the project's own `node_modules/.bin` on `PATH`, so bare binaries and `&&` chains work:

```json
{ "inference": { "build": "vitepress build && vite build" } }
```

That chain is how a static site generator and a Void backend ship together — see [Adding a backend to a static site](../guide/app-types.md#adding-a-backend-to-a-static-site).

#### `inference.scanDirs`

Override which directories are scanned for [binding inference](./resource-inference.md). Paths are relative to the project root. Replaces the default directories for the current mode.
Expand Down
5 changes: 5 additions & 0 deletions packages/void/schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,11 @@
"type": "object",
"description": "Routing configuration — headers, redirects, rewrites, fallbacks, revalidation, prerendering.",
"properties": {
"notFound": {
"type": "string",
"enum": ["single-page-application", "404-page", "none"],
"description": "Override how the asset layer answers a request that matched no asset and no worker route. Void infers \"single-page-application\" when the worker does not own HTML routing; set \"404-page\" for a static-site-generator build so unknown URLs serve 404.html with a real HTTP 404 instead of index.html with a 200. Does not change run_worker_first. Ignored for SvelteKit, Nuxt, Analog, and Astro deploys, which pin not_found_handling to \"none\" because the framework's own worker owns unmatched HTML."
},
"revalidate": {
"description": "Edge caching TTL in seconds. A number sets a global TTL for all SSR pages. An object maps URL patterns to TTLs (first match wins). Set to 0 to disable caching for a path.",
"oneOf": [
Expand Down
35 changes: 34 additions & 1 deletion packages/void/src/asset-routing.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import type { AssetConfig } from './cli/types.ts';
import type { NotFoundHandling } from './config.ts';
import type { RouteDefinition } from './router/parse-filename.ts';

export type AssetRoutingInputs = {
Expand All @@ -11,6 +12,13 @@ export type AssetRoutingInputs = {
hasWebSockets?: boolean;
authEnabled?: boolean;
liveEnabled?: boolean;
/**
* `routing.notFound` from void.json. Overrides the INFERRED
* `not_found_handling`. `run_worker_first`, `workerFirst` and
* `apiWorkerFirst` are untouched, so which layer sees a request first never
* changes. `workerSpaFallback` DOES follow it — see below.
*/
notFound?: NotFoundHandling;
};

export type AssetRoutingPolicy = {
Expand Down Expand Up @@ -76,10 +84,35 @@ export function resolveAssetRoutingPolicy(inputs: AssetRoutingInputs): AssetRout
not_found_handling: 'single-page-application',
run_worker_first: [...VOID_INTERNAL_WORKER_FIRST],
};
// Explicit `routing.notFound` wins over the inferred value. Applied here (on
// the inputs) rather than at the call sites so dev, build, and deploy can't
// drift apart. `run_worker_first` is deliberately left as inferred.
if (inputs.notFound !== undefined) {
assetConfig.not_found_handling = inputs.notFound;
Comment thread
Brooooooklyn marked this conversation as resolved.
Resolved
}
return {
assetConfig,
apiWorkerFirst,
workerFirst,
workerSpaFallback: workerFirst && !inputs.isSsr && !inputs.hasPages,
// The worker-side SPA fallback exists to REPLACE the SPA behavior the
// INFERRED config gives up on this shape: `workerFirst` infers
// `not_found_handling: 'none'`, so `env.ASSETS.fetch()` hands back a bare
// 404 for an unmatched navigation and the worker has to hardcode
// `/index.html` at status 200 itself.
//
// `run_worker_first: ['/**']` is NOT what disables the platform switch — it
// only decides who sees the request FIRST. It skips the pre-worker asset
// layer, but `not_found_handling` still applies inside `env.ASSETS.fetch()`.
//
// So an explicit `notFound` that asks for anything else must turn the
// fallback off, or the generated helper answers the unmatched navigation
// with the shell before `not_found_handling` is ever consulted and the
// override is inert. `single-page-application` keeps it (that is what it
// asks for); `undefined` keeps the inferred behavior.
workerSpaFallback:
workerFirst &&
!inputs.isSsr &&
!inputs.hasPages &&
(inputs.notFound === undefined || inputs.notFound === 'single-page-application'),
Comment thread
Brooooooklyn marked this conversation as resolved.
Resolved
};
}
Loading