void 0.1.6 → 0.7.0

package/skills/void/docs/integrations/frameworks/analog.md

@@ -0,0 +1,182 @@
+---
+outline: deep
+---
+
+# Analog
+
+[Analog](https://analogjs.org/) is a Vite-based Angular meta-framework powered by Nitro. Add `voidPlugin()` to the Vite config for binding inference, typed DB, and migrations during development.
+
+## Setup
+
+### 1. Create a new project
+
+```bash
+npx create-analog@latest my-app
+cd my-app
+```
+
+### 2. Install dependencies
+
+```bash
+npm install -D void wrangler nitro-cloudflare-dev
+```
+
+The `wrangler` dependency is needed for local Cloudflare bindings. `nitro-cloudflare-dev` creates a Cloudflare platform proxy during dev so that `void/db`, `void/kv`, and other runtime helpers can access bindings.
+
+### 3. Configure `vite.config.ts`
+
+```ts
+import { resolve } from 'node:path';
+import { defineConfig } from 'vite';
+import analog from '@analogjs/platform';
+import { voidPlugin } from 'void';
+
+export default defineConfig({
+  resolve: {
+    mainFields: ['module'],
+  },
+  plugins: [
+    analog({
+      ssr: true,
+      nitro: {
+        preset: 'cloudflare-module',
+        modules: ['nitro-cloudflare-dev'],
+        alias: {
+          // Nitro has its own bundler that doesn't use Vite aliases.
+          // Duplicate @schema here so Nitro can resolve it.
+          '@schema': resolve(__dirname, 'db/schema.ts'),
+        },
+      },
+    }),
+    voidPlugin(),
+  ],
+});
+```
+
+### 4. Create `wrangler.jsonc`
+
+`voidPlugin()` auto-syncs inferred bindings into this file on dev startup:
+
+```jsonc
+{
+  "name": "my-app",
+  "compatibility_date": "2026-02-24",
+  "compatibility_flags": ["nodejs_compat", "nodejs_als"],
+}
+```
+
+`nodejs_compat` is required for Nitro's Cloudflare runtime. `nodejs_als` is required for `void/*` runtime helpers (e.g. `void/db`, `void/kv`).
+
+### 5. Deploy
+
+```bash
+void auth login
+void deploy
+```
+
+## Using Void Platform Features
+
+Most [Void platform features](../../guide/app-types.md#void-apps) work with Analog. Use them in page server loaders, actions, and API routes:
+
+Void-managed auth is not supported in framework mode yet. Use Better Auth's official integration directly for now.
+
+### Database
+
+```ts
+// src/app/pages/users.server.ts
+import type { PageServerLoad } from '@analogjs/router';
+import { db } from 'void/db';
+import { users } from '@schema';
+
+export const load = async ({ event }: PageServerLoad) => {
+  return { users: await db.select().from(users) };
+};
+```
+
+::: warning ⚠️ Analog limitation
+Analog uses Nitro, which bundles server routes outside of Vite's plugin pipeline. The schema cannot be injected into the `db` instance, so `db.query.*` relational queries are not available in Analog. Use the standard query builder API (`db.select().from(table)`) instead.
+:::
+
+### KV Storage
+
+```ts
+import type { PageServerLoad } from '@analogjs/router';
+import { kv } from 'void/kv';
+
+export const load = async ({ event }: PageServerLoad) => {
+  return { settings: await kv.get('app:settings') };
+};
+```
+
+### Blob Storage
+
+```ts
+import type { PageServerLoad } from '@analogjs/router';
+import { storage } from 'void/storage';
+
+export const load = async ({ event }: PageServerLoad) => {
+  return { avatar: await storage.get('avatars/user-1.png') };
+};
+```
+
+### AI
+
+```ts
+// src/server/routes/api/summarize.ts
+import { eventHandler } from 'h3';
+import { ai } from 'void/ai';
+
+export default eventHandler(async () => {
+  return ai.run('@cf/meta/llama-3.1-8b-instruct', {
+    prompt: 'Summarize the latest news',
+  });
+});
+```
+
+### Cron Jobs
+
+```ts
+// crons/daily-cleanup.ts
+import { defineScheduled } from 'void';
+
+export const cron = '0 0 * * *';
+
+export default defineScheduled(async () => {
+  // runs daily at midnight
+});
+```
+
+### Queue Consumers
+
+```ts
+// queues/emails.ts
+import { defineQueue } from 'void';
+
+export default defineQueue<{ to: string; subject: string }>(async (batch) => {
+  for (const msg of batch.messages) {
+    // process each message
+    msg.ack();
+  }
+});
+```
+
+### Environment Variables
+
+Void gives you a typed env layer: declare keys in `env.ts`, read them via `import { env } from "void/env"`, and get schema validation at build + deploy time plus a client-leak guard that fails the build if a server-only key reaches the browser. See the [env vars guide](../../guide/env-vars.md) for the full feature set.
+
+`void/env` replaces the H3 event context and `import { env } from "cloudflare:workers"` for env-var access. Keep those around when you need raw binding access (D1, KV, R2, etc.).
+
+## Accessing Bindings Directly
+
+You can also access raw Cloudflare bindings via the H3 event context or the `cloudflare:workers` module:
+
+```ts
+// src/server/routes/api/users.ts
+import { eventHandler } from 'h3';
+import { env } from 'cloudflare:workers';
+
+export default eventHandler(async () => {
+  const { results } = await env.DB.prepare('SELECT * FROM users').all();
+  return results;
+});
+```

package/skills/void/docs/integrations/frameworks/astro.md

@@ -0,0 +1,197 @@
+---
+outline: deep
+---
+
+# Astro
+
+[Astro](https://astro.build/) has its own CLI and Cloudflare adapter (`@astrojs/cloudflare`). Add `voidPlugin()` to Astro's Vite config for binding inference, typed DB, and migrations during development.
+
+::: warning Astro 6 required
+
+- [Astro 6+](https://astro.build/blog/astro-6/) is required to use `import { x } from "void/x"` helpers in Astro apps.
+- You also need to enable `"nodejs_als"` under `compatibility_flags` in your wrangler config.
+  :::
+
+## Setup
+
+### 1. Create a new project
+
+```bash
+npm create astro@latest my-app
+cd my-app
+```
+
+### 2. Install dependencies
+
+```bash
+npm install -D @astrojs/cloudflare void
+```
+
+### 3. Configure `astro.config.mjs`
+
+```js
+import { defineConfig } from 'astro/config';
+import cloudflare from '@astrojs/cloudflare';
+import { voidPlugin } from 'void';
+
+export default defineConfig({
+  adapter: cloudflare(),
+  vite: { plugins: [voidPlugin()] },
+});
+```
+
+By default, Astro Cloudflare runtime and `voidPlugin()` migrations share Wrangler's local state at `.wrangler/state/v3`, so no extra persistence configuration is required.
+
+### 4. Create `wrangler.jsonc`
+
+`voidPlugin()` auto-syncs inferred bindings into this file on dev startup:
+
+```jsonc
+{
+  "name": "my-app",
+  "compatibility_date": "2026-02-24",
+  "compatibility_flags": ["nodejs_als"],
+}
+```
+
+`nodejs_als` is required for `void/*` runtime helpers (for example `void/db`, `void/kv`) in Astro.
+
+### 5. Deploy
+
+```bash
+void auth login
+void deploy
+```
+
+## Using Void Platform Features
+
+Most [Void platform features](../../guide/app-types.md#void-apps) work with Astro in both local dev and production when using Astro 6+ with `nodejs_als`.
+
+Void-managed auth is not supported in framework mode yet. Use Better Auth's official Astro integration directly for now.
+
+Pages that access runtime bindings must opt out of prerendering:
+
+```astro
+---
+export const prerender = false;
+// now Astro.locals.runtime is available
+---
+```
+
+### Database
+
+Use `void/db` in API routes and server-side code:
+
+```ts
+import type { APIRoute } from 'astro';
+import { db } from 'void/db';
+import { users } from '@schema';
+
+export const GET: APIRoute = async () => {
+  const rows = await db.select().from(users);
+  return Response.json(rows);
+};
+```
+
+### KV Storage
+
+Use `void/kv` in both dev and production:
+
+```ts
+import type { APIRoute } from 'astro';
+import { kv } from 'void/kv';
+
+export const GET: APIRoute = async () => {
+  const settings = await kv.get('app:settings');
+  return Response.json(settings);
+};
+```
+
+### Blob Storage
+
+```ts
+import type { APIRoute } from 'astro';
+import { storage } from 'void/storage';
+
+export const GET: APIRoute = async () => {
+  const avatar = await storage.get('avatars/user-1.png');
+  return new Response(avatar);
+};
+```
+
+### AI
+
+```ts
+import type { APIRoute } from 'astro';
+import { ai } from 'void/ai';
+
+export const POST: APIRoute = async () => {
+  const result = await ai.run('@cf/meta/llama-3.1-8b-instruct', {
+    prompt: 'Summarize the latest news',
+  });
+  return Response.json(result);
+};
+```
+
+### Cron Jobs
+
+```ts
+// crons/daily-cleanup.ts
+import { defineScheduled } from 'void';
+
+export const cron = '0 0 * * *';
+
+export default defineScheduled(async () => {
+  // runs daily at midnight
+});
+```
+
+### Queue Consumers
+
+```ts
+// queues/emails.ts
+import { defineQueue } from 'void';
+
+export default defineQueue<{ to: string; subject: string }>(async (batch) => {
+  for (const msg of batch.messages) {
+    // process each message
+    msg.ack();
+  }
+});
+```
+
+### Environment Variables
+
+Void gives you a typed env layer: declare keys in `env.ts`, read them via `import { env } from "void/env"`, and get schema validation at build + deploy time plus a client-leak guard that fails the build if a server-only key reaches the browser. See the [env vars guide](../../guide/env-vars.md) for the full feature set.
+
+Astro-specific note: the client prefix is `PUBLIC_*` (Astro's default `envPrefix`), not `VITE_*` — name client-exposed keys accordingly and the leak guard + constant folding honour the prefix automatically.
+
+`void/env` replaces [`astro:env`](https://docs.astro.build/en/guides/environment-variables/) and `Astro.locals.runtime.env` for env-var access. Keep `Astro.locals.runtime.env` around when you need raw binding access (D1, KV, R2, etc.).
+
+## Accessing Bindings Directly
+
+Access bindings via `Astro.locals.runtime.env` (works in both dev and production):
+
+```ts
+import type { APIRoute } from 'astro';
+
+export const GET: APIRoute = async ({ locals }) => {
+  const { DB } = locals.runtime.env;
+  const { results } = await DB.prepare('SELECT * FROM users').all();
+  return Response.json(results);
+};
+```
+
+In `.astro` pages (remember to set `prerender = false`):
+
+```astro
+---
+export const prerender = false;
+const { DB } = Astro.locals.runtime.env;
+const { results } = await DB.prepare("SELECT * FROM users").all();
+---
+```
+
+::: tip Direct Binding Access
+`Astro.locals.runtime.env` is still useful when you need direct access to raw Cloudflare bindings.
+:::

package/skills/void/docs/integrations/frameworks/nuxt.md

@@ -0,0 +1,164 @@
+---
+outline: deep
+---
+
+# Nuxt
+
+[Nuxt](https://nuxt.com/) has its own CLI and build system based on Nitro. Add `voidPlugin()` to Nuxt's Vite config for binding inference, typed DB, and migrations during development.
+
+## Setup
+
+### 1. Create a new project
+
+```bash
+npm create nuxt@latest my-app
+cd my-app
+```
+
+### 2. Install dependencies
+
+```bash
+npm install -D void wrangler
+```
+
+The `wrangler` dependency is needed by Nuxt to create Cloudflare platform proxy during dev.
+
+### 3. Configure `nuxt.config.ts`
+
+```ts
+import { resolve } from 'node:path';
+import { voidPlugin } from 'void';
+
+export default defineNuxtConfig({
+  nitro: {
+    preset: 'cloudflare-module',
+    alias: {
+      // Nitro has its own bundler that doesn't use Vite aliases.
+      // Duplicate @schema here so Nitro can resolve it.
+      '@schema': resolve(__dirname, 'db/schema.ts'),
+    },
+  },
+  vite: { plugins: [voidPlugin()] },
+});
+```
+
+By default, Nuxt Cloudflare dev runtime and `voidPlugin()` migrations share Wrangler's local state at `.wrangler/state/v3`, so no extra persistence configuration is required.
+
+### 4. Create `wrangler.jsonc`
+
+`voidPlugin()` auto-syncs inferred bindings into this file on dev startup:
+
+```jsonc
+{
+  "name": "my-app",
+  "compatibility_date": "2026-02-24",
+  "compatibility_flags": ["nodejs_compat", "nodejs_als"],
+}
+```
+
+### 5. Deploy
+
+```bash
+void auth login
+void deploy
+```
+
+## Using Void Platform Features
+
+Most [Void platform features](../../guide/app-types.md#void-apps) work with Nuxt. Use them in server routes, API handlers, and middleware:
+
+Void-managed auth is not supported in framework mode yet. Use Better Auth's official Nuxt integration directly for now.
+
+### Database
+
+```ts
+// server/api/users.get.ts
+import { db } from 'void/db';
+import { users } from '@schema';
+
+export default defineEventHandler(async () => {
+  return db.select().from(users);
+});
+```
+
+::: warning ⚠️ Nuxt limitation
+Nuxt uses Nitro, which bundles server routes outside of Vite's plugin pipeline. The schema cannot be injected into the `db` instance, so `db.query.*` relational queries are not available in Nuxt. Use the standard query builder API (`db.select().from(table)`) instead.
+:::
+
+### KV Storage
+
+```ts
+import { kv } from 'void/kv';
+
+export default defineEventHandler(async () => {
+  return kv.get('app:settings');
+});
+```
+
+### Blob Storage
+
+```ts
+import { storage } from 'void/storage';
+
+export default defineEventHandler(async () => {
+  return storage.get('avatars/user-1.png');
+});
+```
+
+### AI
+
+```ts
+import { ai } from 'void/ai';
+
+export default defineEventHandler(async () => {
+  return ai.run('@cf/meta/llama-3.1-8b-instruct', {
+    prompt: 'Summarize the latest news',
+  });
+});
+```
+
+### Cron Jobs
+
+```ts
+// crons/daily-cleanup.ts
+import { defineScheduled } from 'void';
+
+export const cron = '0 0 * * *';
+
+export default defineScheduled(async () => {
+  // runs daily at midnight
+});
+```
+
+### Queue Consumers
+
+```ts
+// queues/emails.ts
+import { defineQueue } from 'void';
+
+export default defineQueue<{ to: string; subject: string }>(async (batch) => {
+  for (const msg of batch.messages) {
+    // process each message
+    msg.ack();
+  }
+});
+```
+
+### Environment Variables
+
+Void gives you a typed env layer: declare keys in `env.ts`, read them via `import { env } from "void/env"`, and get schema validation at build + deploy time plus a client-leak guard that fails the build if a server-only key reaches the browser. See the [env vars guide](../../guide/env-vars.md) for the full feature set.
+
+`void/env` replaces `useRuntimeConfig()` and `event.context.cloudflare.env` for env-var access. Keep `event.context.cloudflare.env` around when you need raw binding access (D1, KV, R2, etc.), and `useRuntimeConfig()` when you need non-env runtime config.
+
+## Accessing Bindings Directly
+
+You can also access raw Cloudflare bindings via Nitro's event context:
+
+```ts
+// server/api/users.get.ts
+export default defineEventHandler(async (event) => {
+  const { DB } = event.context.cloudflare.env;
+  const { results } = await DB.prepare('SELECT * FROM users').all();
+  return results;
+});
+```

package/skills/void/docs/integrations/frameworks/overview.md

@@ -0,0 +1,136 @@
+---
+outline: deep
+---
+
+# Meta-Frameworks
+
+Use this section when your app already has a framework that owns routing and rendering. Void does not try to replace that layer. Instead, it plugs into the Vite build and deployment pipeline so you still get the platform features that matter on the backend.
+
+Void supports deploying meta-framework apps with `void deploy`. Add `voidPlugin()` to your framework's Vite config to get binding inference, typed DB generation, migration management, cron jobs, queues, and caching.
+
+Some frameworks, such as TanStack Start and React Router, compose directly with `@cloudflare/vite-plugin`, which Void already covers. Others, such as SvelteKit, Nuxt, Analog, and Astro, bring their own Cloudflare integrations. In both cases, the framework stays in charge of routing and rendering. Void handles the platform-facing pieces around it.
+
+![void relationships with meta frameworks and deployment targets](./void-relationships.svg)
+
+## Supported Frameworks
+
+| Framework                                           | Package                 | Integration                                                                  |
+| --------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------- |
+| [TanStack Start](https://tanstack.com/start/latest) | `@tanstack/react-start` | Vite plugin composition. `voidPlugin()` runs alongside the framework plugin. |
+| [React Router v7](https://reactrouter.com/)         | `@react-router/dev`     | Vite plugin composition. Setup matches TanStack Start.                       |
+| [SvelteKit](https://svelte.dev/docs/kit)            | `@sveltejs/kit`         | Vite-based, uses its own Cloudflare adapter                                  |
+| [Nuxt](https://nuxt.com/)                           | `nuxt`                  | Own CLI and build toolchain                                                  |
+| [Analog](https://analogjs.org/)                     | `@analogjs/platform`    | Vite-based, uses Nitro with Cloudflare preset                                |
+| [Astro **v6+**](https://astro.build/)               | `astro`                 | Own CLI and Cloudflare adapter (v6 required)                                 |
+
+Detection is automatic. The CLI reads your `package.json` dependencies.
+
+See the individual framework guides for setup instructions:
+
+- [TanStack Start](./tanstack-start.md)
+- [React Router](./react-router.md)
+- [SvelteKit](./sveltekit.md)
+- [Nuxt](./nuxt.md)
+- [Analog](./analog.md)
+- [Astro](./astro.md)
+
+## Feature Support
+
+With `voidPlugin()` added to the framework's Vite config, frameworks get most of the same backend/platform features as [Void apps](../../guide/app-types.md#void-apps):
+
+- **Binding inference:** D1, KV, R2, AI, and queues are detected from source code.
+- **Typed database:** query helpers are generated from `db/migrations/*.sql`.
+- **Migrations:** local D1 is updated on dev startup, and migrations are validated and deployed with `void deploy`.
+- **Runtime helpers:** `void/db`, `void/kv`, `void/storage`, and `void/ai` give you typed access to Cloudflare bindings in dev and production.
+- **Auth:** Void-managed auth is not supported in framework mode yet. For now, use Better Auth's official integration for your framework.
+- **Cron jobs:** scheduled handlers via the `crons/` directory.
+- **Queue consumers:** typed producers and consumers via the `queues/` directory.
+- **Revalidation and prerendering:** configure them with [`routing.revalidate`](../../guide/edge/revalidation.md) and [`routing.prerender`](../../guide/edge/prerendering.md) in `void.json`. Void apps can also set these per page in component files.
+
+Frameworks can also access bindings directly via the framework's own mechanisms (e.g. `platform.env` in SvelteKit, `event.context.cloudflare.env` in Nuxt, `env` from `cloudflare:workers` in Analog, `Astro.locals.runtime.env` in Astro).
+
+## Configuration
+
+### `void.json`
+
+Most configuration is inferred automatically. Use `void.json` to override defaults or fine-tune behavior:
+
+```json
+{
+  "$schema": "https://unpkg.com/void/schema.json",
+  "inference": {
+    "build": "nuxt build",
+    "scanDirs": ["src", "server", "lib"],
+    "bindings": { "db": "MY_DB" }
+  },
+  "routing": {
+    "prerender": ["/", "/about", "/pricing"],
+    "revalidate": 60
+  }
+}
+```
+
+| Field                | Purpose                                                                                                                                                       |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `inference.build`    | Override the default build command                                                                                                                            |
+| `inference.scanDirs` | Directories to scan for binding inference (defaults vary by framework)                                                                                        |
+| `routing.prerender`  | Paths to prerender as static HTML at deploy time                                                                                                              |
+| `routing.revalidate` | Default revalidation TTL in seconds for cached responses                                                                                                      |
+| `inference.bindings` | Override inferred bindings. You only need this if auto-detection is not doing what you want. Accepts `true` or a custom binding name such as `"db": "MY_DB"`. |
+
+See [Configuration](../../reference/config.md) for the full reference.
+
+### `wrangler.jsonc`
+
+Frameworks that use Cloudflare's dev runtime for local dev (SvelteKit, Nuxt with `nitro-cloudflare-dev`, Astro) need a `wrangler.jsonc` for binding configuration. `voidPlugin()` auto-syncs inferred bindings into this file on dev startup:
+
+```jsonc
+{
+  "name": "my-app",
+  "compatibility_date": "2026-02-24",
+  "compatibility_flags": ["nodejs_compat"],
+  // Bindings below are auto-managed by voidPlugin()
+}
+```
+
+Existing bindings are preserved. Only missing ones are added with local placeholder IDs.
+
+For `void deploy`, compatibility settings are read from `wrangler.jsonc` automatically (no need to duplicate them in `void.json`).
+
+## Deploy Pipeline
+
+SvelteKit, Nuxt, Analog, and Astro apps follow this pipeline:
+
+```
+void deploy
+  │
+  ├─ 1. Detect framework
+  │    Reads package.json → determines framework + output conventions
+  │
+  ├─ 2. Build
+  │    Runs framework's build command (or void.json `build` override)
+  │    SvelteKit: vite build → .svelte-kit/cloudflare/
+  │    Nuxt:      nuxt build → .output/
+  │    Analog:    vite build → dist/analog/
+  │    Astro:     astro build → dist/
+  │
+  ├─ 3. Analyze
+  │    ├─ Locate worker entry + static assets from known output paths
+  │    ├─ Infer bindings from source or read from void.json
+  │    ├─ Collect migrations from db/migrations/*.sql
+  │    ├─ Detect cron and queue handlers
+  │    └─ Read wrangler.jsonc compat settings
+  │
+  ├─ 4. Wrap (if needed)
+  │    If crons or queues are configured:
+  │    ├─ Generate wrapper entry module
+  │    ├─ Bundle with Vite (wraps framework's worker)
+  │    └─ Wrapper adds scheduled/queue handlers
+  │
+  ├─ 5. Package + upload
+  │    Same as full-stack: hash-based asset diffing,
+  │    multipart upload, platform provisioning
+  │
+  └─ 6. Live
+       https://my-app.void.app
+```