void 0.21.9 → 0.23.0

package/skills/void/docs/integrations/nodejs-bun-deno.md

@@ -10,16 +10,6 @@ Set `target` in `void.config.ts` to build for Node.js, Bun, or Deno. You can run
 { "target": "node" }
 ```
 
-## Supported Targets
-
-| Target   | Server                                                                    | Static Assets                    |
-| -------- | ------------------------------------------------------------------------- | -------------------------------- |
-| `"node"` | [`@hono/node-server`](https://github.com/honojs/node-server)              | `@hono/node-server/serve-static` |
-| `"bun"`  | [`Bun.serve()`](https://bun.sh/docs/api/http)                             | `hono/bun`                       |
-| `"deno"` | [`Deno.serve()`](https://docs.deno.com/runtime/fundamentals/http_server/) | `hono/deno`                      |
-
-All three produce the same project structure and use the same Hono-based routing. The only difference is the HTTP server and static file middleware.
-
 ## Getting Started
 
 ### 1. Configure the target
@@ -43,7 +33,7 @@ npm install @hono/node-server
 npx vite dev
 ```
 
-The dev server runs your Hono routes in Node.js through Vite's SSR module loading. You get the same hot-reload experience as the Cloudflare target, but without `workerd`.
+The development server reloads routes and pages when you edit them.
 
 ### 4. Build and run
 
@@ -68,7 +58,7 @@ deno run -A dist/ssr/index.js
 
 Run these commands from your app directory. The server listens on `PORT` (env variable) or `3000` by default.
 
-Pages builds load their client manifest from `dist/client/.vite/manifest.json` and serve the generated JavaScript, CSS, and public assets. Keep `dist/ssr` and `dist/client` together when deploying. Asset paths resolve from the emitted server module, so the app also works when imported or started from another working directory.
+Deploy `dist/ssr` and `dist/client` together.
 
 ## Build Output
 
@@ -120,7 +110,7 @@ The following imports are **not available** with a non-CF target and produce a c
 
 If you need a database or storage, use an external provider and connect via standard Node.js libraries.
 
-Void-managed WebSocket route files (`*.ws.ts`) are still Cloudflare-only because they compile to Durable Objects. The `void/ws` subpath is not compile-time blocked on non-CF targets, so browser-side `connect()` code can still be bundled when a WebSocket runtime is available.
+WebSocket route files (`*.ws.ts`) require Cloudflare. You can still use the `void/ws` browser client to connect to a separately hosted WebSocket server.
 
 ### No cron job runtime
 
@@ -128,11 +118,11 @@ You can still define [cron jobs](../guide/jobs.md) in `crons/` and they will com
 
 ### No inbound email
 
-Inbound [email handlers](../guide/email.md#inbound) in `email/` need Cloudflare Email Routing to invoke the worker's `email()` export, and the Node.js entry exposes HTTP only. An `email/` directory fails the build with guidance. Outbound `sendEmail` has no send transport on these targets either: it returns a `BINDING_MISSING` error.
+[Inbound email handlers](../guide/email/receiving.md#inbound) and `sendEmail` require Cloudflare. Use an external mail provider on other targets.
 
 ### No prerendering
 
-[Prerendering](../guide/edge/prerendering.md) is a platform feature that relies on Cloudflare's edge cache and the Void deploy pipeline. It is not available for non-CF targets.
+[Edge prerendering](../guide/edge/prerendering.md) requires Cloudflare. Build-time [static generation](../guide/ssg.md) is available on all targets.
 
 ### No `void deploy`
 
@@ -149,60 +139,6 @@ Void warns and ignores these Cloudflare-specific `void.config.ts` fields on othe
 
 If you enable auth through `void/auth`, `void/client`, or `auth.ts`, Void fails the build for non-CF targets. Use Better Auth directly for Node/Bun/Deno deployments.
 
-## Example: API + Pages
-
-A typical Node.js Void app with API routes and React pages:
-
-```
-my-app/
-  pages/
-    layout.tsx
-    index.tsx
-    index.server.ts
-    about.tsx
-    about.server.ts
-  routes/
-    api/
-      hello.ts
-  package.json
-  vite.config.ts
-  void.config.ts
-```
-
-```json
-// void.config.ts
-{ "target": "node" }
-```
-
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite';
-import { voidPlugin } from 'void';
-import { voidReact } from '@void/react/plugin';
-
-export default defineConfig({
-  plugins: [voidPlugin(), voidReact()],
-});
-```
-
-```ts
-// routes/api/hello.ts
-import { defineHandler } from 'void';
-
-export const GET = defineHandler((c) => {
-  return c.json({ message: 'Hello from Node.js!' });
-});
-```
-
-```bash
-# Development
-npx vite dev
-
-# Production
-npx vite build
-node dist/ssr/index.js
-```
-
 ## Programmatic Usage
 
 Since `app.js` exports the Hono app, you can import it into a custom server:

package/skills/void/docs/reference/api/auth.md

@@ -0,0 +1,156 @@
+---
+outline: deep
+---
+
+# Authentication {#auth}
+
+Imported from `"void"` or `"void/auth"`. Client-side helpers imported from `"void/client"`.
+
+## `defineAuth(config)` {#defineauth-config}
+
+Advanced escape hatch for customizing Void's Better Auth config.
+
+```ts
+import { defineAuth } from 'void/auth';
+
+export default defineAuth(({ defaults }) => ({
+  ...defaults,
+  trustedOrigins: ['https://example.com'],
+}));
+```
+
+**Signature:**
+
+```ts
+function defineAuth(config: VoidAuthConfig): VoidAuthConfig;
+```
+
+## `getUser()` {#getuser}
+
+Returns the current authenticated user, or `null` when no user is present.
+
+```ts
+import { getUser } from 'void/auth';
+
+const user = getUser();
+```
+
+**Signature:**
+
+```ts
+function getUser(): AuthUser | null;
+```
+
+## `getSession()` {#getsession}
+
+Returns the current Better Auth request state, or `null`.
+
+```ts
+import { getSession } from 'void/auth';
+
+const state = getSession();
+```
+
+**Signature:**
+
+```ts
+function getSession(): AuthState | null;
+```
+
+## `requireAuth(c)` {#requireauth-c}
+
+Extracts the authenticated user from the request context. Throws a 401 `HTTPException` if no session is present.
+
+```ts
+import { defineHandler } from 'void';
+import { requireAuth } from 'void/auth';
+
+export const GET = defineHandler((c) => {
+  const user = requireAuth(c);
+  return { email: user.email };
+});
+```
+
+**Signature:**
+
+```ts
+function requireAuth(c: CloudContext): AuthUser;
+```
+
+## `AuthUser` {#authuser}
+
+Better Auth user shape re-exported by Void.
+
+```ts
+interface AuthUser {
+  id: string;
+  email: string;
+  emailVerified: boolean;
+  name: string;
+  image?: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+## `AuthSession` {#authsession}
+
+Better Auth session shape re-exported by Void.
+
+```ts
+interface AuthSession {
+  id: string;
+  token: string;
+  userId: string;
+  expiresAt: Date;
+  createdAt: Date;
+  updatedAt: Date;
+  ipAddress?: string | null;
+  userAgent?: string | null;
+}
+```
+
+## `AuthState` {#authstate}
+
+Combined authenticated request state:
+
+```ts
+interface AuthState {
+  user: AuthUser;
+  session: AuthSession;
+}
+```
+
+## `auth` {#auth-1}
+
+Imported from `"void/client"`. This is a ready-to-use Better Auth client instance preconfigured with `basePath: "/api/auth"`.
+
+```ts
+import { auth } from 'void/client';
+
+await auth.signIn.email({ email, password });
+await auth.signOut();
+```
+
+The exact client methods come from Better Auth. In pages apps, Void automatically chooses the framework-specific Better Auth client package when available.
+
+For regular SPA apps that use Void for API/file routes without Void Pages mode, import the framework-specific client explicitly:
+
+```ts
+import { auth } from 'void/client/react';
+// or: 'void/client/vue'
+// or: 'void/client/svelte'
+// or: 'void/client/solid'
+```
+
+Those subpaths keep the same `fetch`, `fetchStream`, and auth exports as `void/client`, but bind `auth` and `createAuthClient` to Better Auth's framework package.
+
+## `createAuthClient` {#createauthclient}
+
+Imported from `"void/client"`. Re-export of Better Auth's `createAuthClient` for advanced usage.
+
+```ts
+import { createAuthClient } from 'void/client';
+
+const auth = createAuthClient({ basePath: '/api/auth' });
+```

package/skills/void/docs/reference/api/client.md

@@ -0,0 +1,87 @@
+---
+outline: deep
+---
+
+# Fetch Client {#fetch-client}
+
+Imported from `"void/client"`.
+
+## `fetch(path, options?)` {#fetch-path-options}
+
+Type-safe fetch client for calling your API routes from client code, built on top of [ofetch](https://github.com/unjs/ofetch). Route paths and return types are inferred from the generated `RouteMap`.
+
+```ts
+import { fetch } from 'void/client';
+
+// Types are fully inferred from your route handlers
+const users = await fetch('/api/users');
+const user = await fetch('/api/users/:id', {
+  params: { id: '1' },
+});
+```
+
+**Signature:**
+
+```ts
+function fetch<P extends keyof RouteMap, M extends MethodsOf<P>>(
+  path: P,
+  options?: FetchOptions<P, M>,
+): Promise<OutputOf<P, M>>;
+```
+
+**Options:**
+
+| Option    | Type                     | Description                                                |
+| --------- | ------------------------ | ---------------------------------------------------------- |
+| `method`  | `string`                 | HTTP method. Defaults to `"GET"`.                          |
+| `body`    | `unknown`                | 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 (ofetch default: 1 for GET).      |
+| `timeout` | `number`                 | Request timeout in milliseconds.                           |
+
+Returns the parsed JSON response body, or `undefined` for 204 responses. Throws `FetchError` on non-2xx responses.
+
+## `FetchError` {#fetcherror}
+
+Error class thrown by `fetch` on non-2xx responses.
+
+```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.response); // raw Response
+  }
+}
+```
+
+**Properties:**
+
+| Property   | Type       | Description                          |
+| ---------- | ---------- | ------------------------------------ |
+| `status`   | `number`   | HTTP status code.                    |
+| `response` | `Response` | The raw `Response` object.           |
+| `data`     | `unknown`  | Parsed response body (if available). |
+
+## Differences from Native `fetch` {#differences-from-native-fetch}
+
+The typed client is built on [ofetch](https://github.com/unjs/ofetch) with a typed route layer on top. Key differences from native `fetch`:
+
+| Behavior               | Native `fetch`                                       | `void/client` `fetch`                                                                                                  |
+| ---------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **Return type**        | `Promise<Response>`, so you call `.json()` yourself  | `Promise<T>`, which auto-parses JSON and returns the typed result directly (`undefined` for `204`)                     |
+| **Error handling**     | Resolves on any HTTP status; you check `response.ok` | Throws `FetchError` on non-2xx responses                                                                               |
+| **URL construction**   | Raw URL string                                       | Route path with `:param` interpolation from `options.params` + query string from `options.query`                       |
+| **Body serialization** | Manual `JSON.stringify()` + `Content-Type` header    | Auto-serializes `options.body` as JSON and sets `Content-Type: application/json`                                       |
+| **Type safety**        | Accepts any URL or method                            | Constrains paths to `RouteMap` keys and methods to those defined per route. Invalid combinations fail at compile time. |
+| **Retry**              | None                                                 | Auto-retries on 408, 429, and 5xx (configurable via `retry` option)                                                    |
+| **Timeout**            | None                                                 | Configurable via `timeout` option                                                                                      |
+
+`headers` and `signal` are passed through to the underlying fetch unchanged.

package/skills/void/docs/reference/api/database.md

@@ -0,0 +1,95 @@
+---
+outline: deep
+---
+
+# Database and Seeding {#database}
+
+Imported from `"void/db"`. The `db` export is a [Drizzle ORM](https://orm.drizzle.team) instance for the configured database dialect: [Cloudflare D1](https://developers.cloudflare.com/d1/) by default, PostgreSQL with `"database": "pg"`, or MySQL with `"database": "mysql"`.
+
+## `db` {#db}
+
+Default Drizzle instance, pre-wired with your schema from `db/schema.ts`.
+
+```ts
+import { db } from 'void/db';
+import { users } from '@schema';
+
+const allUsers = await db.select().from(users).all();
+```
+
+`db` uses your configured dialect and schema.
+
+- D1 projects resolve the `DB` binding and expose `DrizzleD1Database<Schema>`.
+- PostgreSQL projects use `DATABASE_URL` during local development and Hyperdrive's `connectionString` in production, exposing `NodePgDatabase<Schema>`.
+- MySQL projects use the same connection sources and expose `MySql2Database<Schema>`.
+
+## `createDb(database)` {#createdb-database}
+
+Creates a Drizzle instance for the active dialect.
+
+For D1 projects, pass a specific D1 binding. Use this when you have multiple D1 databases or need a non-default binding.
+
+```ts
+import { createDb } from 'void/db';
+import { env } from 'cloudflare:workers';
+
+const db = createDb(env.MY_OTHER_DB);
+```
+
+For PostgreSQL and MySQL projects, pass a connection string.
+
+```ts
+import { createDb } from 'void/db';
+
+const db = createDb('postgres://user:password@host:5432/app');
+```
+
+**Signature:**
+
+```ts
+// D1
+function createDb(d1: D1Database): DrizzleD1Database<Schema>;
+
+// PostgreSQL
+function createDb(connectionString: string): NodePgDatabase<Schema>;
+
+// MySQL
+function createDb(connectionString: string): MySql2Database<Schema>;
+```
+
+## Query Operators {#query-operators}
+
+`void/db` re-exports commonly used [Drizzle operators](https://orm.drizzle.team/docs/operators) so you never need to depend on `drizzle-orm` directly:
+
+```ts
+import { db, eq, and, or, desc, like, inArray, sql } from 'void/db';
+```
+
+**Full list:** `sql`, `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `and`, `or`, `not`, `desc`, `asc`, `like`, `ilike`, `notLike`, `inArray`, `notInArray`, `isNull`, `isNotNull`, `between`, `notBetween`, `exists`, `notExists`, `count`, `sum`, `avg`, `min`, `max`.
+
+## Seeding {#seeding}
+
+Imported from `"void/seed"`.
+
+### `defineSeed(fn)` {#defineseed-fn}
+
+Identity helper for programmatic seed modules used by `void db seed`.
+
+```ts
+import { defineSeed } from 'void/seed';
+
+export default defineSeed<typeof import('./schema')>(async ({ db, schema }) => {
+  await db.insert(schema.users).values([
+    { name: 'Alice', email: 'alice@example.com' },
+    { name: 'Bob', email: 'bob@example.com' },
+  ]);
+});
+```
+
+The callback receives:
+
+- `dialect`: `"sqlite"`, `"postgresql"`, or `"mysql"`
+- `db`: a local Drizzle instance for the active dialect
+- `schema`: the exports from `db/schema.ts` or `db/schema/`
+
+Seed modules can export either `default` or a named `seed` function.

package/skills/void/docs/reference/api/durable.md

@@ -0,0 +1,46 @@
+---
+outline: deep
+---
+
+# Durable State and WebSockets {#durable-state}
+
+Imported from `"void/durable"`. See [Durable State](../../guide/durable-state.md) for the complete file convention and deployment support.
+
+## `defineDurableState(definition)` {#definedurablestate-definition}
+
+Defines a typed, persisted Durable Object state machine. The returned object must be the default export of a module under `durable-objects/`; named-export the same object for typed RPC calls elsewhere in the app.
+
+```ts
+function defineDurableState<TState, TEnv, TMethods>(definition: {
+  name?: string;
+  initialState: TState | ((env: TEnv) => TState | Promise<TState>);
+  version?: number;
+  migrations?: Array<{
+    version: number;
+    migrate(state: unknown): TState | Promise<TState>;
+  }>;
+  methods: TMethods;
+  fetch?: (context, request: Request) => Response | Promise<Response>;
+  alarm?: (context) => void | Promise<void>;
+  storageKey?: string;
+}): DurableStateApi<TMethods>;
+```
+
+`DurableStateApi` exposes `class`, `get(name)`, `get(namespace, name)`, `getById(id)`, and `getById(namespace, id)`. Stubs returned by the lookup helpers contain the definition's methods with their argument types preserved and return values wrapped in `Promise`.
+
+`name` optionally fixes the persistent resource identity instead of deriving it from the filename. Run `void info` and pin the displayed name before renaming a deployed definition. Keep instance names passed to `get()` unchanged. See the [migration flow](../../guide/durable-state.md#rename-a-file-while-keeping-its-state).
+
+## WebSockets {#websockets}
+
+Imported from `"void/ws"`. `defineRoom()` adds shared-room helpers to hook contexts; `defineWebSocket()` supplies a connection's socket helpers. Both require `messages.client` and `messages.server` Standard Schema validators and support the hooks described in the [WebSocket guide](../../guide/websockets.md).
+
+Both helpers accept these optional resource settings:
+
+```ts
+name?: string;
+key?: (context: { params: Record<string, string> }) => string;
+```
+
+`name` fixes the Worker class and binding identity. Without it, Void derives the identity from the route file. Run `void info` before moving a deployed route and pin its displayed name.
+
+`key` selects the route instance and its `ctx.id`. Without it, routes use parameter names and values in route order (`room=general`, or `default` without parameters). A callback must return a stable string synchronously. When renaming parameters, preserve the complete old key to retain state. See [moving routes](../../guide/websockets.md#move-a-route-while-keeping-its-state) and [renaming parameters](../../guide/websockets.md#rename-a-route-parameter).

package/skills/void/docs/reference/api/env.md

@@ -0,0 +1,50 @@
+---
+outline: deep
+---
+
+# Environment Variables {#environment}
+
+Imported from `"void/env"`.
+
+## `defineEnv(schema)` {#defineenv-schema}
+
+Register an env schema and return the typed [`env`](#env) proxy. Void auto-discovers `env.ts`, imports it during dev/build/deploy, generates `.void/env.d.ts`, validates production secrets before deploy, and validates values at worker boot.
+
+```ts
+import { defineEnv, string, number, oneOf, url } from 'void/env';
+
+export default defineEnv({
+  STRIPE_KEY: string(),
+  PORT: number().default(3000),
+  NODE_ENV: oneOf(['development', 'production']),
+  VITE_PUBLIC_URL: url(),
+});
+```
+
+## `env` {#env}
+
+Typed runtime proxy for declared env keys. Unknown keys and bindings pass through as `unknown`.
+
+```ts
+import { env } from 'void/env';
+
+const port = env.PORT;
+```
+
+## Schema helpers {#schema-helpers}
+
+`void/env` includes Standard Schema-compatible helpers: `string()`, `number()`, `boolean()`, `url()`, `email()`, `oneOf([...])`, and `json<T>()`. Each helper supports `.optional()` and `.default(value)`.
+
+Non-client keys are server values and use remote secret storage in production. `VITE_*` keys are public build-time client values. Invalid input is redacted uniformly; storage is not selected with schema modifiers.
+
+## Types {#types-1}
+
+`void/env` also provides global Cloudflare environment types:
+
+```ts
+/// <reference types="void/env" />
+```
+
+Declares the `Cloudflare.Env` namespace with `DB`, `KV`, `STORAGE`, `AI`, and `SANDBOX` binding types.
+
+For handler context variables such as `c.set()` and `c.get()`, augment [`CloudContextVariables`](./types.md#cloudcontextvariables). This is separate from `Cloudflare.Env`, which types worker bindings. Framework adapters such as `@void/vue`, `@void/react`, and `@void/svelte` also augment `CloudContextVariables` to add the `shared` key used by `useShared()`.