void 0.1.6 → 0.7.0

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

@@ -0,0 +1,74 @@
+---
+outline: deep
+---
+
+# Static Site Generation (SSG)
+
+Set `output: "static"` in `void.json` to prerender all pages at build time:
+
+```json
+{
+  "output": "static"
+}
+```
+
+When `output` is `"static"`:
+
+- All pages default to `prerender = true`, so they are rendered during `vite build` and written as HTML files to `dist/client/`.
+- Use `export const prerender = false` in a page's `.server.ts` to opt out. That page will be server-rendered on request.
+- Dynamic pages without `getPrerenderPaths()` are implicitly not prerendered (the paths aren't known at build time).
+- The build output is self-contained and works for `wrangler deploy`, self-hosting, or `void deploy`.
+
+## How it works
+
+During `vite build`, after both the worker and client bundles are written to disk, Void spins up Miniflare with the built worker and fetches each page. The HTML responses are written to `dist/client/` as static files (e.g. `/about` becomes `dist/client/about.html`).
+
+## Per-page overrides
+
+Individual pages can opt out of prerendering:
+
+```ts
+// pages/dashboard.server.ts
+export const prerender = false;
+```
+
+Dynamic pages with `getPrerenderPaths()` are prerendered for the returned param combinations:
+
+```ts
+// pages/blog/[slug].server.ts
+export async function getPrerenderPaths() {
+  return [{ slug: 'hello-world' }, { slug: 'getting-started' }];
+}
+```
+
+Dynamic pages **without** `getPrerenderPaths()` are not prerendered because the paths are not known at build time. These pages are served dynamically by the worker at runtime.
+
+## Comparison with edge prerendering
+
+| `output` value       | Default prerender | Per-page override                | Prerender timing           |
+| -------------------- | ----------------- | -------------------------------- | -------------------------- |
+| `"server"` (default) | `false`           | `export const prerender = true`  | Deploy-time (platform ISR) |
+| `"static"`           | `true`            | `export const prerender = false` | Build-time (`vite build`)  |
+
+When `output` is omitted or set to `"server"`, behavior is unchanged. `export const prerender = true` opts individual pages into deploy-time [edge prerendering](./edge/prerendering.md).
+
+## Deployment behavior
+
+When you run `void deploy` with `output: "static"`, Void inspects the build output to decide the optimal deploy strategy:
+
+- **Fully static:** if every page is prerendered and there are no API routes, middleware, cron jobs, or queues, Void deploys as a pure static site with no worker.
+- **Hybrid:** if any pages are not prerenderable, such as dynamic pages without `getPrerenderPaths()` or pages with `export const prerender = false`, a worker is deployed to handle those routes at runtime. Prerendered pages are still served as static assets.
+
+You do not need to configure this. Void detects it automatically from your pages and project structure.
+
+## Relationship to `inference.appType: "static"`
+
+The `inference.appType` field describes app type (SPA, static, void), while `output` controls rendering strategy:
+
+|              | `inference.appType: "static"`                   | `output: "static"`                            |
+| ------------ | ----------------------------------------------- | --------------------------------------------- |
+| **What**     | Deploy a pre-built static site (no Void plugin) | Prerender a Void app at build time            |
+| **Worker**   | None (static assets only)                       | Only if some pages can't be prerendered       |
+| **Use case** | VitePress, plain HTML, external SSG tools       | Void apps with mostly or fully static content |
+
+When all pages are prerendered and there are no backend features, `output: "static"` produces the same deploy result as `inference.appType: "static"`: pure static assets with no worker. The difference is that `output: "static"` figures this out by analyzing your build output, while `inference.appType: "static"` is a manual declaration for non-Void projects.

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

@@ -0,0 +1,105 @@
+---
+outline: deep
+---
+
+# Custom SSR
+
+Void supports framework-agnostic SSR via explicit server and client entries. This is for advanced use cases where you want full control over rendering and hydration.
+
+::: tip
+For most apps, [Pages Routing](./pages-routing/overview) handles SSR automatically. You do not need entry files or hydration code.
+:::
+
+## Required entries
+
+SSR mode is enabled when both of these exist:
+
+- `src/main.ssr.ts` or `src/main.ssr.tsx`
+- `src/main.client.ts` or `src/main.client.tsx`
+
+Only one server entry and one client entry may exist.
+If only one side is present, build/deploy fails with a clear error.
+
+## Render API
+
+`src/main.ssr.ts(x)` must export either:
+
+```ts
+render(c: CloudContext, assetTags: RenderAssetTags): Response | Promise<Response>
+```
+
+or:
+
+```ts
+export default defineRender((c, assetTags) => Response | Promise<Response>);
+```
+
+The recommended form is `defineRender(...)` for inferred types.
+
+`assetTags` contains the HTML tags for your client assets:
+
+```ts
+{
+  head: string; // styles/modulepreload/Vite client+preamble (dev)
+  body: string; // main client entry script tag
+}
+```
+
+If no render export is found, build/deploy fails with a clear error.
+
+Example:
+
+```tsx
+import { renderToString } from 'react-dom/server';
+import { defineRender } from 'void';
+import App from './App';
+
+export default defineRender(async (c, assetTags) => {
+  const url = new URL(c.req.raw.url);
+  const html = renderToString(<App url={url.pathname} />);
+  return new Response(
+    `<!doctype html>
+<html>
+  <head>${assetTags.css}${assetTags.preloads}</head>
+  <body>
+    <div id="root">${html}</div>
+    ${assetTags.body}
+  </body>
+</html>`,
+    { headers: { 'content-type': 'text/html; charset=utf-8' } },
+  );
+});
+```
+
+`src/main.client.ts(x)` should hydrate/mount your app:
+
+```tsx
+import { hydrateRoot } from 'react-dom/client';
+import App from './App';
+
+hydrateRoot(document.getElementById('root')!, <App url={window.location.pathname} />);
+```
+
+## Client Asset Injection
+
+Void no longer mutates your rendered HTML automatically.
+You decide whether and where to inject client asset tags.
+
+The `assetTags` values are computed by Void:
+
+- In production: from `dist/client/.vite/manifest.json` (entry script, CSS, modulepreload)
+- In dev: includes Vite HMR client and React refresh preamble (when React plugin is active), plus the client entry script
+
+## Caching
+
+See [Revalidation](./edge/revalidation.md) for stale-while-revalidate caching of SSR pages.
+
+## Request flow
+
+With SSR enabled:
+
+1. `/api/*` requests go to worker API routes
+2. static asset hits are served from R2
+3. unmatched non-API requests fall back to `render(c, assetTags)`
+
+Without SSR entries, non-API requests keep SPA static fallback behavior.

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

@@ -0,0 +1,67 @@
+---
+outline: deep
+---
+
+# Object Storage
+
+Void provides a typed `storage` export for [Cloudflare R2](https://developers.cloudflare.com/r2/). Import it from `void/storage` and use the full R2 API directly.
+
+## Basic Operations
+
+```ts
+import { storage } from 'void/storage';
+
+// Upload
+await storage.put('uploads/photo.jpg', file, {
+  httpMetadata: { contentType: 'image/jpeg' },
+});
+
+// Download
+const object = await storage.get('uploads/photo.jpg');
+if (object) {
+  const data = await object.arrayBuffer();
+}
+
+// Delete
+await storage.delete('uploads/photo.jpg');
+
+// List
+const listed = await storage.list({ prefix: 'uploads/' });
+for (const obj of listed.objects) {
+  console.log(obj.key, obj.size);
+}
+
+// Head (metadata only)
+const head = await storage.head('uploads/photo.jpg');
+```
+
+The `storage` object is a full `R2Bucket`. Every method from the [Cloudflare R2 API](https://developers.cloudflare.com/r2/api/workers/workers-api-reference/) is available directly, with no wrapper layer.
+
+## Serving Files
+
+A common pattern is serving uploaded files from an API route:
+
+```ts
+import { storage } from 'void/storage';
+
+export const GET = defineHandler(async (c) => {
+  const key = c.req.param('key');
+  const object = await storage.get(key);
+
+  if (!object) {
+    return c.notFound();
+  }
+
+  const headers = new Headers();
+  object.writeHttpMetadata(headers);
+  headers.set('etag', object.httpEtag);
+
+  return new Response(object.body, { headers });
+});
+```
+
+## How It Works
+
+Unlike the [database](./database.md) and [KV](./kv.md) clients, `storage` doesn't add any abstraction over the underlying API. The R2 API is already well-designed for direct use, so `storage` is simply a lazy reference to `env.STORAGE` that you can import without manually accessing bindings.
+
+The `createStorage()` factory exists for testing and for frameworks that manage their own routing. It accepts an `R2Bucket` and returns it directly.

package/skills/void/docs/guide/type-safety.md

@@ -0,0 +1,179 @@
+---
+outline: deep
+---
+
+# Type Safety
+
+Void provides end-to-end type safety across the stack. Types come from your source code and Drizzle schema, so you are not hand-writing or duplicating interfaces.
+
+## The Type Pipeline
+
+<img src="./type-pipeline.svg" alt="Type pipeline: Drizzle schema flows to DB types, branching into route handlers (typed fetch), page loaders (component props), and page actions (useForm / action())" style="max-width: 720px; width: 100%;" />
+
+1. **Database types** come from your [Drizzle schema](./database.md#schema-definition). Column types are known at compile time.
+2. **Route handlers:** return types and validator schemas become the generated `RouteMap`, which the [typed fetch](./typed-fetch) client consumes.
+3. **Page loaders:** return types flow into page components as props via `InferProps`.
+4. **Page actions:** validator schemas flow into `useForm` and `action()` for typed data, errors, and URL autocomplete.
+
+All generated types live in `.void/` and update automatically when source files or schema change.
+
+## Database → Handler → Client
+
+Types flow from your Drizzle schema through handlers to the client without any manual annotations:
+
+```ts
+// routes/api/users.ts
+export const GET = defineHandler(async (c) => {
+  return db.select({ name: users.name, email: users.email }).from(users);
+  //     ↑ return type inferred from schema columns
+});
+
+export const POST = defineHandler.withValidator({
+  body: insertUserSchema, // ← derived from Drizzle schema
+})(async (c, { body }) => {
+  return db.insert(users).values(body).returning();
+});
+```
+
+```ts
+// Client: types inferred from handlers above
+const users = await fetch('/api/users');
+//    ↑ { name: string; email: string }[]
+
+await fetch('/api/users', {
+  method: 'POST',
+  body: { name: 'Alice', email: 'alice@example.com' }, // ← typed from validator
+});
+```
+
+The Drizzle schema defines database columns, runtime validation, handler input types, and client-side type checking all at once. For endpoints that don't map to a table, use any [Standard Schema](./server-routing.md#manual-validators) library.
+
+## Loader → Page Props
+
+In [pages mode](./pages-routing/overview), a loader's return type flows into the page component via `InferProps`:
+
+```ts
+// pages/users/index.server.ts
+export type Props = InferProps<typeof loader>;
+
+export const loader = defineHandler(async (c) => {
+  return { users: await db.select().from(users) };
+});
+```
+
+```vue
+<!-- pages/users/index.vue -->
+<script setup lang="ts">
+import type { Props } from './index.server';
+defineProps<Props>(); // ← { users: { id: number; name: string; ... }[] }
+</script>
+```
+
+No manual interface is needed. Props stay in sync with whatever the loader returns.
+
+## Action → useForm
+
+When a page action uses `withValidator()`, the body schema flows through to `useForm`. That gives you typed `data`, typed `errors` keys, and URL autocomplete:
+
+```ts
+// pages/users/create.server.ts
+export const action = defineHandler.withValidator({
+  body: insertUserSchema,
+})(async (c, { body }) => {
+  await db.insert(users).values(body);
+});
+```
+
+```ts
+const form = useForm('/users/create', { name: '', email: '' });
+//                    ^ autocompletes     ^ must match body schema
+
+form.errors.email; // ✓ string | undefined
+form.errors.foo; // ✗ TypeScript error
+```
+
+[Named actions](./pages-routing/actions-and-forms#named-actions) work the same way. The `?actionName` suffix selects the right types for that action:
+
+```ts
+const updateForm = useForm('/users/:id?update', { name: '' }, { params: { id } });
+const deleteForm = useForm('/users/:id?delete', { id: '' }, { params: { id } });
+// Each form's data and errors are typed from their respective validators
+```
+
+The `action()` helper gets the same type checking. See [Actions & Forms](./pages-routing/actions-and-forms) for the full API.
+
+## What Gets Checked
+
+| Layer        | What's type-checked                                                  |
+| ------------ | -------------------------------------------------------------------- |
+| Database     | Table columns, value types, insert/update shapes from Drizzle schema |
+| Handlers     | `c.env` bindings, validator input, return type                       |
+| Fetch client | Route paths, HTTP methods, `body`/`query`/`params`, response type    |
+| `useForm`    | Action URLs, `data` fields, `errors` keys, `reset()` args, `params`  |
+| `action()`   | Action URLs, `data` payload, `params`                                |
+
+## Serialization
+
+Handler return types are transformed via `Serialize<T>` so the client sees what actually arrives over the wire:
+
+| Source type                       | Serialized type                                        |
+| --------------------------------- | ------------------------------------------------------ |
+| `string`, `number`, `boolean`     | unchanged                                              |
+| `Date`                            | `string`                                               |
+| `Response`                        | excluded (passed through at runtime)                   |
+| `bigint`, `Function`, `undefined` | excluded                                               |
+| `Array<T>` / `{ key: T }`         | recursively serialized (function-valued keys stripped) |
+
+## Context Variables
+
+Middleware and handlers share typed data through Hono's context variables. Augment `CloudContextVariables` to define your own:
+
+```ts
+// middleware/01.auth.ts
+declare module 'void' {
+  interface CloudContextVariables {
+    requestId: string;
+  }
+}
+
+export default defineMiddleware(async (c, next) => {
+  c.set('requestId', crypto.randomUUID());
+  await next();
+});
+```
+
+Now `c.get("requestId")` returns `string` everywhere, with no assertion needed. Multiple augmentations across files are [merged together](https://www.typescriptlang.org/docs/handbook/declaration-merging.html).
+
+## Setup
+
+Extend the generated tsconfig in your project:
+
+```json
+{
+  "extends": "./.void/tsconfig.json",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "react-jsx",
+    "types": ["void/env"]
+  },
+  "include": ["src", "routes", "middleware", "crons", "queues"]
+}
+```
+
+If your project already extends another config, use `void init --tsconfig` so Void can patch the file without dropping existing `files` or `compilerOptions.paths` entries. The resulting config may use TypeScript's multi-extends form:
+
+```json
+{
+  "extends": ["./tsconfig.base.json", "./.void/tsconfig.json"],
+  "compilerOptions": {
+    "types": ["void/env"]
+  }
+}
+```
+
+The `.void/tsconfig.json` uses `"files"` and `compilerOptions.paths` for generated declarations such as `routes.d.ts`, `db.d.ts`, and `queues.d.ts`. TypeScript inherits those fields, but `files` and `paths` are replaced rather than deeply merged when another config defines them. `void init --tsconfig` handles the common existing-config cases by adding Void's generated files and aliases directly to the root config when needed.
+
+Run `void prepare` in CI or after a fresh clone, or let `vite dev` / `vite build` generate the `.void/` files during normal app workflows.

package/skills/void/docs/guide/typed-fetch.md

@@ -0,0 +1,113 @@
+---
+outline: deep
+---
+
+# Typed Fetch
+
+Void ships a typed `fetch` client that knows every route in your app. Import it from `void/client` and get autocomplete for paths, type-checked request bodies, and fully inferred response types.
+
+## Basic Usage
+
+```ts
+import { fetch } from 'void/client';
+
+// GET: return type inferred from your handler
+const users = await fetch('/api/users');
+
+// POST: body type-checked against your handler's validator
+await fetch('/api/users', {
+  method: 'POST',
+  body: { name: 'Alice', email: 'alice@example.com' },
+});
+
+// Dynamic params interpolated from the route pattern
+const user = await fetch('/api/users/:id', {
+  params: { id: '42' },
+});
+```
+
+No type annotations needed. Everything is inferred from your route handlers.
+
+## What Gets Type-Checked
+
+The client constrains every part of the request:
+
+- **Paths:** only routes defined in `routes/` are accepted. Typos fail at compile time.
+- **Methods:** only methods exported from the route file are allowed. If a file only exports `GET`, passing `method: "POST"` is an error.
+- **Body, query, params:** when your handler uses [`defineHandler.withValidator()`](./server-routing.md#validation), validator schemas become the input types and the client enforces them at the call site.
+- **Response type:** the return type matches what your handler returns after [JSON serialization](./type-safety.md#serialization).
+
+## Query Parameters
+
+Pass `query` for GET requests with search parameters:
+
+```ts
+// routes/api/search.ts
+export const GET = defineHandler.withValidator({
+  query: z.object({ q: z.string(), page: z.string().optional() }),
+})((c, { query }) => {
+  return { results: [], term: query.q };
+});
+
+// Client: query is type-checked
+const data = await fetch('/api/search', {
+  query: { q: 'hello' },
+});
+// data: { results: never[]; term: string }
+```
+
+## Error Handling
+
+Non-2xx responses throw a `FetchError`:
+
+```ts
+import { fetch, FetchError } from 'void/client';
+
+try {
+  await fetch('/api/users/:id', { params: { id: '999' } });
+} catch (e) {
+  if (e instanceof FetchError) {
+    console.log(e.status); // 404
+    console.log(e.data); // parsed response body
+    console.log(e.response); // raw Response
+  }
+}
+```
+
+## Options
+
+| Option    | Type                     | Description                                                |
+| --------- | ------------------------ | ---------------------------------------------------------- |
+| `method`  | `string`                 | HTTP method. Defaults to `"GET"`.                          |
+| `body`    | `object`                 | Request body (auto-serialized as JSON).                    |
+| `query`   | `Record<string, string>` | Query string parameters.                                   |
+| `params`  | `Record<string, string>` | URL path parameters (`:id` segments).                      |
+| `headers` | `HeadersInit`            | Additional request headers.                                |
+| `signal`  | `AbortSignal`            | Abort signal.                                              |
+| `baseURL` | `string`                 | Base URL prepended to the path. Useful for external calls. |
+| `retry`   | `number`                 | Number of retry attempts (default: 1 for GET).             |
+| `timeout` | `number`                 | Request timeout in milliseconds.                           |
+
+## Isomorphic Fetch During SSR
+
+`fetch()` from `void/client` works during server-side rendering and inside route handlers without an HTTP round-trip. In the worker environment, it calls your Hono app directly through `app.fetch()` and skips the network entirely.
+
+```ts
+// src/main.ssr.tsx
+import { fetch } from "void/client";
+import { defineRender } from "void";
+
+export default defineRender(async (c, assetTags) => {
+  // This calls your API route directly with no HTTP request
+  const data = await fetch("/api/users");
+
+  const html = renderToString(<App users={data} />);
+  return new Response(html, {
+    headers: { "content-type": "text/html" },
+  });
+});
+```
+
+**Automatic header forwarding**: `cookie` and `authorization` headers from the incoming request are automatically forwarded to subrequests, so authentication context is preserved. If you pass these headers explicitly, your values take precedence.
+
+**How it works**: In the browser, `fetch()` uses the normal HTTP client. In the worker, Void redirects the import to a virtual module that calls `app.fetch()` directly using the Hono app instance. AsyncLocalStorage threads the outer request context so headers and `waitUntil()` work correctly.