void 0.1.6 → 0.7.1

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

@@ -0,0 +1,233 @@
+---
+outline: deep
+---
+
+# Quickstart
+
+## Start in an Empty Directory
+
+Install the Void CLI from npm:
+
+`npm`
+
+```sh
+npm install -D void
+```
+
+`pnpm`
+
+```sh
+pnpm add -D void
+```
+
+`yarn`
+
+```sh
+yarn add -D void
+```
+
+`bun`
+
+```sh
+bun add -D void
+```
+
+In an empty directory, `void init` adds the matching Pages adapter and starter dependencies after you choose a framework.
+
+As part of `void init`, you'll choose a Pages framework (React, Vue, Svelte, or Solid) and a starter type. D1 is the default top option and scaffolds a DB-backed page loader, schema, generated migration, `db/seed.ts`, and API route. PostgreSQL scaffolds the same starter and writes `"database": "pg"` to `void.json`. Static Pages skips the database and server starter files so you can start with static content and add Void features later.
+
+After installation, run the setup flow:
+
+::: code-group
+
+```sh [npm]
+npx void init
+```
+
+```sh [pnpm]
+pnpm void init
+```
+
+```sh [yarn]
+yarn void init
+```
+
+```sh [bun]
+bunx void init
+```
+
+:::
+
+At the end of the full interactive flow, `void init` can also handle Void project setup by logging you in and linking or creating your Void project. That means the default first-time path is install packages, run `void init`, then `void deploy`.
+
+For the database-backed starters, D1 is the zero-config default for prototyping and read-heavy apps, while PostgreSQL is better when you already have Postgres infrastructure or need heavier writes and more complex queries.
+
+<details>
+<summary style="cursor:pointer">
+💡 <b>Notes on <code>void</code> binary usage</b>
+</summary>
+
+`void` is a local binary from the installed `void` package, so outside of npm scripts, you will have to invoke it with `npx`, `pnpm`, `yarn`, or `bunx`. For brevity, you will sometimes see unprefixed `void` usage throughout the docs. Just remember it needs to be invoked through a binary runner.
+
+Alternatively, you can add `./node_modules/.bin` to your `PATH` so that you can invoke `void` directly when you are in the root directory of your app.
+
+:::warning ⚠️ Prefer local install
+We do not recommend installing `void` globally, because the CLI needs to be in sync with same version of the runtime framework. Always install `void` locally as a dev dependency of your project.
+:::
+
+</details>
+
+## Using with Coding Agents
+
+`void init` detects your agent once and reuses that choice for instructions, skills linking, and MCP config.
+
+If auto-detection fails, `void init` asks you to choose from a short list (Claude, Cursor, Codex, Gemini CLI, Generic).
+
+In supported agents such as Claude Code, you can invoke the `/void` skill to turn your agent into a Void export. Then, simply ask the agent to build an app with Void. See the [Coding Agents](../integrations/agents) guide for more details.
+
+## Meta Frameworks
+
+Void as a platform supports Vite-based meta frameworks, but the Void SDK itself is also a powerful and flexible meta framework via its [Pages routing](./pages-routing/overview) feature. If you only want to use an existing meta framework and deploy to Void, check out the [Framework Integration Guides](../integrations/frameworks/overview).
+
+## Adding to an Existing Vite App
+
+::: code-group
+
+```sh [npm]
+npm install -D void
+```
+
+```sh [pnpm]
+pnpm add -D void
+```
+
+```sh [yarn]
+yarn add -D void
+```
+
+```sh [bun]
+bun add -D void
+```
+
+:::
+
+Enable the plugin in `vite.config.ts`
+
+```ts
+import { defineConfig } from 'vite';
+import { voidPlugin } from 'void';
+
+export default defineConfig({
+  plugins: [voidPlugin()],
+});
+```
+
+Then run the setup guide via `void` (Void CLI):
+
+::: code-group
+
+```sh [npm]
+npx void init
+```
+
+```sh [pnpm]
+pnpm void init
+```
+
+```sh [yarn]
+yarn void init
+```
+
+```sh [bun]
+bunx void init
+```
+
+:::
+
+## Once You Have a Working App
+
+### 1. Edit the generated API route
+
+Your starter already includes `routes/api/hello.ts` with a named `GET` export:
+
+```ts
+import { defineHandler } from 'void';
+
+export const GET = defineHandler(() => {
+  return { message: 'Hello from Void' };
+});
+```
+
+### 2. Run locally
+
+```sh
+npm run dev
+```
+
+Then visit:
+
+- App: `http://localhost:5173`
+- API route: `http://localhost:5173/api/hello`
+
+### 3. Finish Void project setup if you skipped it during `void init`
+
+```sh
+void auth login
+```
+
+If you already logged in and linked a project during `void init`, you can skip this step.
+
+### 4. Deploy
+
+Set secrets once before deploying, if any:
+
+```sh
+void secret put KEY=value
+```
+
+Then run:
+
+```sh
+void deploy
+```
+
+```sh
+┌  void deploy
+│
+◇  Building...
+│  (vite build output)
+│
+ℹ  Found N migration(s)
+│
+◇  Checking assets...
+◇  Uploading X/Y assets (Z cached)
+◇  Packaging...
+◇  Deploying...
+◇  Deployed!
+│
+│  ╭─────────────────────────────────────────╮
+│  │  https://my-app.void.app           │
+│  │                                         │
+│  │  2 worker module(s), 5 static asset(s)  │
+│  │  1 migration(s) applied                 │
+│  │  SSR enabled                            │
+│  ╰─────────────────────────────────────────╯
+│
+└  Done!
+```
+
+On first deploy, Void will:
+
+- build your app
+- create or link a project if you did not already do that during `void init`
+- provision required resources (for example D1/KV/R2 when inferred)
+- deploy to `https://<slug>.void.app`
+
+Right now, only deploys via the CLI is supported. To setup push-to-deploy GitHub, run `void init --github`.
+
+## Next steps
+
+- To understand what kind of apps are supported: [Supported App Types](./app-types)
+- [Server Routing](./server-routing): dynamic params, middleware, and validation
+- [Database](./database): queries, migrations, and generated types
+- [Type Safety](./type-safety): end-to-end typed fetch client

package/skills/void/docs/guide/remote-dev.md

@@ -0,0 +1,67 @@
+---
+outline: deep
+---
+
+# Remote Development
+
+During local development, Void uses local emulations of D1, KV, and R2 through [Miniflare](https://miniflare.dev/). That covers most work, but sometimes you need real data for debugging a production issue, testing against a populated database, or validating R2 uploads end to end.
+
+Remote development mode connects your local dev server to the **real bindings** from your deployed project. Your code does not change. `db.select()`, `env.KV.get()`, and `env.STORAGE.get()` work the same way, but they hit remote resources instead of local emulations.
+
+## Prerequisites
+
+Before enabling remote mode, you need:
+
+1. **Logged in:** run `void auth login` if you have not already
+2. **Project linked:** run `void deploy` at least once to create and link a project
+
+## Enabling Remote Mode
+
+### In `void.json` (persistent)
+
+```json
+{
+  "remote": true
+}
+```
+
+### Via environment variable (one-off)
+
+```bash
+VOID_REMOTE=1 vite dev
+```
+
+`VOID_REMOTE=0` disables remote mode even if `void.json` has `"remote": true`.
+
+## Supported Bindings
+
+| Binding | Local (default)            | Remote              |
+| ------- | -------------------------- | ------------------- |
+| D1      | Local SQLite via Miniflare | Remote D1 database  |
+| KV      | Local file-backed KV       | Remote KV namespace |
+| R2      | Local file-backed R2       | Remote R2 bucket    |
+| AI      | Always proxied             | Always proxied      |
+
+AI inference is always routed through the proxy regardless of remote mode. There is no local AI emulation.
+
+## How It Works
+
+When remote mode is active, the dev server replaces local Miniflare bindings with proxy-backed versions at runtime. Every binding call is forwarded to your deployed resources via Void's proxy service, authenticated with your login token. The proxy resolves which D1 database, KV namespace, or R2 bucket to use based on your project's binding configuration.
+
+You don't need to change any code. Imports like `import { db } from "void/db"` and direct binding access via `c.env.KV` both work transparently.
+
+When the dev server starts with remote mode active, it prints:
+
+```
+⚡ Remote bindings active (my-project.void.app)
+   DB      → remote D1
+   KV      → remote KV
+   STORAGE → remote R2
+```
+
+## Limitations
+
+- **Network latency:** every binding call goes over the network, so local dev is slower than local emulation. This is expected.
+- **R2 multipart uploads:** `createMultipartUpload()` and `resumeMultipartUpload()` are not supported in remote mode.
+- **D1 dump:** `db.dump()` is not supported in remote mode.
+- **Writes affect real data:** remote mode connects to your actual deployed resources. Inserts, updates, and deletes are real, so use it carefully or point it at a staging project.

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

@@ -0,0 +1,82 @@
+---
+outline: deep
+---
+
+# Sandboxes
+
+Void can wire Cloudflare Sandboxes into Void apps. A sandbox gives each session an isolated container for running commands, working with files, and exposing ports from server-side code.
+
+```ts
+import { defineHandler } from 'void';
+import { getSandbox } from 'void/sandbox';
+
+export const POST = defineHandler(async (c) => {
+  const { command } = await c.req.json<{ command: string }>();
+  const sandbox = getSandbox('default');
+  const result = await sandbox.exec(command);
+
+  return c.json(result);
+});
+```
+
+Importing from `void/sandbox` enables the `SANDBOX` Durable Object binding, exports the SDK's `Sandbox` class from the generated Worker entry, and adds the matching `containers` and migration metadata to the Cloudflare worker config.
+
+## Configuration
+
+Most apps do not need config. The default binding is `SANDBOX`, the Durable Object class is `Sandbox`, local development uses the Dockerfile bundled with `@cloudflare/sandbox`, and `void deploy` uses the matching published sandbox image.
+
+Use `void.json` when you need a custom image or container size:
+
+```json
+{
+  "sandbox": {
+    "image": "./Dockerfile.sandbox",
+    "platformImage": "registry.example.com/acme/sandbox:latest",
+    "instanceType": "lite",
+    "maxInstances": 2
+  }
+}
+```
+
+Available fields:
+
+| Field               | Default                        | Description                                              |
+| ------------------- | ------------------------------ | -------------------------------------------------------- |
+| `binding`           | `SANDBOX`                      | Worker binding name                                      |
+| `className`         | `Sandbox`                      | Durable Object class exported by the Worker              |
+| `containerName`     | `void-sandbox`                 | Cloudflare container app name                            |
+| `image`             | Bundled sandbox SDK Dockerfile | Dockerfile path or registry image used by Wrangler/local |
+| `imageBuildContext` | Directory of `image`           | Docker build context for Wrangler/local                  |
+| `platformImage`     | Matching sandbox SDK image     | Registry image used by `void deploy`                     |
+| `instanceType`      | `lite` on Void deploy          | Container size, such as `lite`, `basic`, `standard-1`    |
+| `maxInstances`      | `20` on Void deploy            | Maximum number of container instances                    |
+
+## Runtime API
+
+`getSandbox(id, options)` returns the SDK sandbox stub for a session id. IDs are normalized by default so user-provided session ids can safely map to Durable Object names.
+
+```ts
+import { getSandbox } from 'void/sandbox';
+
+const sandbox = getSandbox(`user-${user.id}`);
+await sandbox.writeFile('/tmp/input.txt', 'hello');
+const result = await sandbox.exec('cat /tmp/input.txt');
+```
+
+You can also use the namespace directly from `c.env.SANDBOX` when you need lower-level Durable Object control.
+
+## State persistence
+
+There are two distinct layers to think about: stable Durable Object identity, and ephemeral container state.
+
+`getSandbox(id)` always resolves to the same Durable Object instance for a given `id`, regardless of how many times the project has been deployed or rolled back. Anything written through the DO's persistent storage (`ctx.storage`, the embedded SQLite database) survives deploys, rollbacks, and container restarts. That layer is the durable home for sandbox metadata, session ids, and any data you need to outlive the container.
+
+The container itself — filesystem, running processes, exposed ports, in-memory shell sessions — is tied to a single container lifetime and is **not** durable. Cloudflare Containers idle out after inactivity (the SDK default is `sleepAfter: "10m"`), and a container can also restart on a process crash or a platform-side reschedule. When that happens, files in the container filesystem, background processes, and previously exposed ports are lost. Setting `keepAlive: true` disables the idle timer but does not protect against crashes or infrastructure restarts.
+
+Treat the sandbox container as a working environment, not a source of truth. Persist anything you cannot afford to lose to DO storage, your database, KV, or R2 (the SDK also offers backup/restore helpers for snapshotting a directory to R2). Project deletion destroys both layers, but plenty of routine events destroy only the container layer.
+
+## Deployment
+
+`void deploy` provisions the `SANDBOX` Durable Object namespace, attaches the Cloudflare Container metadata to the Worker upload, and creates or updates the matching container application in the Void platform account.
+
+Platform deploys require a registry image reference. The default sandbox works without extra config. If `sandbox.image` points at a custom local Dockerfile, also set `sandbox.platformImage` to an image you have already pushed to a registry.

package/skills/void/docs/guide/server-routing.md

@@ -0,0 +1,246 @@
+---
+outline: deep
+---
+
+# Server Routing
+
+Full-stack Void apps uses file-based routing powered by [Hono](https://hono.dev). Drop files in `routes/` and they become endpoints. Add global middleware in `middleware/`.
+
+## Route Files
+
+Create route handlers in `routes/**/*.ts`. Each file maps to a URL path based on its location in the filesystem:
+
+<RoutesFileTree />
+
+Dynamic segments use brackets: `[id]` becomes a route parameter and `[...slug]` becomes a catch-all. Files or directories starting with `_` are ignored. Directories wrapped in parentheses like `(admin)` are route groups. They help organize files without changing the URL.
+
+You can add a `.dev` or `.prod` suffix before the extension (e.g. `debug.dev.ts`) to include a route only in that environment.
+
+Each file exports named HTTP method constants to handle specific methods:
+
+```ts
+// routes/api/hello.ts  →  GET /api/hello
+import { defineHandler } from 'void';
+
+export const GET = defineHandler((c) => {
+  return { message: 'Hello!', timestamp: Date.now() };
+});
+```
+
+A file can export multiple methods:
+
+```ts
+// routes/api/users/index.ts  →  GET + POST /api/users
+import { defineHandler } from 'void';
+import { db } from 'void/db';
+import { users } from '@schema';
+
+export const GET = defineHandler(async () => {
+  return await db.select().from(users);
+});
+
+export const POST = defineHandler(async (c) => {
+  const body = await c.req.json();
+  await db.insert(users).values({ name: body.name });
+  return { created: true };
+});
+```
+
+The `db` helper provides a typed query API over D1. See [Database](./database.md) for the full API.
+
+## `defineHandler`
+
+`defineHandler` wraps a route handler function:
+
+```ts
+import { defineHandler } from 'void';
+
+export const GET = defineHandler((c) => {
+  return { data: 'hello' };
+});
+```
+
+The handler receives a Hono `Context` with typed Cloudflare bindings on `c.env` (see [Cloudflare](../integrations/cloudflare.md)). You can use the full Hono API (`c.json()`, `c.text()`, `c.header()`, etc.).
+
+Return values are automatically converted:
+
+- **object/array/number/boolean** → JSON response
+- **`string`** → `text/html; charset=utf-8`
+- **`null`/`undefined`** → `204 No Content`
+- **`Response`** → returned as-is
+
+## Validation
+
+`defineHandler.withValidator()` adds input validation for `body`, `query`, and `params`. The recommended approach is to derive validators from your [Drizzle schema](./database.md#schema-derived-validators), which keeps validation in sync with the database.
+
+```ts
+// routes/api/users/index.ts
+import { defineHandler } from 'void';
+import { db } from 'void/db';
+import { users, insertUserSchema } from '@schema';
+
+export const POST = defineHandler.withValidator({
+  body: insertUserSchema,
+})(async (c, { body }) => {
+  const [created] = await db.insert(users).values(body).returning();
+  return created;
+});
+```
+
+See [Database: Schema-Derived Validators](./database.md#schema-derived-validators) for how to set up `createInsertSchema` with column refinements.
+
+You can validate multiple slots at once:
+
+```ts
+// routes/api/users/[id].ts
+import { defineHandler } from 'void';
+import { db, eq } from 'void/db';
+import { users, updateUserSchema } from '@schema';
+
+export const PUT = defineHandler.withValidator({
+  body: updateUserSchema,
+})(async (c, { body }) => {
+  const id = Number(c.req.param('id'));
+  const [updated] = await db.update(users).set(body).where(eq(users.id, id)).returning();
+  return updated;
+});
+```
+
+### Manual validators
+
+For endpoints that don't map to a database table, you can write validators by hand using any [Standard Schema](https://standardschema.dev/)-compatible library (Valibot, Zod, ArkType, etc.):
+
+```ts
+import * as v from 'valibot';
+import { defineHandler } from 'void';
+
+export const POST = defineHandler.withValidator({
+  body: v.object({
+    query: v.pipe(v.string(), v.minLength(1)),
+    limit: v.optional(v.pipe(v.number(), v.maxValue(100)), 10),
+  }),
+})(async (c, { body }) => {
+  // body is typed as { query: string; limit: number }
+  return search(body.query, body.limit);
+});
+```
+
+### Validation errors
+
+When validation fails, a `400` response is returned with structured error details:
+
+```json
+{
+  "error": "Validation failed",
+  "issues": [
+    {
+      "slot": "body",
+      "issues": [{ "message": "Invalid email", "path": "email" }]
+    }
+  ]
+}
+```
+
+No extra dependencies are required. Void inlines the Standard Schema types, so you only need your chosen schema library.
+
+Validator schemas also power the [typed fetch client](./typed-fetch.md), so `body`, `query`, and `params` types are enforced at the call site.
+
+## Middleware
+
+Void middlewares are just Hono middlewares. `defineMiddleware()` is a thin typing helper around the standard Hono `(c, next)` shape, and `defineHandler()` also accepts raw Hono middleware directly.
+
+```ts
+import { defineMiddleware } from 'void';
+
+export const addServerTiming = defineMiddleware(async (c, next) => {
+  const start = performance.now();
+  await next();
+  c.header('Server-Timing', `app;dur=${Math.round(performance.now() - start)}`);
+});
+```
+
+Any `hono/*` built-in middleware, response helpers, or third-party Hono ecosystem packages can be used in Void apps. If you want to import from `hono/*` in your app, make sure to install `hono` in your app first:
+
+```bash
+npm install hono
+```
+
+```ts
+import { cors } from 'hono/cors';
+
+const allowDashboard = cors({ origin: 'https://app.example.com' });
+```
+
+You can apply middleware globally or per-route.
+
+### Global middleware
+
+Global middleware runs on every request. Place files in `middleware/` and use numeric prefixes for ordering:
+
+- `middleware/01.logger.ts`
+- `middleware/02.auth.ts`
+
+```ts
+import { defineMiddleware } from 'void';
+
+export default defineMiddleware(async (c, next) => {
+  console.log(c.req.method, c.req.path);
+  await next();
+});
+```
+
+`defineMiddleware` uses Hono middleware semantics: `(c, next) => Promise<void> | void`.
+
+Middleware can set typed context variables using `c.set()`. Augment the `CloudContextVariables` interface so downstream handlers get full type safety:
+
+```ts
+// middleware/01.request-id.ts
+import { defineMiddleware } from 'void';
+
+declare module 'void' {
+  interface CloudContextVariables {
+    requestId: string;
+  }
+}
+
+export default defineMiddleware(async (c, next) => {
+  c.set('requestId', crypto.randomUUID());
+  await next();
+});
+```
+
+Now every route handler can call `c.get("requestId")` and get `string` back, with no type assertion needed. See [Type Safety](./type-safety.md#context-variables) for more details.
+
+### Per-route middleware
+
+Pass one or more middleware to `defineHandler` before the final handler:
+
+```ts
+defineHandler(middleware1, middleware2, handler);
+```
+
+Middleware runs in order. Each can short-circuit (return a response without calling `next()`) or post-process (modify the response after `await next()`). Both `defineMiddleware`-wrapped functions and raw Hono `MiddlewareHandler` functions are accepted.
+
+```ts
+// routes/api/stats.ts
+import { defineHandler } from 'void';
+import { cors } from 'hono/cors';
+
+const addServerTiming = async (c, next) => {
+  const start = performance.now();
+  await next();
+  c.header('Server-Timing', `app;dur=${Math.round(performance.now() - start)}`);
+};
+
+export const GET = defineHandler(
+  cors({ origin: 'https://app.example.com' }),
+  addServerTiming,
+  (c) => {
+    return { stats: '...' };
+  },
+);
+```
+
+Up to 5 middleware can be passed before the handler, with full type inference for each position.
+
+See the [Hono integration guide](../integrations/hono.md) for more examples.