void 0.1.6 → 0.7.0

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

@@ -0,0 +1,190 @@
+---
+outline: deep
+---
+
+# WebSockets
+
+::: warning ⚠️ Void Apps Only
+Void-managed WebSockets currently works only for Void apps. Meta-framework mode is not supported yet.
+:::
+
+Void supports typed WebSockets from file-based `.ws.ts` routes. Each WebSocket route compiles to a Cloudflare Durable Object, so the feature is currently Cloudflare-only. If you set `target` to `node`, `bun`, or `deno`, builds fail when `.ws.ts` routes are present.
+
+Use WebSockets for chat, presence, collaborative rooms, notifications, AI/live-log streaming, and other realtime flows where one connection target maps cleanly to one route instance.
+
+## Route files
+
+Create WebSocket routes in `routes/` with the `.ws.ts` suffix:
+
+```text
+routes/
+  chat/[room].ws.ts
+  notifications.ws.ts
+```
+
+Filename rules match regular server routes:
+
+- `index.ws.ts` becomes the parent path
+- `[id].ws.ts` becomes `:id`
+- `[...slug].ws.ts` becomes a catch-all
+- route groups like `(marketing)/chat.ws.ts` are ignored in the URL
+
+## `defineRoom()`
+
+Use `defineRoom()` when many clients should share one route-scoped room or document.
+
+```ts
+// routes/chat/[room].ws.ts
+import * as v from 'valibot';
+import { defineRoom } from 'void/ws';
+
+const ClientMessage = v.variant('type', [
+  v.object({ type: v.literal('chat.message'), text: v.string() }),
+]);
+
+const ServerMessage = v.variant('type', [
+  v.object({
+    type: v.literal('chat.message'),
+    id: v.string(),
+    text: v.string(),
+    userId: v.string(),
+  }),
+  v.object({ type: v.literal('chat.joined'), userId: v.string() }),
+]);
+
+export default defineRoom({
+  messages: {
+    client: ClientMessage,
+    server: ServerMessage,
+  },
+  onBeforeConnect(ctx) {
+    if (!ctx.user) {
+      return new Response('Unauthorized', { status: 401 });
+    }
+  },
+  async onConnect(ctx) {
+    await ctx.room.broadcast({ type: 'chat.joined', userId: ctx.user!.id }, [ctx.connection.id]);
+  },
+  async onMessage(ctx, event) {
+    await ctx.room.broadcast({
+      type: 'chat.message',
+      id: crypto.randomUUID(),
+      text: event.text,
+      userId: ctx.user!.id,
+    });
+  },
+});
+```
+
+`defineRoom()` adds room helpers to the hook context:
+
+- `ctx.room.broadcast(event, excludeIds?)`
+- `ctx.room.getConnections()`
+- `ctx.room.getConnection(id)`
+- `ctx.connection.send(event)`
+- `ctx.connection.close(code?, reason?)`
+- `ctx.connection.setState(data)`
+
+## `defineWebSocket()`
+
+Use `defineWebSocket()` when each connection is handled independently instead of as a shared room.
+
+```ts
+// routes/notifications.ws.ts
+import * as v from 'valibot';
+import { defineWebSocket } from 'void/ws';
+
+export default defineWebSocket({
+  messages: {
+    client: v.object({ type: v.literal('notifications.ack'), id: v.string() }),
+    server: v.object({ type: v.literal('notifications.item'), title: v.string() }),
+  },
+  onBeforeConnect(ctx) {
+    if (!ctx.user) {
+      return new Response('Unauthorized', { status: 401 });
+    }
+  },
+  async onConnect(ctx) {
+    await ctx.socket.send({ type: 'notifications.item', title: 'Connected' });
+  },
+});
+```
+
+## Typed messages
+
+WebSocket messages are schema-backed in both directions:
+
+- `messages.client` validates what the browser may send
+- `messages.server` validates what the server may send
+- `onMessage()` receives the parsed, validated client event
+- `ctx.room.broadcast()`, `ctx.connection.send()`, and `ctx.socket.send()` are typed from `messages.server`
+- `connect()` infers route params, outgoing client messages, and incoming server messages from generated route types
+
+The default protocol is JSON events. Raw string or binary framing is not the primary API.
+
+## Ambient auth
+
+WebSocket hooks use the same built-in session resolution as HTTP auth. When Void auth is enabled, `ctx.user` is available in:
+
+- `onBeforeConnect`
+- `onConnect`
+- `onMessage`
+- `onClose`
+- `onRequest`
+
+This makes cookie-authenticated sockets work without re-parsing the session manually.
+
+## Hooks
+
+Both `defineRoom()` and `defineWebSocket()` support:
+
+- `onBeforeConnect(ctx)`: return a `Response` to reject the upgrade
+- `onConnect(ctx)`: runs after the socket is accepted
+- `onMessage(ctx, event)`: receives the validated client event
+- `onClose(ctx, details)`: receives `{ code, reason, wasClean }`
+- `onRequest(ctx)`: handles ordinary HTTP requests to the same path
+
+Every hook receives a context with:
+
+- `ctx.id`: deterministic route instance id
+- `ctx.params`: matched route params
+- `ctx.user`: resolved auth user or `null`
+- `ctx.request`
+- `ctx.env`
+- `ctx.storage`
+
+If a route does not define `onRequest()`, non-WebSocket requests return `426 Upgrade Required`.
+
+## Client
+
+Use `connect()` from `void/ws` on the client:
+
+```ts
+import { connect } from 'void/ws';
+
+const socket = connect('/chat/:room', {
+  params: { room: 'general' },
+});
+
+socket.on('message', (event) => {
+  if (event.type === 'chat.message') {
+    console.log(event.text);
+  }
+});
+
+socket.send({ type: 'chat.message', text: 'hello' });
+```
+
+`connect()` resolves relative URLs against the current origin and automatically uses `ws:` or `wss:`. It also buffers messages until the socket opens and reconnects by default.
+
+## Constraints
+
+This first release intentionally focuses on the Durable Object sweet spot:
+
+- Cloudflare-only
+- one route-derived connection target per socket
+- no Socket.IO-style dynamic room join/leave API
+- no global pub/sub abstraction
+- JSON event messages only
+
+That covers most realtime app shapes Void is targeting without exposing Durable Objects directly.

package/skills/void/docs/index.md

@@ -0,0 +1,48 @@
+---
+layout: home
+theme: dark
+
+hero:
+  name: Void.
+  text: Ship full-stack Vite apps at warp speed
+  tagline: Void is a deployment platform designed for Vite - with a powerful backend SDK that makes your Vite apps truly full-stack.
+  actions:
+    - theme: brand
+      text: Get Started
+      link: ./guide/
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/voidzero-dev/void
+  image:
+    src: /hero.svg
+    alt: Void deployment platform
+
+features:
+  - iconify: lucide:layers
+    title: Truly Full-Stack
+    details: Database, KV storage, object storage, AI inference, authentication, queues, and cron jobs are built in. Import what you need and ignore the rest.
+  - iconify: lucide:wand-sparkles
+    title: Your Code is Your Infra
+    details: Void scans your source code, detects what you use, and provisions resources automatically. No config files or dashboard clicks, either locally or in the cloud.
+  - iconify: lucide:shield-check
+    title: End-to-End Type Safety
+    details: Types flow from Drizzle schema through route handlers to page component props and the frontend fetch client. One schema validates at runtime and infers types at build time.
+  - iconify: lucide:blocks
+    title: Any Framework, Any Rendering
+    details: React, Vue, Svelte, Solid, plus Vite-based meta-frameworks. Use SSR, SSG, ISR, islands, and markdown where they fit.
+  - iconify: lucide:bot
+    title: AI-Native
+    details: Built-in skills, MCP support, and reference prompts let coding agents scaffold and ship full-stack apps in a single prompt.
+  - iconify: lucide:terminal
+    title: One Command to Production
+    details: '`void deploy` builds your app, runs migrations, provisions resources, and deploys to Cloudflare Workers, without requiring a Cloudflare account or knowledge about the infra.'
+
+footer_heading: Build and Deploy at Warp Speed
+footer_subheading: npm install void
+---
+
+<script setup>
+import Home from './.vitepress/theme/Home.vue'
+</script>
+
+<Home />

package/skills/void/docs/integrations/agents.md

@@ -0,0 +1,84 @@
+---
+outline: deep
+---
+
+# Using Void with Coding Agents
+
+Void integrates with coding agents via **skills** (agent instructions and reference docs) and an **MCP server** (tool-based documentation access). Both are set up as part of the default `void init` flow. To run only the agent setup step:
+
+```sh
+npx void init --agents
+```
+
+This detects your coding agent, links skills into its configuration directory, writes MCP config, and injects a Void reference block into your agent instructions file (`CLAUDE.md` or `AGENTS.md`). If auto-detection fails, it asks you to choose from Claude Code, Cursor, Codex, Gemini CLI, or Generic.
+
+## Skills
+
+Skills give your coding agent structured knowledge about Void, including how to use the CLI, build apps, work with routes, databases, auth, and more. They are symlinked from the `void` package into the agent's skills directory, so they stay version-matched with your installed Void version.
+
+Void ships two skills:
+
+- **`void`:** main development skill. Routes agent requests to the right documentation for CLI commands, routing, pages, database, auth, deployment, and more.
+- **`migrate-vite-cloudflare-to-void`:** migration skill for converting existing `@cloudflare/vite-plugin` apps to Void.
+
+Skills are linked automatically by `void init --agents`. For Claude Code, they are symlinked into `.claude/skills/`. Other agents that support skills will have them linked to their respective directories.
+
+## MCP
+
+Void ships with a built-in [MCP](https://modelcontextprotocol.io/) server that runs locally over stdio. It provides three tools: `list_pages`, `get_page`, and `search_docs`. Together they give your AI agent full access to the Void documentation, version-matched and usable offline.
+
+```sh
+npx void mcp
+```
+
+### Automatic Setup
+
+MCP config is written automatically by `void init --agents`:
+
+- Agents with project-level config support (Claude, Cursor, etc.): writes the config file for you.
+- Agents without project-level config support (Codex, Gemini CLI, etc.): prints the CLI command to register `npx void mcp`.
+- Generic mode: prints MCP JSON you can paste into your agent config.
+
+### Manual Setup
+
+#### Claude Code
+
+```sh
+claude mcp add void -- npx void mcp
+```
+
+#### Codex CLI
+
+```sh
+codex mcp add void -- npx void mcp
+```
+
+#### Cursor
+
+In `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "void": {
+      "command": "npx",
+      "args": ["void", "mcp"]
+    }
+  }
+}
+```
+
+#### Gemini CLI
+
+In `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "void": {
+      "command": "npx",
+      "args": ["void", "mcp"]
+    }
+  }
+}
+```

package/skills/void/docs/integrations/cloudflare.md

@@ -0,0 +1,284 @@
+---
+outline: deep
+---
+
+# Cloudflare
+
+Void runs on Cloudflare Workers. This page covers how bindings work, how the plugin merges your wrangler config, and how to deploy directly to your own Cloudflare account.
+
+## Bindings
+
+Void automatically infers and provisions Cloudflare bindings (D1, KV, R2, AI, Queues) by scanning your source files. There are two ways to access them at runtime depending on your setup.
+
+### Via Hono context (`c.env`)
+
+In Void's default routing mode, route handlers and middleware receive a Hono `Context` object with bindings on `c.env`:
+
+```ts
+// routes/api/users.ts
+import { defineHandler } from 'void';
+
+export const GET = defineHandler(async (c) => {
+  const { results } = await c.env.DB.prepare('SELECT * FROM users').all();
+  return c.json(results);
+});
+```
+
+```ts
+// routes/api/cache.ts
+import { defineHandler } from 'void';
+
+export const GET = defineHandler(async (c) => {
+  const value = await c.env.KV.get('key');
+  return c.json({ value });
+});
+```
+
+`c.env` is fully typed via `CloudContext` -- no manual type declarations needed.
+
+### Via `cloudflare:workers` import
+
+When using framework mode (TanStack Start, React Router, SolidStart), the framework owns routing and you access bindings through the `cloudflare:workers` module instead:
+
+::: warning ⚠️ Cloudflare env access in meta frameworks
+Some frameworks, like Nuxt and SvelteKit, do not run in workerd during dev and therefore do not support directly importing from `cloudflare:workers`.
+:::
+
+```ts
+import { env } from 'cloudflare:workers';
+
+const result = await env.DB.prepare('SELECT * FROM users').all();
+```
+
+This also works in server functions:
+
+```tsx
+// src/routes/users.tsx (TanStack Start)
+import { createFileRoute } from '@tanstack/react-router';
+import { createServerFn } from '@tanstack/react-start';
+import { env } from 'cloudflare:workers';
+
+const getUsers = createServerFn().handler(async () => {
+  const { results } = await env.DB.prepare('SELECT * FROM users').all();
+  return results;
+});
+
+export const Route = createFileRoute('/users')({
+  loader: () => getUsers(),
+  component: UsersPage,
+});
+```
+
+### TypeScript setup
+
+Add `"void/env"` to your tsconfig `types` to get typed bindings on `env`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["void/env"]
+  }
+}
+```
+
+This augments the `Cloudflare.Env` interface with `DB`, `KV`, `STORAGE`, `AI`, and `QUEUE_*` and also pulls in `@cloudflare/workers-types`, so you don't need to add that separately.
+
+### Available bindings
+
+| Binding   | Type          | Trigger                                                         |
+| --------- | ------------- | --------------------------------------------------------------- |
+| `DB`      | `D1Database`  | `env.DB` / `c.env.DB` or `import from "void/db"`                |
+| `KV`      | `KVNamespace` | `env.KV` / `c.env.KV` or `import from "void/kv"`                |
+| `STORAGE` | `R2Bucket`    | `env.STORAGE` / `c.env.STORAGE` or `import from "void/storage"` |
+| `AI`      | `Ai`          | `env.AI` / `c.env.AI` or `import from "void/ai"`                |
+| `QUEUE_*` | `Queue<T>`    | `defineQueue()` or `import from "void/queue"`                   |
+
+Bindings are [inferred automatically](../reference/resource-inference.md) by scanning your source files for import and access patterns. You can also set them explicitly in `void.json`:
+
+```json
+{
+  "inference": {
+    "bindings": { "db": true, "kv": true, "storage": false, "ai": true }
+  }
+}
+```
+
+`db`, `kv`, and `storage` accept a string to customize the binding name (e.g. `"db": "MY_DB"`). `ai` only accepts a boolean.
+
+See [Configuration](../reference/config.md) for details.
+
+### Wrangler passthrough
+
+You can set non-binding wrangler fields like `compatibility_date` and `compatibility_flags` in `void.json`:
+
+```json
+{
+  "worker": {
+    "compatibility_date": "2026-02-24",
+    "compatibility_flags": ["nodejs_compat"]
+  }
+}
+```
+
+For environment variables, use `.env` files instead of `worker.vars`. Void automatically loads `.env` files through Vite's `loadEnv` and merges them into the worker's `vars` bindings:
+
+```bash
+# .env
+API_URL=https://api.example.com
+```
+
+Binding arrays such as `d1_databases`, `kv_namespaces`, and `r2_buckets` are not allowed in the `worker` field because Void manages bindings for you. If you need custom bindings with real resource IDs, add a `wrangler.jsonc` to the project root instead. See [Wrangler config merging](#wrangler-config-merging) for details.
+
+## Wrangler config merging
+
+By default, Void configures the Cloudflare plugin programmatically, so you don't need a `wrangler.jsonc` for bindings. Void pins a Workers compatibility date in `void.json` `worker.compatibility_date`; if no date is already configured in `void.json` or `wrangler.jsonc`/`wrangler.json`, Void writes the latest known-good date to `void.json`. Bindings are inferred from your source code and provisioned with local placeholder IDs for development.
+
+If you add a `wrangler.jsonc` (or `wrangler.json`) to your project root, Void respects it -- but **how** depends on whether Void owns the Cloudflare integration or a meta-framework does.
+
+### Void-only mode and Vite-based frameworks
+
+In Void's default mode and when using frameworks where Void controls the Cloudflare integration (TanStack Start, React Router), Void manages the `@cloudflare/vite-plugin` directly. It passes a `config` callback that merges inferred bindings into whatever the plugin resolves from your `wrangler.jsonc`:
+
+1. The plugin reads your `wrangler.jsonc` and resolves it into a config object with `d1_databases`, `kv_namespaces`, `r2_buckets`, etc.
+2. Void checks each inferred binding **by name** (e.g. `"DB"`, `"KV"`, `"STORAGE"`). If a binding with that name already exists in your config, it is left untouched.
+3. Only bindings that are **missing** from your config are added with local placeholder IDs (e.g. `database_id: "local"`).
+4. The merged config is used for both `vite dev` (Miniflare) and `vite build` (output `wrangler.json` in `dist/`).
+
+All other fields in your `wrangler.jsonc` -- `name`, `routes`, `services`, `vars`, `env`, `compatibility_date`, etc. -- are preserved in the resolved config and flow through to the build output.
+
+Fields that Void always sets (`main`, `triggers`, `assets`) don't need to be in your wrangler config -- they're added programmatically based on your project structure.
+
+In this mode, Void does **not** modify your `wrangler.jsonc` file on disk. The merge is purely in-memory.
+
+### Adapter-based frameworks (SvelteKit, Nuxt, Astro)
+
+When using SvelteKit, Nuxt, or Astro, the framework's own Cloudflare adapter owns the worker build and dev server. Void does **not** provide `@cloudflare/vite-plugin` in that setup. It only contributes DB type codegen, migration management, and binding sync.
+
+Because Void doesn't control the CF plugin in this mode, it can't merge bindings via a config callback. Instead, on dev startup Void syncs inferred bindings directly to your `wrangler.jsonc` file on disk:
+
+- Only adds bindings that are **missing** by name -- existing bindings are never modified or removed.
+- If `worker.compatibility_date` is set in `void.json`, syncs that date into wrangler config so the framework adapter reads the same value.
+- Also ensures the `nodejs_als` compatibility flag is present.
+- The framework adapter then reads this `wrangler.jsonc` normally.
+
+This means your `wrangler.jsonc` is the single source of truth for bindings in this mode. Void keeps it up to date as you add new resource imports to your code, but you're responsible for replacing placeholder IDs with real ones before deploying.
+
+### Merge precedence
+
+| Source                     | Priority             | What it controls                                                    |
+| -------------------------- | -------------------- | ------------------------------------------------------------------- |
+| Your `wrangler.jsonc`      | Highest for bindings | Real resource IDs, service bindings, routes, vars, environments     |
+| `void.json` `worker` field | Highest for compat   | `compatibility_date`, `compatibility_flags`, `vars`                 |
+| Void inference             | Fills gaps only      | Adds placeholder bindings for inferred resources not in your config |
+
+If no date is found in `void.json`, project wrangler config, or the supported generated build wrangler fallback during deploy, Void pins the latest known-good date to `void.json` and uses it for that run.
+
+### Example
+
+If your code uses `c.env.DB` and `c.env.KV`, and your `wrangler.jsonc` only defines D1:
+
+```jsonc
+{
+  "name": "my-app",
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "my-app-db",
+      "database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    },
+  ],
+  // Service bindings, routes, etc. are also preserved
+  "services": [{ "binding": "API", "service": "my-api-worker" }],
+}
+```
+
+Void sees that `DB` is already configured and leaves it alone (including your real `database_id`), but adds a local placeholder for `KV` since it's missing. The `services` array passes through unchanged.
+
+This means `pnpm dev` works out of the box (Miniflare creates local instances of all bindings), while `wrangler deploy` uses your real D1 database ID and service bindings.
+
+### What ends up in the build output
+
+After `vite build`, the Cloudflare Vite plugin writes a merged `wrangler.json` to the `dist/` directory. This file contains:
+
+- All fields from your `wrangler.jsonc` (bindings with real IDs, routes, services, vars, environments)
+- Any inferred bindings Void added (with placeholder IDs -- replace these before deploying)
+- Fields set by Void (`main`, `assets`, `triggers`)
+
+When you run `wrangler deploy`, it picks up this generated `wrangler.json` and deploys everything.
+
+::: tip
+When deploying via `void deploy` (to the Void platform), the `wrangler.json` in the build output is **skipped** -- the platform manages worker configuration via its own deploy manifest. The merge behavior described here only applies to direct `wrangler deploy`.
+:::
+
+## Deploy to your own Cloudflare account
+
+Void's default deployment path is `void deploy`, which uploads to the Void platform. But the generated worker is a standard Cloudflare Worker -- you can deploy it directly to your own account with `wrangler deploy`.
+
+### 1. Create your resources
+
+Create whatever bindings your app uses:
+
+```bash
+# D1 database
+wrangler d1 create my-app-db
+
+# KV namespace
+wrangler kv namespace create KV
+
+# R2 bucket
+wrangler r2 bucket create my-app-storage
+```
+
+### 2. Add a `wrangler.jsonc`
+
+Create `wrangler.jsonc` in your project root with the resource IDs from step 1:
+
+```jsonc
+{
+  "name": "my-app",
+  "compatibility_date": "2026-02-24",
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "my-app-db",
+      "database_id": "<your-database-id>",
+    },
+  ],
+  "kv_namespaces": [
+    {
+      "binding": "KV",
+      "id": "<your-namespace-id>",
+    },
+  ],
+  "r2_buckets": [
+    {
+      "binding": "STORAGE",
+      "bucket_name": "my-app-storage",
+    },
+  ],
+}
+```
+
+Only include the bindings your app actually uses. You can also add service bindings, custom routes, environment overrides, and any other standard wrangler fields -- they all flow through to the build output. You don't need `main` or `assets` -- those are set by the plugin.
+
+### 3. Run migrations
+
+If your app uses D1, apply migrations before deploying:
+
+```bash
+wrangler d1 migrations apply DB --remote
+```
+
+This uses the same `db/migrations/` directory that Void uses locally.
+
+### 4. Build and deploy
+
+```bash
+vite build && wrangler deploy
+```
+
+That's it. The Cloudflare Vite plugin produces a complete build output with a merged `wrangler.json` in the dist directory (containing your real resource IDs and any inferred bindings), and `wrangler deploy` picks it up.
+
+### Local development
+
+`pnpm dev` continues to work as before -- Miniflare creates local instances of all bindings regardless of the IDs in your `wrangler.jsonc`. Your real resource IDs are only used when you run `wrangler deploy`.