void 0.20.3 → 0.21.0

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

@@ -94,14 +94,16 @@ This augments the `Cloudflare.Env` interface with `DB`, `KV`, `STORAGE`, `AI`, a
 | `QUEUE_*`        | `Queue<T>`               | `defineQueue()` or `import { queues } from "void/queues"`       |
 | filename-derived | `DurableObjectNamespace` | module in `durable-objects/`                                    |
 
-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`:
+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.config.ts`:
 
-```json
-{
-  "inference": {
-    "bindings": { "db": true, "kv": true, "storage": false, "ai": "MY_AI" }
-  }
-}
+```ts
+import { defineConfig } from 'void/config';
+
+export default defineConfig({
+  inference: {
+    bindings: { db: true, kv: true, storage: false, ai: 'MY_AI' },
+  },
+});
 ```
 
 `db`, `kv`, `storage`, and `ai` accept a string to customize the binding name (for example, `"db": "MY_DB"` or `"ai": "MY_AI"`). `email` is a boolean feature switch.
@@ -110,15 +112,17 @@ See [Configuration](../reference/config.md) for details.
 
 ### Cloudflare configuration passthrough
 
-You can set non-binding Cloudflare fields like `compatibility_date` and `compatibility_flags` in `void.json`:
+You can set non-binding Cloudflare fields like `compatibility_date` and `compatibility_flags` in `void.config.ts`:
 
-```json
-{
-  "worker": {
-    "compatibility_date": "2026-02-24",
-    "compatibility_flags": ["nodejs_compat"]
-  }
-}
+```ts
+import { defineConfig } from 'void/config';
+
+export default defineConfig({
+  worker: {
+    compatibility_date: '2026-02-24',
+    compatibility_flags: ['nodejs_compat'],
+  },
+});
 ```
 
 For environment variables, declare the schema in `env.ts` and put local values in the single root `.env` file. Void loads `.env` into local development bindings only; it never becomes production configuration:
@@ -128,71 +132,69 @@ For environment variables, declare the schema in `env.ts` and put local values i
 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 [Cloudflare config merging](#cloudflare-config-merging) for details.
+Binding arrays such as `d1_databases`, `kv_namespaces`, and `r2_buckets` belong in the `cloudflare` field. Void adds inferred bindings that are missing by name and preserves custom bindings with real resource IDs. See [Cloudflare config merging](#cloudflare-config-merging) for details.
 
-For non-secret plain-text defaults, you can also set `worker.vars` in `void.json`. Local `.env` values override `worker.vars` during development. Production builds reject any `worker.vars` name that is declared as a server key in `env.ts`; store those values remotely with `void secret put` instead.
+For non-secret plain-text defaults, you can also set `worker.vars` in `void.config.ts`. Local `.env` values override `worker.vars` during development. Production builds reject any `worker.vars` name that is declared as a server key in `env.ts`; store those values remotely with `void secret put` instead.
 
 ## Cloudflare 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.
+Void reads `void.config.ts`, combines its `cloudflare` settings with provisioned values in `void.lock.json`, and generates the Cloudflare config needed by the build and deploy tools. Root `wrangler.jsonc` and `wrangler.json` files from existing apps are migrated automatically by `void init` or `void deploy`. Bindings are inferred from source code and use 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.
+Edit `cloudflare` in `void.config.ts` for custom Worker settings. Commit `void.lock.json` when Void records resource IDs or Durable Object migration history.
 
 ### 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`:
+In Void's default mode and frameworks where Void controls the Cloudflare integration (TanStack Start, React Router), Void manages `@cloudflare/vite-plugin` directly. It merges inferred bindings with the generated Cloudflare config:
 
-1. The plugin reads your `wrangler.jsonc` and resolves it into a config object with `d1_databases`, `kv_namespaces`, `r2_buckets`, etc.
+1. The plugin reads the generated config containing your `cloudflare` settings and Void's recorded resource values.
 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.
+All other `cloudflare` fields -- `name`, `routes`, `services`, `vars`, `env`, `compatibility_date`, etc. -- flow through to the build output.
 
 Fields that Void always sets (`main`, `triggers`, `assets`) don't need to be in your Cloudflare config -- they're added programmatically based on your project structure.
 
-In this mode, normal inferred bindings are merged purely in memory. Typed state modules in `durable-objects/` are the exception: Void persists their bindings and `new_sqlite_classes` entries to `wrangler.jsonc` because Cloudflare Durable Object migration history must remain append-only across builds. Commit those entries.
+In this mode, normal inferred bindings are merged in memory. Typed state modules in `durable-objects/` are the exception: Void records their bindings and append-only `new_sqlite_classes` history in `void.lock.json`. Commit the lock.
 
 ### 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:
+Because Void does not control the Cloudflare plugin in this mode, it syncs inferred bindings to the generated Cloudflare config on dev startup:
 
 - 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 the Cloudflare config so the framework adapter reads the same value.
+- If `worker.compatibility_date` is set in `void.config.ts`, syncs that date into the Cloudflare 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.
+- The framework adapter reads the generated config through its configured path.
 
-The framework adapter reads bindings from `wrangler.jsonc`. Void adds them as you import resources, and `void deploy --platform cloudflare` replaces local placeholder IDs when it provisions production resources.
+The framework adapter reads the generated config. Void adds bindings as you import resources, and `void deploy --platform cloudflare` replaces local placeholder IDs when it provisions production resources.
 
 ### 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 |
+| Source                          | Priority                      | What it controls                                                    |
+| ------------------------------- | ----------------------------- | ------------------------------------------------------------------- |
+| `void.config.ts` `cloudflare`   | Highest for authored settings | Resource IDs, service bindings, routes, vars, environments          |
+| `void.config.ts` `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`, the project Cloudflare config, or the supported generated build fallback during deploy, Void pins the latest known-good date to `void.json` and uses it for that run.
+If no date is found in `void.config.ts` or the generated build config, Void records the latest known-good date 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:
+If your code uses `c.env.DB` and `c.env.KV`, and `cloudflare` 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" }],
-}
+```ts
+// Inside defineConfig({ ... })
+cloudflare: {
+  name: 'my-app',
+  d1_databases: [{
+    binding: 'DB',
+    database_name: 'my-app-db',
+    database_id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+  }],
+  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.
@@ -203,7 +205,7 @@ This means `pnpm dev` works out of the box (Miniflare creates local instances of
 
 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)
+- All `cloudflare` fields from `void.config.ts` (bindings with real IDs, routes, services, vars, environments)
 - Any inferred bindings Void added (local placeholders during development; provisioned IDs during deploy)
 - Fields set by Void (`main`, `assets`, `triggers`)
 
@@ -221,7 +223,7 @@ Choose Cloudflare during `void init`, then deploy:
 void deploy
 ```
 
-Void opens your browser to sign in when needed. If you have access to several accounts, it asks which one to use and saves the account in your root `wrangler.jsonc`. Credentials are stored in your operating system's keychain. Press Ctrl+C to cancel login, or manage your session with `void cloudflare login`, `status`, and `logout`.
+Void opens your browser to sign in when needed. If you have access to several accounts, it asks which one to use and records the account in `void.lock.json`. Credentials are stored in your operating system's keychain. Press Ctrl+C to cancel login, or manage your session with `void cloudflare login`, `status`, and `logout`.
 
 To configure deployment separately from project setup, run `void connect --platform cloudflare`. It uses the same browser login and account selection as `void init`, and saves Cloudflare as the target for subsequent `void deploy` commands.
 
@@ -237,7 +239,7 @@ This deploys directly to your account. You don't need a Void platform connection
 
 ### Deploy an existing Worker
 
-This handoff is for the existing source of an app already built with Void and previously deployed directly to Cloudflare. Keep its `wrangler.jsonc` or `wrangler.json`, then run:
+This handoff is for the existing source of an app already built with Void and previously deployed directly to Cloudflare. Keep its `wrangler.jsonc` or `wrangler.json` for the first deploy; Void migrates it to `void.config.ts` and `void.lock.json` after linking the Worker. Then run:
 
 ```sh
 void deploy
@@ -247,20 +249,20 @@ If the project has no deployment destination, Void asks whether to link and depl
 
 The first handoff preserves resource bindings, production variables, encrypted secrets, event handlers, and existing routes and schedules. It builds the app, checks the uploaded version's bindings and handler set, and verifies readiness before activating it. Void saves `keep_vars: true` in your config so later deployments retain dashboard-only variables too. The active version must also be the latest uploaded version; activate or remove an unpublished candidate in Cloudflare before retrying so secret inheritance has an unambiguous source.
 
-Keep this first deployment focused on the existing site. Apart from the explicit ISR cache choice below, new resources, auth setup, runtime features, database migrations, and secret overrides stop the handoff before activation. A later code-only deploy continues to preserve dashboard-managed routes and visibility. Before adding a cron, queue consumer, workflow, or visibility change when those values exist only in the dashboard, add the current `routes`, `workers_dev`, and `preview_urls` values to the root Wrangler config. If the build fails, fix it and rerun `void deploy`; Void remembers the destination and checks the existing Worker again.
+Keep this first deployment focused on the existing site. Apart from the explicit ISR cache choice below, new resources, auth setup, runtime features, database migrations, and secret overrides stop the handoff before activation. A later code-only deploy continues to preserve dashboard-managed routes and visibility. Before adding a cron, queue consumer, workflow, or visibility change when those values exist only in the dashboard, add the current `routes`, `workers_dev`, and `preview_urls` values under `cloudflare` in `void.config.ts`. If the build fails, fix it and rerun `void deploy`; Void remembers the destination and checks the existing Worker again.
 
-Pages with `prerender = true` (including automatically prerendered Markdown pages) also request ISR caching. When the existing Worker has no cache, Void asks whether to enable it and saves the choice as `routing.isr` in `void.json`:
+Pages with `prerender = true` (including automatically prerendered Markdown pages) also request ISR caching. When the existing Worker has no cache, Void asks whether to enable it and saves the choice as `routing.isr` in `void.config.ts`:
 
 - **Yes:** provisions the KV cache and enables ISR in this deployment. The uploaded Worker must retain every existing binding and use exactly the approved cache namespace.
 - **No:** saves `routing.isr: false`. Pages render on each request, and later deployments keep ISR disabled until you change that setting.
 
-You can keep your page-level prerender and revalidate exports with either choice. The same saved choice applies to retries, other machines, and CI; completing the handoff does not change it. To choose ahead of time, set `routing.isr` to `true` or `false`. A non-interactive handoff with no saved choice stops with instructions to set it. Existing caches keep their namespace IDs. Commit `void.json` and any updated resource IDs in the root Cloudflare config.
+You can keep your page-level prerender and revalidate exports with either choice. The same saved choice applies to retries, other machines, and CI; completing the handoff does not change it. To choose ahead of time, set `routing.isr` to `true` or `false`. A non-interactive handoff with no saved choice stops with instructions to set it. Existing caches keep their namespace IDs. Commit `void.config.ts` and `void.lock.json` when it changes.
 
-If linking reports other missing inferred resources, the error lists each binding and why the app needs it. Check that the root config uses the existing Worker's binding names and resource IDs, and that `inference.bindings` in `void.json` matches those names. An application KV binding explicitly named `ISR_CACHE` is still required. An existing D1 binding without checked-in migrations can keep its current `migrations_dir`, including an omitted value; linking does not provision a database or change its migration settings. Keep `.void/cloudflare-link.json` when retrying so the handoff checks remain in place.
+If linking reports other missing inferred resources, the error lists each binding and why the app needs it. Check that `cloudflare` in `void.config.ts` uses the existing Worker's binding names and resource IDs, and that `inference.bindings` in `void.config.ts` matches those names. An application KV binding explicitly named `ISR_CACHE` is still required. An existing D1 binding without checked-in migrations can keep its current `migrations_dir`, including an omitted value; linking does not provision a database or change its migration settings. Keep `.void/cloudflare-link.json` when retrying so the handoff checks remain in place.
 
 Declining the initial link-and-deploy prompt leaves the project unchanged. Explicit platform choices and existing project links take precedence. In CI, select the destination with `--platform cloudflare` and provide Cloudflare credentials.
 
-Direct deployment uses the top-level JSON/JSONC configuration; convert a `wrangler.toml` with the same settings before linking. Named environments need a separate top-level config. If previews are disabled, include the existing production hostname in your config so Void can check the candidate through it.
+Direct deployment uses the top-level `cloudflare` settings in `void.config.ts`; convert a `wrangler.toml` to JSON/JSONC before linking. Named environments need a separate Void project config. If previews are disabled, include the existing production hostname in your config so Void can check the candidate through it.
 
 ### What happens during deploy
 
@@ -276,7 +278,7 @@ Void reads your app's configuration and source, then:
 
 The secret and migration checks need the built Worker, so they happen after provisioning and building. If a check fails, resources may already exist, but Void has not applied remote D1 migrations or uploaded the application Worker.
 
-Resource IDs are saved in `wrangler.jsonc` for the next deploy. Void preserves comments, though it may adjust indentation when writing the file. Commit the updated config so other machines and CI can reuse the same resources. The old `--provision` flag is still accepted, but provisioning is now automatic.
+Resource IDs are saved in `void.lock.json` for the next deploy. Commit the lock so other machines and CI can reuse the same resources. The old `--provision` flag is still accepted, but provisioning is now automatic.
 
 Run the first deploy from one machine at a time. The provisioning lock protects a local config file; it cannot coordinate two fresh CI runners, which could create duplicate resources.
 
@@ -284,7 +286,7 @@ Run the first deploy from one machine at a time. The provisioning lock protects
 
 Set `CLOUDFLARE_API_TOKEN` in your CI secrets. The token needs Workers Scripts: Edit and read access to bound resources, plus edit permission for each product Void needs to provision. Set `CLOUDFLARE_ACCOUNT_ID` if the token can access more than one account.
 
-Email setup needs a browser session from `void cloudflare login`, which carries the Email Routing and Email Sending scopes, or a `CLOUDFLARE_API_TOKEN` that also has Email Routing Edit and Email Sending Edit. A Global API Key pair is refused. In CI the email step never prompts: run `void email setup --platform cloudflare` once locally, commit `wrangler.jsonc`, then deploy with `--require-email`.
+Email setup needs a browser session from `void cloudflare login`, which carries the Email Routing and Email Sending scopes, or a `CLOUDFLARE_API_TOKEN` that also has Email Routing Edit and Email Sending Edit. A Global API Key pair is refused. In CI the email step never prompts: run `void email setup --platform cloudflare` once locally, commit `void.lock.json`, then deploy with `--require-email`.
 
 When a Worker has no version preview URL, such as a Worker with Durable Objects, also set `CLOUDFLARE_WORKERS_SUBDOMAIN`. Use the account subdomain, for example `my-team` or `my-team.workers.dev`. Local deploys cache this value in ignored `.void/cloudflare.json` after Cloudflare reports a deployment URL; a fresh CI checkout has no such cache.
 
@@ -304,7 +306,7 @@ If Access blocks a version preview but allows the stable Worker hostname, Void c
 
 PostgreSQL and MySQL apps need a production `DATABASE_URL` in the deploy process environment. Void uses it for Hyperdrive provisioning and migrations, and never writes it to generated config. PostgreSQL migrations are transactional; MySQL schema changes may partially apply before an error.
 
-Creating a Hyperdrive config for the first time also requires `CLOUDFLARE_API_TOKEN` with Hyperdrive edit permission. Void needs the REST API to find existing configurations, and the current provisioning path can't use browser OAuth for that lookup. Alternatively, create the config in the Cloudflare dashboard and add its ID to the `hyperdrive` binding in `wrangler.jsonc`. An app with an existing Hyperdrive binding can deploy through browser login.
+Creating a Hyperdrive config for the first time also requires `CLOUDFLARE_API_TOKEN` with Hyperdrive edit permission. Void needs the REST API to find existing configurations, and the current provisioning path can't use browser OAuth for that lookup. Alternatively, create the config in the Cloudflare dashboard and add its ID to the `cloudflare.hyperdrive` binding in `void.config.ts`. An app with an existing Hyperdrive binding can deploy through browser login.
 
 For auth-enabled apps, run `void db generate` and commit the migrations. Void includes the production Better Auth schema, including renamed tables and plugin tables, and checks it against your migration history during deploy. D1 also gets an in-memory schema check before remote migration. A mismatch stops deployment and asks you to regenerate the SQL.
 
@@ -339,7 +341,7 @@ Void supports Worker apps, static sites, SPAs, known SSGs, `--dir` deploys, and
 
 Static sites use a small Worker in front of Workers Assets to handle redirects, rewrites, fallbacks, and headers. Hybrid and SSR apps keep their application Worker. A page that opts out of prerendering, a dynamic page without `getPrerenderPaths()`, or another runtime feature keeps the app on a Worker even with `output: "static"`.
 
-Native Void applications apply `void.json` routing rules in their Worker.
+Native Void applications apply `void.config.ts` routing rules in their Worker.
 Framework-owned Workers do not yet support those Void redirects, rewrites,
 fallbacks, or headers on the direct target. The CLI rejects such configuration
 before provisioning or building; configure the rules in the framework or its
@@ -348,15 +350,13 @@ Worker instead. This restriction does not change an explicit asset policy for
 
 Worker apps support D1, KV, R2, Queues, typed state, PostgreSQL and MySQL through Hyperdrive, auth, WebSockets, AI, cron jobs, and ISR. The main limits are:
 
-- **Sandbox needs Workers Paid and Docker.** Importing `void/sandbox` or enabling `sandbox` in `void.json` adds a Container application. Void checks access before provisioning or building. [Enable Workers Paid](https://dash.cloudflare.com/?to=/:account/workers/plans) and sign in again if needed. API tokens need Account / Containers: Edit and Account / Cloudchamber: Edit. See [Containers pricing](https://developers.cloudflare.com/containers/pricing/). Apps without Sandbox skip this check and remain compatible with Workers Free within its quotas.
+- **Sandbox needs Workers Paid and Docker.** Importing `void/sandbox` or enabling `sandbox` in `void.config.ts` adds a Container application. Void checks access before provisioning or building. [Enable Workers Paid](https://dash.cloudflare.com/?to=/:account/workers/plans) and sign in again if needed. API tokens need Account / Containers: Edit and Account / Cloudchamber: Edit. See [Containers pricing](https://developers.cloudflare.com/containers/pricing/). Apps without Sandbox skip this check and remain compatible with Workers Free within its quotas.
 - **Worker apps need a fresh build.** `--skip-build` works for existing static, SPA, and SSG output. Worker validation needs the current build's vars and auth schema.
-- **Named Cloudflare environments aren't supported.** Direct commands use the top-level root config and reject `CLOUDFLARE_ENV`, `CLOUDFLARE_VITE_WRANGLER_CONFIG_PATH`, and project-local name overrides. Use a separate root config per deployment target.
+- **Named Cloudflare environments aren't supported.** Direct commands use the top-level `cloudflare` settings and reject `CLOUDFLARE_ENV`, `CLOUDFLARE_VITE_WRANGLER_CONFIG_PATH`, and project-local name overrides. Use a separate Void project config per deployment target.
 - **Node.js, Bun, and Deno use a different deployment path.** See their [integration guide](./nodejs-bun-deno.md).
-- **Email is set up on the first deploy, on a zone you own.** Put `email.from` in `void.json`; the deploy reads your account, prints a checklist of what it would change, and asks once. See [Your own Cloudflare account](../guide/email.md#your-own-cloudflare-account). Outside Void's reach: `email/_default.ts` and dynamic local parts (`email/[user].ts`) need a catch-all, which exists only on a zone apex, so on a mail subdomain they get no rule; a mail domain that already has non-Cloudflare MX records is refused, never routed over; `sendEmail()` to arbitrary recipients needs Workers Paid (Email Sending onboarding), otherwise verified destinations only; Void owns the top-level `addresses` array in `wrangler.jsonc`, so hand-written entries there skip the email step; and `void email usage`, `logs`, `allow`, and `destinations` are platform-only.
+- **Email is set up on the first deploy, on a zone you own.** Put `email.from` in `void.config.ts`; the deploy reads your account, prints a checklist of what it would change, and asks once. See [Your own Cloudflare account](../guide/email.md#your-own-cloudflare-account). Outside Void's reach: `email/_default.ts` and dynamic local parts (`email/[user].ts`) need a catch-all, which exists only on a zone apex, so on a mail subdomain they get no rule; a mail domain that already has non-Cloudflare MX records is refused, never routed over; `sendEmail()` to arbitrary recipients needs Workers Paid (Email Sending onboarding), otherwise verified destinations only; Void owns the top-level `addresses` array in the generated Cloudflare config, so hand-written `cloudflare.addresses` entries skip the email step; and `void email usage`, `logs`, `allow`, and `destinations` are platform-only.
 
-WebSocket routes and typed state use SQLite-backed Durable Objects. Commit the bindings and `new_sqlite_classes` migration history in `wrangler.jsonc`; don't delete or reorder deployed migration steps. Older hosted classes using `new_classes` keep their existing storage.
-
-Bare `vite build && wrangler deploy` does not provision schema-declared secrets. Use `wrangler secret bulk` / `wrangler secret put` and list every inherited name under `secrets.required` yourself.
+WebSocket routes and typed state use SQLite-backed Durable Objects. Commit `void.lock.json` when Void adds bindings or `new_sqlite_classes` migration history; don't delete or reorder deployed migration steps. Older hosted classes using `new_classes` keep their existing storage.
 
 ISR uses the shared cache protocol. Entries are scoped to a deployment and hostname, and `routing.revalidateQueryAllowlist` adds bounded query variants. `revalidate()` purges matching entries and variants from KV and the local edge cache. See [ISR](#isr-self-host) below for cache behavior across regions.
 
@@ -378,22 +378,23 @@ These checks detect changes to the deployment target or uploader, but they don't
 
 ### 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 during direct Cloudflare deployment.
+`pnpm dev` continues to work as before -- Miniflare creates local instances of all bindings regardless of the IDs in `void.config.ts`. Your real resource IDs are only used during direct Cloudflare deployment.
 
 ### AI on your Cloudflare account {#ai-self-host}
 
 `void/ai` works on your own Cloudflare account, along two paths:
 
-- **Workers AI** (`ai.run`, `ai.stream`, `ai.image`) works out of the box. When your app imports `void/ai`, `vite build` infers that you need AI and adds a Workers AI binding (`env.AI`) to the generated `wrangler.json` automatically -- you do **not** add it to `wrangler.jsonc`. Set `inference.bindings.ai` to a string to use a custom name.
-- **Provider models** (`ai.provider("openai").fetch(...)`) route through _your own_ Cloudflare AI Gateway. Set its id in `void.json` and add the provider's API key as a Worker secret.
+- **Workers AI** (`ai.run`, `ai.stream`, `ai.image`) works out of the box. When your app imports `void/ai`, `vite build` infers that you need AI and adds a Workers AI binding (`env.AI`) to the generated build config automatically. Set `inference.bindings.ai` to a string to use a custom name.
+- **Provider models** (`ai.provider("openai").fetch(...)`) route through _your own_ Cloudflare AI Gateway. Set its id in `void.config.ts` and add the provider's API key as a Worker secret.
 
-```jsonc
-// void.json
-{
-  "ai": {
-    "gateway": "my-gateway", // an AI Gateway in YOUR Cloudflare account
+```ts
+import { defineConfig } from 'void/config';
+
+export default defineConfig({
+  ai: {
+    gateway: 'my-gateway', // an AI Gateway in your Cloudflare account
   },
-}
+});
 ```
 
 ```bash
@@ -408,7 +409,7 @@ import { ai } from 'void/ai';
 
 export const POST = defineHandler(async (c) => {
   // Workers AI -- uses the inferred or configured AI binding directly
-  const summary = await ai.run('@cf/meta/llama-3.1-8b-instruct', {
+  const summary = await ai.run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
     prompt: 'Summarize the changelog.',
   });
 
@@ -428,22 +429,23 @@ Set `ai.gateway` before calling `ai.provider().fetch()`; otherwise it returns `5
 Notes:
 
 - **Account-owned usage.** Direct deployments use your own [Cloudflare AI Gateway analytics](https://developers.cloudflare.com/ai-gateway/). A team platform meters requests through its shared proxy; those usage records do not automatically bill application developers.
-- **Custom AI binding names are supported.** Configure `"inference": { "bindings": { "ai": "MY_AI" } }`, or declare the custom `ai.binding` in your root Wrangler config; the generated worker records the resolved name for `void/ai` automatically.
+- **Custom AI binding names are supported.** Set `inference.bindings.ai` to `MY_AI`, or declare `cloudflare.ai.binding` in `void.config.ts`; the generated worker records the resolved name for `void/ai` automatically.
 - **Workers AI runs remotely during development.** After `void connect --platform cloudflare`, an app importing `void/ai` uses your account's remote AI binding with your Cloudflare login or API token. Development and preview calls consume that account's allowance. Apps without AI imports add no AI binding or authentication probe.
 
 ### ISR on your Cloudflare account {#isr-self-host}
 
-[Revalidation (ISR)](../guide/edge/revalidation.md) works self-hosted. `void deploy --platform cloudflare` automatically creates or reuses the cache KV namespace and persists its `ISR_CACHE` binding in `wrangler.jsonc`, just like the other inferred resources.
+[Revalidation (ISR)](../guide/edge/revalidation.md) works self-hosted. `void deploy --platform cloudflare` automatically creates or reuses the cache KV namespace and records its `ISR_CACHE` binding in `void.lock.json`, just like the other inferred resources.
 
-Configure revalidation exactly as on the platform -- globally or per-path in `void.json`:
+Configure revalidation exactly as on the platform -- globally or per-path in `void.config.ts`:
 
-```jsonc
-// void.json
-{
-  "routing": {
-    "revalidate": { "/blog/*": 3600, "*": 60 },
+```ts
+import { defineConfig } from 'void/config';
+
+export default defineConfig({
+  routing: {
+    revalidate: { '/blog/*': 3600, '*': 60 },
   },
-}
+});
 ```
 
 ...or per page with an exported `revalidate` literal in a `.server.ts` companion (Pages mode):

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

@@ -40,6 +40,7 @@ export default defineConfig({
       ssr: true,
       nitro: {
         preset: 'cloudflare-module',
+        cloudflareDev: { configPath: './.void-wrangler.jsonc' },
         modules: ['nitro-cloudflare-dev'],
         alias: {
           // Nitro has its own bundler that doesn't use Vite aliases.
@@ -53,16 +54,20 @@ export default defineConfig({
 });
 ```
 
-### 4. Create `wrangler.jsonc`
+### 4. Create `void.config.ts`
 
-`voidPlugin()` auto-syncs inferred bindings into this file on dev startup:
+Void generates the Cloudflare config used by Analog's development runtime:
 
-```jsonc
-{
-  "name": "my-app",
-  "compatibility_date": "2026-02-24",
-  "compatibility_flags": ["nodejs_compat", "nodejs_als"],
-}
+```ts
+import { defineConfig } from 'void/config';
+
+export default defineConfig({
+  cloudflare: {
+    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`).
@@ -127,7 +132,7 @@ import { eventHandler } from 'h3';
 import { ai } from 'void/ai';
 
 export default eventHandler(async () => {
-  return ai.run('@cf/meta/llama-3.1-8b-instruct', {
+  return ai.run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
     prompt: 'Summarize the latest news',
   });
 });

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

@@ -35,23 +35,27 @@ import cloudflare from '@astrojs/cloudflare';
 import { voidPlugin } from 'void';
 
 export default defineConfig({
-  adapter: cloudflare(),
+  adapter: cloudflare({ configPath: './.void-wrangler.jsonc' }),
   vite: { plugins: [voidPlugin()] },
 });
 ```
 
 By default, Astro's Cloudflare runtime and `voidPlugin()` migrations share local state at `.wrangler/state/v3`, so no extra persistence configuration is required.
 
-### 4. Create `wrangler.jsonc`
+### 4. Create `void.config.ts`
 
-`voidPlugin()` auto-syncs inferred bindings into this file on dev startup:
+Void uses this config for the Cloudflare adapter during development and deployment:
 
-```jsonc
-{
-  "name": "my-app",
-  "compatibility_date": "2026-02-24",
-  "compatibility_flags": ["nodejs_als"],
-}
+```ts
+import { defineConfig } from 'void/config';
+
+export default defineConfig({
+  cloudflare: {
+    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.
@@ -126,7 +130,7 @@ 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', {
+  const result = await ai.run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
     prompt: 'Summarize the latest news',
   });
   return Response.json(result);

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

@@ -32,6 +32,7 @@ import { voidPlugin } from 'void';
 export default defineNuxtConfig({
   nitro: {
     preset: 'cloudflare-module',
+    cloudflareDev: { configPath: './.void-wrangler.jsonc' },
     alias: {
       // Nitro has its own bundler that doesn't use Vite aliases.
       // Duplicate @schema here so Nitro can resolve it.
@@ -44,16 +45,20 @@ export default defineNuxtConfig({
 
 By default, Nuxt's Cloudflare development runtime and `voidPlugin()` migrations share local state at `.wrangler/state/v3`, so no extra persistence configuration is required.
 
-### 4. Create `wrangler.jsonc`
+### 4. Create `void.config.ts`
 
-`voidPlugin()` auto-syncs inferred bindings into this file on dev startup:
+Void generates the Cloudflare config used by Nuxt's development runtime:
 
-```jsonc
-{
-  "name": "my-app",
-  "compatibility_date": "2026-02-24",
-  "compatibility_flags": ["nodejs_compat", "nodejs_als"],
-}
+```ts
+import { defineConfig } from 'void/config';
+
+export default defineConfig({
+  cloudflare: {
+    name: 'my-app',
+    compatibility_date: '2026-02-24',
+    compatibility_flags: ['nodejs_compat', 'nodejs_als'],
+  },
+});
 ```
 
 ### 5. Deploy
@@ -111,7 +116,7 @@ export default defineEventHandler(async () => {
 import { ai } from 'void/ai';
 
 export default defineEventHandler(async () => {
-  return ai.run('@cf/meta/llama-3.1-8b-instruct', {
+  return ai.run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
     prompt: 'Summarize the latest news',
   });
 });

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

@@ -45,29 +45,32 @@ With `voidPlugin()` added to the framework's Vite config, frameworks get most of
 - **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.
+- **Revalidation and prerendering:** configure them with [`routing.revalidate`](../../guide/edge/revalidation.md) and [`routing.prerender`](../../guide/edge/prerendering.md) in `void.config.ts`. Void apps can also set these per page in component files.
+
+For framework apps, Void revalidation caches public HTML document responses with both `void deploy` and `void deploy --platform cloudflare`. Client data requests continue to use the framework's own behavior. A response with `Set-Cookie` or `Cache-Control: private`, `no-store`, or `no-cache` is never shared.
 
 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`
+### `void.config.ts`
+
+Most configuration is inferred automatically. Use `void.config.ts` to override defaults or fine-tune behavior:
 
-Most configuration is inferred automatically. Use `void.json` to override defaults or fine-tune behavior:
+```ts
+import { defineConfig } from 'void/config';
 
-```json
-{
-  "$schema": "./node_modules/void/schema.json",
-  "inference": {
-    "build": "nuxt build",
-    "scanDirs": ["src", "server", "lib"],
-    "bindings": { "db": "MY_DB" }
+export default defineConfig({
+  inference: {
+    build: 'nuxt build',
+    scanDirs: ['src', 'server', 'lib'],
+    bindings: { db: 'MY_DB' },
+  },
+  routing: {
+    prerender: ['/', '/about', '/pricing'],
+    revalidate: 60,
   },
-  "routing": {
-    "prerender": ["/", "/about", "/pricing"],
-    "revalidate": 60
-  }
-}
+});
 ```
 
 | Field                | Purpose                                                                                                                                                       |
@@ -81,22 +84,25 @@ Most configuration is inferred automatically. Use `void.json` to override defaul
 
 See [Configuration](../../reference/config.md) for the full reference.
 
-### `wrangler.jsonc`
+### Cloudflare settings
 
-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:
+Frameworks that use Cloudflare's dev runtime need their adapters pointed at Void's generated `.void-wrangler.jsonc`. Their setup guides show the adapter options. Define your Cloudflare settings in `void.config.ts`:
 
-```jsonc
-{
-  "name": "my-app",
-  "compatibility_date": "2026-02-24",
-  "compatibility_flags": ["nodejs_compat"],
-  // Bindings below are auto-managed by voidPlugin()
-}
+```ts
+import { defineConfig } from 'void/config';
+
+export default defineConfig({
+  cloudflare: {
+    name: 'my-app',
+    compatibility_date: '2026-02-24',
+    compatibility_flags: ['nodejs_compat'],
+  },
+});
 ```
 
-Existing bindings are preserved. Only missing ones are added with local placeholder IDs.
+Existing bindings are preserved. D1, KV, and R2 use local placeholder IDs until deployment. For a project connected directly to Cloudflare, importing `void/ai` adds a remote Workers AI binding during development; [Cloudflare login](../../guide/ai.md#local-development) is required to use it. Direct deployments also include the inferred AI binding.
 
-For `void deploy`, compatibility settings are read from `wrangler.jsonc` automatically (no need to duplicate them in `void.json`).
+Void combines these settings with inferred bindings and records provisioned resource IDs in `void.lock.json`. Commit both files.
 
 ## Deploy Pipeline
 
@@ -109,7 +115,7 @@ void deploy
   │    Reads package.json → determines framework + output conventions
   │
   ├─ 2. Build
-  │    Runs framework's build command (or void.json `build` override)
+  │    Runs framework's build command (or void.config.ts `build` override)
   │    SvelteKit: vite build → .svelte-kit/cloudflare/
   │    Nuxt:      nuxt build → .output/
   │    Analog:    vite build → dist/analog/
@@ -117,10 +123,10 @@ void deploy
   │
   ├─ 3. Analyze
   │    ├─ Locate worker entry + static assets from known output paths
-  │    ├─ Infer bindings from source or read from void.json
+  │    ├─ Infer bindings from source or read from void.config.ts
   │    ├─ Collect migrations from db/migrations/*.sql
   │    ├─ Detect cron and queue handlers
-  │    └─ Read wrangler.jsonc compat settings
+  │    └─ Read void.config.ts Cloudflare settings
   │
   ├─ 4. Wrap (if needed)
   │    If crons or queues are configured:

package/skills/void/docs/integrations/frameworks/react-router.md

@@ -87,7 +87,7 @@ export async function loader() {
 import { ai } from 'void/ai';
 
 export async function action() {
-  return ai.run('@cf/meta/llama-3.1-8b-instruct', {
+  return ai.run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
     prompt: 'Summarize the latest news',
   });
 }