void 0.1.6 → 0.7.0

package/skills/void/docs/guide/deployment.md

@@ -0,0 +1,98 @@
+---
+outline: deep
+---
+
+# Deployment
+
+Void apps run on Cloudflare's infrastructure but you don't need to use your own Cloudflare account. Our long term goal is to provide a simpler app-centric deployment experience similar to that of Vercel and Netlify. But right now, Void only supports deploying via the CLI or GitHub actions.
+
+## CLI
+
+### First deploy
+
+```bash
+void init               # can handle auth + project setup during onboarding
+void deploy             # auto-detects app type, builds, deploys
+```
+
+If you skipped Void project setup during `void init`, you can still run `void auth login` manually. On first deploy, the CLI will prompt you to create or select a project if none is linked yet. The project link is saved to `.void/project.json` for subsequent deploys.
+
+### Migrations
+
+If your app uses Drizzle, `void deploy` runs migrations as part of the deploy flow:
+
+1. Build the app
+2. Read SQL migrations from `db/migrations/`
+3. Fail if the schema has drifted ahead of the committed migrations
+4. Apply pending migrations to the target database
+5. Make the new deploy live
+
+Deploy always uses checked-in migration files. If drift is detected, run `void db generate`, review the generated migration, commit it yourself, then rerun deploy. For the full database workflow and backend-specific details, see the [Database guide](./database.md).
+
+### Flags
+
+```bash
+void deploy [--project <name>] [--dir <path>] [--spa]
+```
+
+| Flag               | Purpose                                           |
+| ------------------ | ------------------------------------------------- |
+| `--project <name>` | Target a specific project by slug                 |
+| `--dir <path>`     | Deploy a pre-built static directory (skips build) |
+| `--spa`            | Use SPA mode instead of SSG for static deploys    |
+
+### Project resolution
+
+The CLI resolves which project to deploy to in this order:
+
+1. `--project <name>` flag
+2. `VOID_PROJECT` environment variable
+3. Linked project in `.void/project.json`
+
+If none match, the CLI prompts interactively.
+
+### CI preparation
+
+If your CI pipeline runs typechecking or other static analysis before deploy, run `void prepare` after install to generate the `.void/` artifacts without booting Vite.
+
+### Environment variables
+
+| Variable       | Purpose                          |
+| -------------- | -------------------------------- |
+| `VOID_TOKEN`   | Auth token (for CI, skips OAuth) |
+| `VOID_PROJECT` | Project slug override            |
+
+## GitHub Actions
+
+You can deploy from a GitHub repo with a simple GitHub Actions workflow. Running `void init --github` will generate this as `.github/workflows/deploy.yml` in your project:
+
+```yaml
+name: Deploy
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install
+      - run: pnpm void deploy
+        env:
+          VOID_TOKEN: ${{ secrets.VOID_TOKEN }}
+          VOID_PROJECT: my-app
+```
+
+To get a deploy token, run `void auth token` to copy it to your clipboard, then add it as a GitHub Actions secret.
+
+## Other Targets
+
+If you prefer to deploy directly to your own Cloudflare account instead of using Void's managed platform, see the [Cloudflare integration guide](../integrations/cloudflare.md).
+
+To deploy to Node.js, Bun, or Deno instead of Cloudflare, set [`target`](../reference/config.md) in `void.json`. This builds a standalone server you can run anywhere, including Docker, Railway, and Fly.io. These targets do not have access to Void platform features such as D1, KV, R2, built-in auth, Workers AI, or cron scheduling. See the [Node.js, Bun, and Deno guide](../integrations/nodejs-bun-deno.md).

package/skills/void/docs/guide/edge/headers.md

@@ -0,0 +1,79 @@
+---
+outline: deep
+---
+
+# Custom Headers
+
+Define custom response headers in [`void.json`](../../reference/config) using the `routing.headers` field. Keys are URL patterns, values are arrays of `"Name: value"` strings.
+
+```json
+{
+  "routing": {
+    "headers": {
+      "/assets/*": ["Cache-Control: public, max-age=31536000, immutable"],
+      "/*": ["X-Frame-Options: DENY", "X-Content-Type-Options: nosniff"],
+      "/*.html": ["Cache-Control: no-cache"]
+    }
+  }
+}
+```
+
+## Rules
+
+- **Pattern keys** start with `/`. `*` matches any characters including `/`.
+- **Header values** use `Name: value` format. The value may contain colons.
+- All matching rules are merged. When multiple rules set the same header name, the **last match wins**.
+- User-defined `Cache-Control` overrides the built-in default. The default still applies when no rule matches.
+
+## Example: security headers
+
+```json
+{
+  "routing": {
+    "headers": {
+      "/*": [
+        "X-Frame-Options: DENY",
+        "X-Content-Type-Options: nosniff",
+        "Referrer-Policy: strict-origin-when-cross-origin"
+      ]
+    }
+  }
+}
+```
+
+## Example: override caching
+
+```json
+{
+  "routing": {
+    "headers": {
+      "/*.html": ["Cache-Control: public, max-age=300"],
+      "/config.json": ["Cache-Control: no-store"]
+    }
+  }
+}
+```
+
+## Scope
+
+Header rules apply to **all responses** served through the dispatch worker, including static assets, SSR pages, and API routes. They do not apply to:
+
+- Hashed asset cache hits (these use immutable caching set by the dispatch worker itself)
+- ISR cache responses (these have their own cache-control headers)
+
+## Framework `_headers` files
+
+Meta-frameworks like SvelteKit, Nuxt, and Astro generate a `_headers` file with cache rules for their hashed asset directories. Void automatically parses this file during deploy and merges the rules into the deploy manifest.
+
+- Framework-generated rules are applied **before** `void.json` rules. Since the last match wins, `routing.headers` in `void.json` takes precedence and can override framework defaults.
+- The `_headers` file is not uploaded as a static asset. Its contents are parsed and included in the manifest only.
+
+No configuration is needed. If the framework generates a `_headers` file, it is picked up automatically.
+
+## How headers work
+
+1. `void deploy` reads header rules from the framework `_headers` file (if present) and `routing.headers` in `void.json`, then includes them in the deploy manifest.
+2. The platform stores the rules in the KV routing entry for your project.
+3. The dispatch worker applies matching rules to static responses before edge caching.
+
+Because rules are evaluated at the edge, there is no extra latency cost. Headers are applied inline before the response is returned and cached.

package/skills/void/docs/guide/edge/prerendering.md

@@ -0,0 +1,83 @@
+---
+outline: deep
+---
+
+# Edge Prerendering
+
+You can instruct Void to prerender a page so it is served from cache immediately after a new deploy. Prerendering happens on the platform at deploy time. The platform invokes the uploaded worker and writes the result to the edge cache.
+
+- [Markdown pages](../pages-routing/markdown.md) are auto-prerendered.
+- [Island pages](../pages-routing/islands) with no companion loader and no dynamic params are also auto-prerendered.
+
+## Static pages (no params)
+
+Export `prerender = true` from the companion `.server.ts` file:
+
+```ts
+// pages/about.server.ts
+export const prerender = true;
+
+export const loader = defineHandler(async (c) => {
+  // ...
+});
+```
+
+Pages with no dynamic params are automatically prerendered at their URL pattern (e.g. `/about`).
+
+## Dynamic pages (with params)
+
+For pages with URL params, also export `getPrerenderPaths()` to specify which param combinations to prerender:
+
+```ts
+// pages/blog/[slug].server.ts
+export const prerender = true;
+
+export async function getPrerenderPaths() {
+  // Return param objects matching the URL pattern
+  return [{ slug: 'hello-world' }, { slug: 'getting-started' }];
+}
+
+export const loader = defineHandler(async (c) => {
+  // ...
+});
+```
+
+## Custom SSR
+
+In custom SSR mode (`src/main.ssr.ts`), export `getPrerenderPaths()` at the top level. Since there's no file-based routing, return full path strings:
+
+```ts
+// src/main.ssr.ts
+export const prerender = true;
+
+export async function getPrerenderPaths() {
+  return ['/', '/about', '/blog/hello-world'];
+}
+
+export default defineRender(async (c, assetTags) => {
+  // ...
+});
+```
+
+## Relationship to revalidation
+
+Pages with long revalidate TTLs (e.g. 1 year) are effectively static, but the first visitor after a deploy hits a cold cache. This is where prerendering helps - it ensures your users never get slow requests.
+
+Enabling prerendering for a page automatically sets `revalidate` to 1 year, so you don't need to export it yourself. Since the ISR cache is cleared on every deploy, the TTL only needs to be long enough to last between deploys.
+
+You can also explicitly set to it a different value to override the default:
+
+```ts
+// pages/about.server.ts
+export const prerender = true;
+export const revalidate = 3600;
+```
+
+Just be aware that if no new deploy happens before the revalidate expires, the first user request after expiration will miss the cache and incur a full render.
+
+## Behavior details
+
+- Prerender happens once per deployment, before traffic is routed to the new version. Prerendered pages are cached at the edge.
+- Each deploy clears the ISR cache. The deployment shows `"prerendering"` during this phase.
+- Only paths with a positive revalidate TTL are prerendered (TTL `0` is skipped).
+- Prerender failures are logged but never block the deploy. The page will render on the first request as usual.

package/skills/void/docs/guide/edge/redirects.md

@@ -0,0 +1,116 @@
+---
+outline: deep
+---
+
+# Redirects
+
+Define URL redirects in [`void.json`](../../reference/config) using the `routing.redirects` field. Keys are source URL patterns, values are destination strings or objects with an explicit status.
+
+```json
+{
+  "routing": {
+    "redirects": {
+      "/old": "/new",
+      "/blog/*": { "to": "/posts/:splat", "status": 301 }
+    }
+  }
+}
+```
+
+## Rules
+
+- **Source patterns** start with `/`. `*` matches any characters including `/`.
+- **Destinations** can be strings (default `302`) or objects with `to` and optional `status`. Supported statuses: `301`, `302`, `303`, `307`, `308`.
+- `:splat` in the destination is replaced with the portion of the path matched by `*` in the source pattern.
+- Destination query strings are merged into the `Location` header (the destination's parameters take precedence on per-key conflict). To drop the incoming query, write an explicit reset like `?`.
+- When multiple rules match, the **first match wins**. Put more-specific rules above more-general ones (matches Netlify `_redirects` and Vercel `vercel.json` semantics).
+- Redirects are evaluated **before** the request reaches the worker, so they short-circuit static asset serving, ISR, and SSR.
+
+## Example: permanent redirect
+
+```json
+{
+  "routing": {
+    "redirects": {
+      "/old-page": { "to": "/new-page", "status": 301 }
+    }
+  }
+}
+```
+
+## Example: path prefix migration
+
+```json
+{
+  "routing": {
+    "redirects": {
+      "/blog/*": { "to": "/posts/:splat", "status": 301 }
+    }
+  }
+}
+```
+
+A request to `/blog/hello-world` redirects to `/posts/hello-world` with a `301` status.
+
+## Domain-level redirects
+
+Scope a redirect to a specific Host header by prefixing the source with `https://host`. Useful for:
+
+- **Domain consolidation** — redirect everything from an old marketing domain to a new one without per-host deploy config.
+- **Canonical host enforcement** — `www.example.com` → `example.com`.
+- **Per-domain rules on a multi-domain project** — when you've bound several custom domains to one project but want different behavior on each.
+
+```json
+{
+  "routing": {
+    "redirects": {
+      "https://www.example.com/*": "https://example.com/:splat",
+      "https://old-marketing.com/*": "https://example.com/:splat"
+    }
+  }
+}
+```
+
+The `_redirects` file accepts the same syntax:
+
+```
+https://www.example.com/*  https://example.com/:splat  301!
+```
+
+The host portion is split off the source and stored as a `host` field on the rule. Path-only sources (no `https://` prefix) apply to every domain bound to the project — that's the existing behavior. Host-prefixed sources only fire when the request's `Host` header matches.
+
+### Validation
+
+- The host must be a literal hostname — wildcards (`*.example.com`), ports, paths, and userinfo are rejected.
+- Only `https://` is accepted. `http://` and protocol-relative `//` sources are rejected — TLS terminates upstream of the worker, so an `http://`-scoped rule physically cannot fire.
+- The host must be **bound to your project** (either `<slug>.void.app` or a custom domain you've added via `void domain add`). `void deploy` rejects rules scoped to hosts that aren't on the project — staging the rule in the same change as the domain is the recommended flow.
+- Custom domains in `pending` (DCV-in-progress) state are accepted. The rule deploys but stays inert until DCV completes; once the certificate is issued, the rule starts firing automatically without a redeploy.
+
+### Combined with external destinations
+
+The source `host` and the destination URL are independent. Combining them lets you express domain-consolidation redirects in a single rule:
+
+```
+https://old.example.com/*  https://www.example.com/:splat  301!
+```
+
+Reads as "when a request hits `old.example.com` on any path, send a 301 to the same path on `www.example.com`."
+
+## Framework `_redirects` files
+
+Meta-frameworks may generate a `_redirects` file during build. Void parses this file at deploy time and merges the rules into the deploy manifest.
+
+- `void.json` rules are applied **before** framework-generated `_redirects` rules. Since the first match wins, `routing.redirects` in `void.json` takes precedence.
+- Both 3xx redirect rules and status `200` [rewrite rules](./rewrites) are supported in `_redirects` files.
+- The `!` force suffix is only meaningful on `200` entries (see [rewrites — `_redirects` file](./rewrites#redirects-file)). On 3xx entries (`301!`, `302!`, `307!`, `308!`) it's silently stripped — a redirect always "forces" by nature, so the suffix is redundant. `void deploy` prints a single aggregated warning tallying every such entry so you can clean them up.
+- The `_redirects` file is not uploaded as a static asset. Its contents are parsed and included in the manifest only.
+
+Precedence when the same source appears in both sources follows the same rules as rewrites — config rules are merged before file rules within each phase, and first match wins, so `void.json` overrides `_redirects`. See [Precedence: `_redirects` vs `void.json`](./rewrites#precedence-redirects-vs-void-json) for the full explanation and a worked example.
+
+## How redirects work
+
+1. `void deploy` reads redirect rules from the framework `_redirects` file (if present) and `routing.redirects` in `void.json`, then includes them in the deploy manifest.
+2. The platform stores the rules in the KV routing entry for your project.
+3. The dispatch worker checks redirect rules before any worker invocation, so matching requests get a redirect response immediately.
+
+Because rules are evaluated at the edge before invoking the worker, redirects add no latency to the request path.

package/skills/void/docs/guide/edge/revalidation.md

@@ -0,0 +1,131 @@
+---
+outline: deep
+---
+
+# Revalidation (ISR)
+
+For SSR and [Pages mode](../pages-routing/overview) projects, Void supports stale-while-revalidate caching for dynamically rendered pages. Cached pages are served instantly from the edge while the worker re-renders in the background when the cache is stale. This is the equivalent of [Incremental Static Regeneration (ISR)](https://vercel.com/docs/incremental-static-regeneration) in other frameworks.
+
+This requires [SSR](../ssr.md) or [Pages mode](../pages-routing/overview) to be configured.
+
+## Enabling revalidation
+
+Add a `routing.revalidate` field to `void.json` with a TTL in seconds:
+
+```json
+{
+  "routing": {
+    "revalidate": 60
+  }
+}
+```
+
+Setting `revalidate` to `0` disables revalidation (equivalent to plain SSR).
+
+## Per-path revalidation
+
+You can set different TTLs for different URL patterns using an object:
+
+```json
+{
+  "routing": {
+    "revalidate": {
+      "/": 60,
+      "/docs/*": 31536000,
+      "/user/*": 0,
+      "*": 30
+    }
+  }
+}
+```
+
+Rules are matched in order, and the first match wins. The `*` glob matches any characters including `/`.
+
+Special values:
+
+- `31536000` (1 year): effectively cached until the next deploy, since deploys clear the ISR cache
+- `0`: never cached and always rendered by the worker, which is equivalent to plain SSR for that path
+
+## Per-page revalidation (Pages mode)
+
+In [Pages mode](../pages-routing/overview), you can export a `revalidate` value from a `.server.ts` file to override the global config for that page:
+
+```ts
+// pages/products/index.server.ts
+export const revalidate = 120; // cache for 2 minutes
+
+export const loader = defineHandler(async (c) => {
+  // ...
+});
+```
+
+Per-page values take precedence over `void.json` patterns.
+
+## Precedence
+
+When multiple sources set a revalidate TTL, the most specific wins:
+
+1. `x-revalidate` response header (per-response)
+2. `.server.ts` export (per-page, Pages mode only)
+3. `void.json` `routing.revalidate` path pattern match
+4. `void.json` `routing.revalidate` global number or `"*"` fallback
+
+## How revalidation works
+
+1. **First request:** there is no cache entry yet. The worker renders the page, returns the response, and writes the result to KV in the background.
+
+2. **Subsequent requests (fresh):** the cached response is served from the edge cache or KV. No worker call is needed.
+
+3. **Subsequent requests (stale):** the stale cached response is served immediately, and the worker re-renders in the background. The next request gets the fresh version.
+
+This means users never wait for a stale page to re-render. They always get an immediate response.
+
+## Per-response TTL override
+
+Route handlers can set the `x-revalidate` response header to override the TTL for a specific response:
+
+```ts
+export const GET = defineHandler(async (c) => {
+  // Don't cache this particular response
+  c.header('x-revalidate', '0');
+
+  return c.html('...');
+});
+```
+
+- `x-revalidate: 0`: skip caching for this response
+- `x-revalidate: 300`: cache for 5 minutes instead of the default
+
+Only successful responses (2xx) are cached.
+
+## Cache bypass
+
+Requests with `Cookie` or `Authorization` headers bypass the ISR cache entirely and always dispatch to the worker. This ensures personalized or authenticated pages are never served from a shared cache.
+
+## Cache keys and rewrites
+
+If a request is rewritten at dispatch (`routing.rewrites`, `routing.fallbacks`, or `_redirects` 200/200!), the ISR cache slot is keyed on the **rewritten** pathname **plus** the original request URL's pathname. Query parameters are dropped from rewrite variant keys by default; use `routing.revalidateQueryAllowlist` to keep selected query params when they should vary cached output. So a direct request to `/en/docs/foo` and a rewrite from `/docs/foo → /en/docs/foo` no longer share a slot — each renders and caches independently. Middleware `c.rewrite()` runs after ISR lookup, so it observes rewrite metadata but does not create a separate ISR variant.
+
+`revalidate({ paths })` operates on the rewritten pathname (the slot's primary key). Purging `/en/docs/foo` removes **all variants** (direct + every rewrite source) under that path. Purging the source path (`/docs/foo`) invalidates nothing, because no slot was ever written under it.
+
+**Migration note:** the ISR cache key format bumped to a versioned `v2` prefix alongside this feature, with no reader-side fallback to the previous unversioned format. The first time a project deploys on the new dispatch, **every** pre-existing ISR entry becomes unreachable — not only paths that gained a rewrite rule. Cache slots warm up normally under the new key as traffic comes in; you'll see a one-time cache-miss wave proportional to your traffic × TTL, then the hit rate returns to normal. No manual purge is required, and the stranded entries expire on their own via their original TTLs and deployment age-out. Additionally, if you introduce a rewrite on an existing path (e.g. `/docs/foo` → `/en/docs/foo`), the cache slot for that path moves to the rewritten pathname, so the source path's `v2` slot will cold-start too.
+
+## On-demand revalidation
+
+You can purge ISR cache entries programmatically from a route handler:
+
+```ts
+import { revalidate } from 'void/isr';
+
+export const POST = defineHandler(async (c) => {
+  // ... update content in database ...
+
+  // Purge specific pages
+  await revalidate({ paths: ['/', '/blog/hello-world'] });
+
+  // Or purge all cached pages
+  await revalidate({ all: true });
+
+  return c.json({ ok: true });
+});
+```