void 1.2.1 → 1.4.0

package/dist/{wrangler-F96NnLyb.mjs → wrangler-I-scB_1t.mjs}

@@ -1,12 +1,68 @@
 import { a as join, c as resolve, n as dirname, o as normalize, t as basename } from "./dist-ipQi0Q8y.mjs";
-import "./project-paths-DGu_QZ_Q.mjs";
-import { p as readConfig } from "./config-DHgSEWT7.mjs";
-import { i as persistCloudflareConfig, r as materializeCloudflareConfig } from "./cloudflare-config-DchHxPTo.mjs";
+import { o as TYPED_CONFIG_FILE, s as loadTypedVoidConfigFile } from "./project-paths-DGu_QZ_Q.mjs";
+import { h as validateConfig, p as readConfig } from "./config-OFOAimzt.mjs";
+import { a as persistCloudflareConfig, i as materializeCloudflareConfig, r as ignoreMaterializedCloudflareConfig } from "./cloudflare-config-CH1AylZT.mjs";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { parseSync } from "vite";
 import { appendSqliteClassMigration, isRecord } from "@void/deploy-core";
 import { createHash } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { SyntaxKind, applyEdits, createScanner, findNodeAtLocation, modify, parse, parseTree } from "jsonc-parser";
+//#region src/config-write.ts
+const GENERATED_MARKERS = [
+	"// Generated by void migrate.",
+	"// Generated from void.json by void migrate.",
+	"// Generated by void init."
+];
+function renderVoidConfig(config, marker = GENERATED_MARKERS[0]) {
+	return `${marker}\nimport { defineConfig } from 'void/config';\n\nexport default defineConfig(${JSON.stringify(config, null, 2)});\n`;
+}
+function isStaticValue(node) {
+	if (!node) return false;
+	if (node.type === "Literal") return node.value === null || [
+		"string",
+		"number",
+		"boolean"
+	].includes(typeof node.value);
+	if (node.type === "UnaryExpression") return node.operator === "-" && node.argument?.type === "Literal" && typeof node.argument.value === "number";
+	if (node.type === "ArrayExpression") return node.elements?.every(isStaticValue) ?? false;
+	if (node.type !== "ObjectExpression") return false;
+	return node.properties?.every((property) => property.type === "Property" && property.kind === "init" && !property.computed && !property.method && (property.key?.type === "Identifier" || property.key?.type === "Literal") && isStaticValue(property.value)) ?? false;
+}
+function isGeneratedStaticConfig(source) {
+	if (!GENERATED_MARKERS.some((marker) => source.startsWith(marker))) return false;
+	let program;
+	try {
+		const parsed = parseSync(TYPED_CONFIG_FILE, source, {
+			lang: "js",
+			sourceType: "module",
+			preserveParens: false,
+			showSemanticErrors: true
+		});
+		if (parsed.errors.length > 0 || parsed.comments.length !== 1 || !GENERATED_MARKERS.includes(`// ${parsed.comments[0]?.value.trim()}`)) return false;
+		program = parsed.program;
+	} catch {
+		return false;
+	}
+	const [importDeclaration, exportDeclaration] = program.body ?? [];
+	const call = exportDeclaration?.declaration;
+	return program.body?.length === 2 && importDeclaration?.type === "ImportDeclaration" && importDeclaration.source?.value === "void/config" && importDeclaration.specifiers?.length === 1 && importDeclaration.specifiers[0]?.imported?.name === "defineConfig" && importDeclaration.specifiers[0]?.local?.name === "defineConfig" && exportDeclaration?.type === "ExportDefaultDeclaration" && call?.type === "CallExpression" && call.callee?.name === "defineConfig" && call.arguments?.length === 1 && isStaticValue(call.arguments[0]);
+}
+function canRewriteVoidProjectConfig(root) {
+	const path = join(root, TYPED_CONFIG_FILE);
+	return !existsSync(path) || isGeneratedStaticConfig(readFileSync(path, "utf8"));
+}
+/** Update CLI-owned static config without silently rewriting authored TypeScript. */
+function writeVoidProjectConfig(root, config) {
+	validateConfig(config, TYPED_CONFIG_FILE);
+	const path = join(root, TYPED_CONFIG_FILE);
+	if (existsSync(path)) {
+		if (!isGeneratedStaticConfig(readFileSync(path, "utf8"))) throw new Error(`config: ${TYPED_CONFIG_FILE} contains authored TypeScript or comments. Update it directly and rerun the command.`);
+		validateConfig(loadTypedVoidConfigFile(path), TYPED_CONFIG_FILE);
+	}
+	writeFileSync(path, renderVoidConfig(config, "// Generated by void init."));
+}
+//#endregion
 //#region src/cli/wrangler.ts
 const COMPAT_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 /** UTF-8 byte-order mark. Node's utf-8 read preserves a leading one. */
@@ -170,10 +226,15 @@ function resolveGeneratedName(base, used, kind) {
 function readWranglerCompat(root, config, buildOutputDir) {
 	return resolveWranglerCompat(readWranglerCompatFields(root, config, buildOutputDir));
 }
-/** Like `readWranglerCompat()`, but pins the default date when no source sets one. */
-function ensureWranglerCompat(root, config, buildOutputDir) {
+/**
+* Like `readWranglerCompat()`, but pins the default date when no source sets one.
+* With `rootWrangler`, a project with no config gets the date in a root wrangler.jsonc
+* instead of a new void.config.ts, so a framework adapter that reads the root file by
+* default still finds it.
+*/
+function ensureWranglerCompat(root, config, buildOutputDir, options) {
 	const fields = readWranglerCompatFields(root, config, buildOutputDir);
-	const defaultDate = fields.voidDate ?? fields.wranglerDate ?? fields.buildDate ? void 0 : ensureVoidCompatibilityDate(root, fields.voidConfig);
+	const defaultDate = fields.voidDate ?? fields.wranglerDate ?? fields.buildDate ? void 0 : ensureVoidCompatibilityDate(root, options?.rootWrangler === true);
 	return resolveWranglerCompat(fields, defaultDate ? { defaultDate } : void 0);
 }
 function readWranglerCompatFields(root, config, buildOutputDir) {
@@ -205,7 +266,6 @@ function readWranglerCompatFields(root, config, buildOutputDir) {
 		if (Array.isArray(buildParsed.compatibility_flags) && buildParsed.compatibility_flags.every((f) => typeof f === "string")) buildFlags = buildParsed.compatibility_flags;
 	} catch {}
 	return {
-		voidConfig,
 		voidDate: voidConfig?.worker?.compatibility_date,
 		voidFlags: voidConfig?.worker?.compatibility_flags,
 		wranglerDate,
@@ -226,14 +286,23 @@ function validateCompatDate(value, source) {
 function readVoidConfigIfExists(root) {
 	return existsSync(join(root, VOID_CONFIG_FILE)) || existsSync(join(root, "void.config.ts")) ? readConfig(root) : void 0;
 }
-function ensureVoidCompatibilityDate(root, config) {
+function ensureVoidCompatibilityDate(root, rootWrangler) {
 	if (existsSync(join(root, "void.config.ts"))) {
 		writeProvisionedWranglerConfig(root, { compatibilityDate: LATEST_KNOWN_COMPAT_DATE });
 		return LATEST_KNOWN_COMPAT_DATE;
 	}
 	const filePath = join(root, VOID_CONFIG_FILE);
-	let nextConfig = {};
-	if (existsSync(filePath)) try {
+	if (!existsSync(filePath)) {
+		if (existsSync(join(root, "wrangler.toml"))) writeFileSync(filePath, `${JSON.stringify({ worker: { compatibility_date: LATEST_KNOWN_COMPAT_DATE } }, null, 2)}\n`);
+		else if (rootWrangler || projectWranglerPaths(root).some((path) => existsSync(path))) writeProvisionedWranglerConfig(root, { compatibilityDate: LATEST_KNOWN_COMPAT_DATE });
+		else {
+			writeVoidProjectConfig(root, { worker: { compatibility_date: LATEST_KNOWN_COMPAT_DATE } });
+			ignoreMaterializedCloudflareConfig(root);
+		}
+		return LATEST_KNOWN_COMPAT_DATE;
+	}
+	let nextConfig;
+	try {
 		const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
 		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error(`config: ${VOID_CONFIG_FILE} must be a JSON object.`);
 		nextConfig = parsed;
@@ -241,7 +310,6 @@ function ensureVoidCompatibilityDate(root, config) {
 		if (error instanceof SyntaxError) throw new Error(`config: Invalid JSON in ${VOID_CONFIG_FILE}.`);
 		throw error;
 	}
-	else if (config) nextConfig = { ...config };
 	nextConfig.worker = {
 		...nextConfig.worker ?? {},
 		compatibility_date: LATEST_KNOWN_COMPAT_DATE
@@ -666,9 +734,10 @@ function writeProvisionedWranglerConfig(root, patch, options) {
 				const matches = [];
 				for (let i = 0; i < currentList.length; i++) if (currentList[i].binding === entry.binding) matches.push(i);
 				if (matches.length > 1) throw new Error(`deploy: cannot update "${configPath}" — queue producer binding ${JSON.stringify(entry.binding)} is declared ${matches.length} times across producers. A producer binding must map to exactly one queue, so wrangler rejects this config. Remove the duplicate producers and retry.`);
+				const voidOwned = reconcileManagedQueues && managedProducerBindings.has(String(entry.binding));
 				if (matches.length === 1) {
 					const existing = currentList[matches[0]];
-					if (existing.queue !== entry.queue) throw new Error(`deploy: cannot update "${configPath}" — queue producer binding ${JSON.stringify(entry.binding)} is already bound to queue ${JSON.stringify(existing.queue)}, but queue ${JSON.stringify(entry.queue)} also requests it. A producer binding must map to exactly one queue. Rename or remove the conflicting producer and retry.`);
+					if (existing.queue !== entry.queue && !voidOwned) throw new Error(`deploy: cannot update "${configPath}" — queue producer binding ${JSON.stringify(entry.binding)} is already bound to queue ${JSON.stringify(existing.queue)}, but queue ${JSON.stringify(entry.queue)} also requests it. A producer binding must map to exactly one queue. Rename or remove the conflicting producer and retry.`);
 				}
 				index = matches.length === 1 ? matches[0] : -1;
 				workerBindingOwners ??= collectWorkerBindingNames(parseJsonc(text));
@@ -1399,4 +1468,4 @@ function normalizeMigrationsPath(p) {
 	return normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
 }
 //#endregion
-export { syncWranglerWebSockets as A, readWranglerManagedQueueCleanupCandidates as C, sameMigrationsDir as D, resolveLiveBindingConfig as E, writeProvisionedWranglerConfig as M, writeWranglerPublishedTrafficSnapshot as N, syncWranglerBindings as O, readWranglerCustomDomains as S, readWranglerWebSocketTombstones as T, persistMaterializedWranglerConfig as _, LIVE_MIGRATION_TAG as a, readRootWranglerConfig as b, bindingEntriesForField as c, ensureWranglerCompatibilityDate as d, ensureWranglerNodejsAlsFlag as f, normalizeWranglerCompatibilityFlags as g, nextDurableObjectMigrationTag as h, LATEST_KNOWN_COMPAT_DATE as i, updateWranglerCustomDomain as j, syncWranglerDurableObjects as k, bindingNamesForField as l, hasDurableObjectSqliteMigration as m, DEFAULT_LIVE_CLASS as n, acknowledgeWranglerManagedQueueRemovals as o, findBindingNameOwner as p, FRIENDLY_BINDING_NAMES as r, assertNoDuplicateMembers as s, DEFAULT_LIVE_BINDING as t, ensureWranglerCompat as u, readExistingLiveBindingConfig as v, readWranglerPublishedTrafficSnapshot as w, readWranglerCompat as x, readProvisionedBindingEntry as y };
+export { syncWranglerWebSockets as A, readWranglerManagedQueueCleanupCandidates as C, sameMigrationsDir as D, resolveLiveBindingConfig as E, canRewriteVoidProjectConfig as F, renderVoidConfig as I, writeVoidProjectConfig as L, writeProvisionedWranglerConfig as M, writeWranglerPublishedTrafficSnapshot as N, syncWranglerBindings as O, GENERATED_MARKERS as P, readWranglerCustomDomains as S, readWranglerWebSocketTombstones as T, persistMaterializedWranglerConfig as _, LIVE_MIGRATION_TAG as a, readRootWranglerConfig as b, bindingEntriesForField as c, ensureWranglerCompatibilityDate as d, ensureWranglerNodejsAlsFlag as f, normalizeWranglerCompatibilityFlags as g, nextDurableObjectMigrationTag as h, LATEST_KNOWN_COMPAT_DATE as i, updateWranglerCustomDomain as j, syncWranglerDurableObjects as k, bindingNamesForField as l, hasDurableObjectSqliteMigration as m, DEFAULT_LIVE_CLASS as n, acknowledgeWranglerManagedQueueRemovals as o, findBindingNameOwner as p, FRIENDLY_BINDING_NAMES as r, assertNoDuplicateMembers as s, DEFAULT_LIVE_BINDING as t, ensureWranglerCompat as u, readExistingLiveBindingConfig as v, readWranglerPublishedTrafficSnapshot as w, readWranglerCompat as x, readProvisionedBindingEntry as y };

package/dist/wrangler-UnwdISay.mjs

@@ -0,0 +1 @@
+export { b as readRootWranglerConfig } from "./wrangler-I-scB_1t.mjs";

package/dist/{wrapper-D3sZyh2C.mjs → wrapper-BBl1rC32.mjs}

@@ -1,13 +1,14 @@
 import { a as join, l as toSlash, n as dirname, r as extname } from "./dist-ipQi0Q8y.mjs";
 import { n as readProjectPaths } from "./project-paths-DGu_QZ_Q.mjs";
-import { l as getDatabaseDialect, p as readConfig } from "./config-DHgSEWT7.mjs";
+import { l as getDatabaseDialect, p as readConfig } from "./config-OFOAimzt.mjs";
 import { n as isIdentifier, r as isLiteral } from "./ast-CsZ_q_gc.mjs";
 import { t as MagicString } from "./dist-Cegxq8gs.mjs";
-import { r as voidDbBundlerPlugin, t as generateQueueResolverSource } from "./dispatch-DoUnxTNo.mjs";
+import { c as voidDbBundlerPlugin, r as cloudflareQueueName, t as generateQueueResolverSource } from "./dispatch-CLa2LThw.mjs";
+import { t as WORKER_CONDITIONS } from "./worker-conditions-AWFRcFxR.mjs";
 import { createRequire } from "node:module";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
 import { build, parseSync } from "vite";
+import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 //#region src/cli/worker-require-transform.ts
 function nodes(root) {
@@ -237,14 +238,6 @@ async function bundleMigrationHandler(root, workerDir, handlerPath, dialect) {
 	if (isPostgresql || isMysql) patchWorkerRequireBundle(outDir, isPostgresql ? "PostgreSQL" : "MySQL", "migration bundle");
 	for (const file of readdirSync(outDir)) copyFileSync(join(outDir, file), join(workerDir, file));
 }
-const WORKER_CONDITIONS = [
-	"workerd",
-	"worker",
-	"browser",
-	"module",
-	"import",
-	"default"
-];
 const SQL_WORKER_EXTERNAL = [
 	/^cloudflare:/,
 	/^node:/,
@@ -414,6 +407,7 @@ async function bundleEntry(root, entry) {
 	await build({
 		root: tmpDir,
 		logLevel: "silent",
+		resolve: { conditions: [...WORKER_CONDITIONS, "production"] },
 		build: {
 			outDir,
 			emptyOutDir: true,
@@ -608,7 +602,9 @@ function generateHandlersSource(root, features, dialect) {
 			lines.push(`import queueHandler${i} from "${absPath}";`);
 		}
 		lines.push("");
-		lines.push(generateQueueResolverSource(features.queues.map((queue) => queue.name)));
+		const queueNames = features.queues.map((queue) => queue.name);
+		const cloudflareNames = features.cloudflareQueueNames;
+		lines.push(generateQueueResolverSource(queueNames, cloudflareNames && queueNames.map((name) => cloudflareQueueName(name, cloudflareNames))));
 		lines.push("");
 		lines.push(scoped ? "async function __runQueue(batch, env, ctx) {" : "export async function handleQueue(batch, env, ctx) {");
 		lines.push("  const queueSuffix = batch.queue;");

package/dist/{ws-BH-im_tX.d.mts → ws-B3ClMVDh.d.mts}

@@ -1,6 +1,6 @@
 import { t as StandardSchemaV1 } from "./standard-schema-Fo_vCAZh.mjs";
-import { r as AuthUser } from "./auth-DkcFflXV.mjs";
-import { a as CloudEnv } from "./handler-BbkSPzGF.mjs";
+import { r as AuthUser } from "./auth-g2TQbDLD.mjs";
+import { a as CloudEnv } from "./handler-BHktmuTL.mjs";
 import { WebSocketRouteMap } from "void/routes";
 //#region src/runtime/ws.d.ts
 type MaybePromise<T> = T | Promise<T>;
@@ -125,6 +125,7 @@ declare class VoidSocket<P extends keyof WebSocketRouteMap & string> {
   private readonly buffer;
   private reconnectAttempts;
   private closedByUser;
+  private reconnectTimer;
   constructor(url: string, options: ConnectCommonOptions);
   private emit;
   private connect;

package/docs/guide/auth.md

@@ -119,7 +119,7 @@ import { getSession, getUser, requireAuth } from 'void/auth';
 - `getSession()` returns `{ user, session } | null`
 - `requireAuth(c)` returns the authenticated user or throws `401`
 
-Import `AuthUser` and `AuthSession` from `void/auth` for type annotations. See their fields in the [API reference](../reference/api/auth.md#authuser).
+Import `AuthUser` and `AuthSession` from `void/auth` for type annotations. They include the fields your Better Auth plugins and `user.additionalFields` add, such as `role` from `admin()`. See their fields in the [API reference](../reference/api/auth.md#authuser).
 
 ## Behavior
 
@@ -129,6 +129,8 @@ Local development needs no secret setup. To preview a production build locally,
 
 Responses to signed-in requests get `Cache-Control: no-store`, so neither the browser cache nor a shared cache keeps a user's data. A route keeps its own policy when it sets `no-store`, or `private` together with `no-cache`. To answer repeat requests with `304`, use `private, no-cache` with Hono's [`etag()`](https://hono.dev/docs/middleware/builtin/etag) middleware. If you set the `ETag` yourself, make it differ per user, so the `304` doesn't reuse another account's page. The browser cache keeps a copy of a `private, no-cache` page, so the Back button can show it again after the user signs out. Keep the default `no-store` for pages that must not stay in the browser cache.
 
+Static files from your build and `public/` keep their own cache policy for signed-in requests, so the browser reuses cached JavaScript and CSS. When your app handles the request, the policy is marked `private`, and a request that refreshes the session cookie gets `no-store`.
+
 `POST`, `PUT`, `PATCH` and `DELETE` requests and WebSocket connections from another origin don't use the signed-in session unless that origin is in `trustedOrigins`. If a separate frontend calls your app, add its origin there (see [Customization](#customization)). If your routes use their own cookies, check the request `Origin` yourself, for example with Hono's [`csrf()`](https://hono.dev/docs/middleware/builtin/csrf) middleware.
 
 Deployed apps on Cloudflare limit auth requests per client IP with Better Auth's defaults, for example 3 sign-in attempts per 10 seconds. Each Worker instance keeps its own count. Change or turn off the limits with `rateLimit` in `auth.ts`. To share one count across instances, set `rateLimit: { storage: 'database' }`, then run `void db generate` for a direct Cloudflare deploy.
@@ -184,7 +186,7 @@ For the full set of available options, see the official [Better Auth options ref
 
 ## Database and Migrations
 
-Auth tables live alongside your app's tables. During local development, Void creates them automatically.
+Auth tables live alongside your app's tables. During local development, Void creates them automatically. While the dev server runs, saving `auth.ts`, or a local file it imports, updates the auth schema Void generates for your app. New auth tables and columns are created in the local database the next time the dev server starts.
 
 Void platforms create auth tables automatically. For a direct Cloudflare deploy, include them in your checked-in migrations:
 

package/docs/guide/edge/redirects.md

@@ -51,6 +51,28 @@ Path-only sources apply to every domain on the project. Host-prefixed sources ap
 
 The source must use `https://` and a literal hostname without wildcards or a port. Add the domain to your project with `void domain add` before deploying the rule. A domain awaiting certificate verification starts redirecting once it becomes active.
 
+## HTTP to HTTPS
+
+Set `routing.alwaysUseHttps` to redirect HTTP requests to HTTPS:
+
+```ts
+import { defineConfig } from 'void/config';
+
+export default defineConfig({
+  routing: {
+    alwaysUseHttps: true,
+  },
+});
+```
+
+Void answers with a permanent `308` redirect to the same URL over HTTPS. The path, query string, and request method stay the same. Omitted or `false` means off. `localhost` and loopback addresses such as `127.0.0.1` stay on HTTP, so local development and `vite preview` are unchanged.
+
+It works on the Void platform and for Void apps on `void deploy --platform cloudflare`. It needs the Cloudflare target: setting it with `target: 'node'`, `'bun'`, or `'deno'` is a config error.
+
+On `void deploy --platform cloudflare`, built files with a content hash in their name, such as `/assets/index-abc123.js`, can be served by Cloudflare before Void runs, so they may still answer over HTTP. Pages always redirect, so browsers load these files over HTTPS. To redirect every request, also turn on [Always Use HTTPS](https://developers.cloudflare.com/ssl/edge-certificates/additional-options/always-use-https/) for your Cloudflare zone.
+
+SvelteKit, Nuxt, Astro, Analog, TanStack Start, React Router, and vinext apps run their own Worker, so `void deploy --platform cloudflare` stops with an error when the option is on. Static builds of these frameworks, deployed with `--dir` or `inference.appType`, redirect as usual. For the others, redirect to HTTPS in the framework, or turn on [Always Use HTTPS](https://developers.cloudflare.com/ssl/edge-certificates/additional-options/always-use-https/) for your Cloudflare zone.
+
 ## Framework `_redirects` files
 
 Void reads `_redirects` files produced by supported frameworks. You can also place one in Vite's `publicDir`:

package/docs/guide/edge/static-assets.md

@@ -37,6 +37,16 @@ With `void deploy --platform cloudflare`, generated JavaScript bundles with cont
 
 Use [Custom Headers](./headers) to choose a cache policy for other files. Apply immutable caching only to URLs that change whenever their content changes.
 
+Cloudflare serves these fingerprinted JavaScript bundles without starting your Worker, so they do not count as Worker requests, when your app:
+
+- has no global middleware
+- has no header, redirect, rewrite or fallback rules, and no `routing.notFound` setting
+- uses the default `base` of `/`
+- has no route or page that matches paths in the assets directory (`assets/` by default)
+- builds at most 99 fingerprinted bundles
+
+Otherwise these bundles go through your Worker and keep the same caching.
+
 ## Non-hashed assets
 
 Other static files, such as `index.html` and `favicon.ico`, are cached until the next deploy. You do not need to purge them manually.

package/docs/guide/email/domains.md

@@ -16,7 +16,7 @@ void email domain add acme.com
 
 `add` opens a Cloudflare API-token template. Restrict the token to the selected account and mail zone before creating it; Workers Scripts permission applies across that account. The CLI accepts a masked paste or a newly copied token and asks you to confirm those restrictions. The platform encrypts the credential for the zone connection, so projects sharing that zone do not need separate ingress Workers.
 
-Platform-managed custom inbound email requires the apex of a Cloudflare zone. Cloudflare’s catch-all only covers that apex, so a subdomain of the selected zone cannot receive arbitrary addresses. `add` refuses to register a new apex that already has MX records, or whose catch-all already routes elsewhere, so it never takes over mail hosted with another provider such as Microsoft 365 or Google Workspace. Use an apex that has no mail yet, or the platform’s shared mail address. Running `add` again for a registered apex, for example to renew its token, keeps working. Each custom apex belongs to one project; a project can register more than one apex.
+Platform-managed custom inbound email requires the apex of a Cloudflare zone. Cloudflare’s catch-all only covers that apex, so a subdomain of the selected zone cannot receive arbitrary addresses. `add` refuses to register a new apex that already has MX records, or whose catch-all already routes elsewhere, so it never takes over mail hosted with another provider such as Microsoft 365 or Google Workspace. Use an apex that has no mail yet, or the platform’s shared mail address. To only send from an apex that keeps its current mail provider, ask your platform administrator to register it as [outbound-only](../platform/administration/email.md#sending-from-a-domain-that-already-receives-mail). Running `add` again for a registered apex, for example to renew its token, keeps working. Each custom apex belongs to one project; a project can register more than one apex.
 
 If setup is interrupted, use `void email domain status <domain>` to inspect the saved operation before retrying.
 

package/docs/guide/email/receiving.md

@@ -94,6 +94,8 @@ deployed `email/` handlers without per-project DNS setup once the platform has v
 handlers once its inbound readiness is `ready`. Use `void email domain status`
 to check current provider routing and any remaining setup steps.
 
+A project with an [email alias](../../reference/cli/email.md#void-email-alias) also receives at `<alias>+anything@<mail domain>`. Routing ignores which prefix was used: with the slug `acme-store` and the alias `acme`, both `acme-store+support@…` and `acme+support@…` reach `email/support.ts`.
+
 For direct deployments, follow [Your own Cloudflare account](./domains.md#your-own-cloudflare-account) to configure inbound addresses.
 
 The local dev server provides the outbound email inbox but has no inbound email trigger. Test inbound handlers with `createInboundTestHarness` below.

package/docs/guide/email/sending.md

@@ -84,7 +84,7 @@ You can send to at most 50 recipients across `to`, `cc`, and `bcc`. Use standard
 
 `Address` accepts either a string (`"hello@acme.dev"` or `"Name <hello@acme.dev>"`) or an object (`{ email, name? }`). Unicode display names are supported.
 
-On the platform the sender is pinned to your project. `from` must be your project's own platform address — `<project-slug>@<mail-domain>` or `<project-slug>+<tag>@<mail-domain>`, optionally with a display name — or any address on a domain registered with `void email domain add` (see [Your own domain on the platform](./domains.md#your-own-domain-on-the-platform)). For example, if your platform's mail domain is `mail.example.com`, you can use `Acme <acme+noreply@mail.example.com>`. Anything else is rejected with `INVALID_FROM`. Omit `from` and Void fills in `<project-slug>+noreply@<mail-domain>` for you.
+On the platform the sender is pinned to your project. `from` must be your project's own platform address — `<project-slug>@<mail-domain>` or `<project-slug>+<tag>@<mail-domain>`, optionally with a display name — or any address on a domain registered with `void email domain add` (see [Your own domain on the platform](./domains.md#your-own-domain-on-the-platform)). For example, if your platform's mail domain is `mail.example.com`, you can use `Acme <acme+noreply@mail.example.com>`. Anything else is rejected with `INVALID_FROM`. Omit `from` and Void fills in `<project-slug>+noreply@<mail-domain>` for you. If the project owner set an [email alias](../../reference/cli/email.md#void-email-alias), `<alias>@<mail-domain>` and `<alias>+<tag>@<mail-domain>` are accepted too; the default stays the slug address.
 
 On your own Cloudflare account, `from` defaults to `email.from` from `void.config.ts` and must be on a domain your account can send from; Cloudflare rejects any other sender and `sendEmail` reports it as `INVALID_FROM`.
 

package/docs/guide/pages-routing/actions-and-forms.md

@@ -147,19 +147,23 @@ The types are inferred from your action's `withValidator()` schema in the compan
 
 `useForm` returns a reactive object with:
 
-| Property / Method                | Purpose                                                                            |
-| -------------------------------- | ---------------------------------------------------------------------------------- |
-| `data` / `setData`               | Current form values, typed to match the action's body schema.                      |
-| `errors`                         | Field-level validation errors, keys typed to body field names.                     |
-| `error`                          | Action error, or `null`.                                                           |
-| `post`, `put`, `patch`, `delete` | Submit the form with that method. In React these are native form action callbacks. |
-| `pending`                        | `true` while the submission is in flight.                                          |
-| `hasChanges`                     | `true` if form data differs from initial values.                                   |
-| `wasSuccessful`                  | `true` after a successful submission. Stays `true` until the next submission.      |
-| `recentlySuccessful`             | `true` for 2 seconds after a successful submission. Useful for flash messages.     |
-| `reset(...fields)`               | Reset form data to initial values. Field names autocomplete.                       |
-| `clearErrors(...fields)`         | Clear validation errors. Field names autocomplete.                                 |
-| `clearError()`                   | Clear `error`.                                                                     |
+| Property / Method                | Purpose                                                                                                                                                                             |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data` / `setData`               | Current form values, typed to match the action's body schema.                                                                                                                       |
+| `errors`                         | Field-level validation errors, keys typed to body field names.                                                                                                                      |
+| `error`                          | Action error, or `null`.                                                                                                                                                            |
+| `post`, `put`, `patch`, `delete` | Submit the form with that method. In React these are native form action callbacks.                                                                                                  |
+| `pending`                        | `true` while the submission is in flight.                                                                                                                                           |
+| `hasChanges`                     | `true` if form data differs from the current defaults. After a successful submit, defaults update to the submitted values so `hasChanges` becomes `false`.                          |
+| `wasSuccessful`                  | `true` after a successful submission. Stays `true` until the next submission.                                                                                                       |
+| `recentlySuccessful`             | `true` for 2 seconds after a successful submission. Useful for flash messages.                                                                                                      |
+| `reset(...fields)`               | Reset form data to the current defaults (last submitted values after success). Field names autocomplete. Pass `{ initial: true }` first to reset to the values passed to `useForm`. |
+| `resetOnSuccess` (option)        | When `true`, a successful submit resets both form data and defaults to the mount-time values. Useful for create forms that should clear after save.                                 |
+| `setError(field, message)`       | Set a client-side validation error on a field.                                                                                                                                      |
+| `clearErrors(...fields)`         | Clear validation errors. Field names autocomplete.                                                                                                                                  |
+| `clearError()`                   | Clear `error`.                                                                                                                                                                      |
+
+Use `setError()` to display errors from your own client-side validation. Setting an error preserves errors on other fields. Changing a field clears that field's validation error automatically (`setData` in React and Solid, or assigning to `data` in Vue and Svelte).
 
 For a native React form, use `form.post`, `form.put`, `form.patch`, or `form.delete` as a native form action. For an awaitable mutation, use `action()`. In Vue, Svelte, and Solid, form submissions return `Promise<void>`; catch thrown errors or use your framework's error handling.
 
@@ -171,6 +175,32 @@ const form = useForm('/users/:id', { name: '' }, { params: { id: '42' } });
 <Form form={form} method="put">{/* submits to /users/42 */}</Form>
 ```
 
+Create forms often need empty fields again after a successful save. Either pass `resetOnSuccess: true` in the third argument, or call `form.reset({ initial: true })` when `form.wasSuccessful` becomes `true`.
+
+### React submission callbacks
+
+In React, pass `onSuccess` and `onError` to `useForm()` to respond to a submission:
+
+```tsx
+const form = useForm(
+  '/users',
+  { name: '', email: '' },
+  {
+    onSuccess: () => setDialogOpen(false),
+    onError: (error) => {
+      // A field-error map or VoidActionError for a handled action failure.
+      console.error(error);
+    },
+  },
+);
+```
+
+Each submission uses the callbacks from when it was dispatched. Callbacks run inside the React Action, before the updated UI commits. Use an effect or ref callback to focus an element that appears after submission.
+
+Callbacks can return `Promise<void>`. The Action awaits them, and `form.pending` stays true until they complete. Errors thrown or rejected by callbacks reach the nearest React error boundary. Aborted submissions invoke neither callback.
+
+Vue, Svelte, and Solid submissions return a promise instead; use `await form.post()` to run work after a submission.
+
 ## Named Actions
 
 When a page needs multiple mutations, such as updating and deleting a user on the same page, export `actions` (plural) instead of `action`:

package/docs/guide/pages-routing/markdown.md

@@ -241,6 +241,8 @@ import pages from '@void/md/pages';
 // [{ path: "/docs/getting-started", title: "Getting Started", frontmatter: {...}, headings: [...] }, ...]
 ```
 
+The list holds only the pages for the current [environment](./overview.md#environment-only-pages): `.dev` pages on the dev server, `.prod` pages in builds. The suffix is dropped from `path`: `debug.dev.md` is listed as `/debug`.
+
 Each entry has this shape:
 
 ```ts

package/docs/guide/pages-routing/overview.md

@@ -94,13 +94,44 @@ Pages can be flat files such as `about.vue` or directory-based routes such as `a
 
 <PagesFileTree />
 
-Each page can have a companion `.server.ts` file that runs exclusively on the server. It can export:
+Keep one file per route. Void reports an error when two page files resolve to the same path, such as `about.vue` and `about/index.vue`, or the same page in two route groups.
+
+Each page can have a companion `.server.ts`, `.server.tsx`, `.server.js`, `.server.jsx`, `.server.mts`, or `.server.mjs` file that runs exclusively on the server. Use `.server.tsx` or `.server.jsx` when the companion contains JSX (see [JSX handlers](../server-routing.md#jsx-handlers) for the JSX runtime). A companion belongs to its matching page and does not create a separate route:
+
+| File                   | Role                           |
+| ---------------------- | ------------------------------ |
+| `pages/foo.tsx`        | Page component at `/foo`       |
+| `pages/foo.server.tsx` | Server companion for that page |
+
+A companion can export:
 
 - A [**loader**](./loaders), which runs on `GET` and returns the data that becomes the page component's props
 - [**Actions**](./actions-and-forms), which handle mutations from forms and programmatic calls. Export a single `action` or multiple [named actions](./actions-and-forms#named-actions) when a page has several mutations
 - `ssr = false` to opt a route out of server-rendered component HTML while keeping server loaders and client-side routing
 
-File-based routing rules are the same as [server routing](../server-routing.md): `[param]` for dynamic segments, `[...param]` for catch-all, `(group)/` for route groups.
+File-based routing rules are the same as [server routing](../server-routing.md): `[param]` for dynamic segments, `[...param]` for catch-all, `(group)/` for route groups, and a `.dev` or `.prod` suffix for [environment-only pages](#environment-only-pages).
+
+### Environment-only pages
+
+Add a `.dev` or `.prod` suffix before the extension to include a page in only one environment. The suffix is not part of the URL:
+
+```
+pages/
+  about.tsx       →  /about, always
+  debug.dev.tsx   →  /debug, development only
+  stats.prod.tsx  →  /stats, production only
+  home.dev.tsx    →  /home in development
+  home.prod.tsx   →  /home in production
+```
+
+`.dev` pages run only on the dev server; `.prod` pages run in builds, deployments, and production previews.
+
+- A `.dev` page and a `.prod` page can share a URL. A plain page and a suffixed page for the same URL is an error wherever both run: `home.tsx` with `home.dev.tsx` fails on the dev server, and `home.tsx` with `home.prod.tsx` fails the build.
+- The suffix goes **before** `.island`: `chart.dev.island.tsx` is a development-only island page. `chart.island.dev.tsx` is not an island page.
+- A companion repeats the suffix: `home.dev.server.ts` belongs to `home.dev.tsx`.
+- Suffixes apply to page files only. Layouts take no suffix.
+- A resource used only by `.dev` pages and their companions is not provisioned for production.
+- The dev server and builds generate types for their own environment. `void prepare` generates types for both.
 
 ## How Navigation Works
 

package/docs/guide/platform/administration/email.md

@@ -10,6 +10,8 @@ These commands apply to a platform that enables email. Every project can send fr
 
 Shared inbound mail uses one exact routing rule per receiving project and enables Cloudflare’s per-zone plus addressing. Creating a project or deploying an app that only sends mail consumes no inbound rule. Existing rules and the apex catch-all remain in place. Cloudflare normally allows [200 routing rules per domain](https://developers.cloudflare.com/email-service/platform/limits/); remove unused rules or request a higher limit if the shared domain reaches capacity. An unrelated rule for a project’s base address or a plus address blocks its setup until that conflict is removed.
 
+A project owner can give the shared address one permanent, shorter name with `void email alias <name>`. A receiving project with an alias uses two rules, one for the slug and one for the alias, because the slug address keeps working. Setting an alias is refused while a conflicting rule exists or the domain is at its rule limit, and the alias is released only when the project is deleted.
+
 If recipient creation is interrupted, inspect its retained intent:
 
 ```sh
@@ -150,3 +152,19 @@ Run recovery with the same platform version that created the persisted intent.
 `applied` continues without replaying the write; `not-applied` permits that exact
 step to retry. Secret rotation keeps its staged generation, and removal resumes
 from the unresolved cleanup step. Age alone never authorizes a retry.
+
+### Sending from a domain that already receives mail
+
+If an apex already receives mail with another provider, such as Microsoft 365 or Google Workspace, register it for sending only:
+
+```sh
+void platform email domain-add brand.example --project hr-portal --outbound-only
+```
+
+The project can then send from any address on the apex, such as `support@brand.example`. It cannot receive mail there: the MX records, the apex SPF record, and incoming mail stay with the current provider.
+
+- Cloudflare Email Sending must be available, which needs Workers Paid. Without it, setup is blocked instead of falling back to verified destinations only. Upgrade, then run `domain-sync`.
+- Email Sending adds its own records on `cf-bounce.<domain>` and `_dmarc.<domain>`. If Cloudflare reports that existing records conflict with them, for example several DMARC records, setup is blocked and the error lists each record. Fix them, then run `domain-sync`.
+- Only administrators can register an outbound-only domain, and it must be a zone apex. The platform's shared mail zone cannot be outbound-only.
+- `domain-rotate-secret` does not apply. `domain-remove` stops sending through the platform and leaves the MX records alone.
+- To switch an outbound-only domain to platform-managed inbound mail, or back, remove it first and add it again.

package/docs/guide/platform/installation/maintenance.md

@@ -100,7 +100,9 @@ Repair recreates missing infrastructure that the installer owns. It does not res
 
 ### Upgrade the platform
 
-Keep the platform runtime current when updating the Void CLI.
+Keep the platform runtime current when updating the Void CLI. Upgrade the platform before your team updates its CLI: a newer CLI refuses to work with an older platform and asks for `void platform upgrade`. Install the new CLI on the administrator's machine, run the upgrade below, then have the team update.
+
+If the platform will deploy apps that use `void/sandbox`, its runtime token needs **Account → Containers → Edit** and **Account → Cloudchamber → Edit**. A token made from an older setup link may lack them, and an upgrade does not add them. Edit the token in the Cloudflare dashboard, or set `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN` to a new token when you upgrade. See [Cloudflare API Tokens](/guide/platform/installation/credentials#runtime-token-permissions).
 
 Use the installed CLI's packaged runtime to upgrade:
 

package/docs/guide/platform/installation/prerequisites.md

@@ -13,16 +13,17 @@ To run a Void platform, you need:
 
 Void creates the Workers, storage, queues, routing, and database tables through the CLI.
 
-Workers for Platforms requires a paid plan. Your database and Cloudflare usage are billed separately.
+Workers for Platforms requires its own paid plan. Analytics Engine is available on Workers Free, but you must enable it for the account. Review [Analytics Engine pricing and allowances](https://developers.cloudflare.com/analytics/analytics-engine/pricing/). Your database and Cloudflare usage are billed separately.
 
 ## Prepare Your Cloudflare Account and Domain
 
 In the [Cloudflare dashboard](https://dash.cloudflare.com/), select the account where you want the platform to live:
 
 1. Open **Workers & Pages** once to let Cloudflare provision Workers for the account.
-2. Open **Workers for Platforms** and enable its plan. Review [Workers for Platforms pricing](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/platform/pricing/) before confirming.
+2. Open **Workers for Platforms** and enable its plan. Review [Workers for Platforms pricing](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/reference/pricing/) before confirming.
 3. Open **R2 Object Storage** and complete its activation. Void creates the bucket later.
-4. For a domain installation, choose a domain you own, such as `example.app`. If you need one, register it with your preferred registrar. Use a spare domain's root: apps will be served at `my-app.example.app`. For workers.dev testing, skip this step and the DNS setup below.
+4. Open **Analytics Engine** and select **Enable** if prompted. You do not need to create a dataset manually. If the page has no **Enable** action and installation reports code 10089, follow the [steps below](#if-cloudflare-rejects-analytics-engine).
+5. For a domain installation, choose a domain you own, such as `example.app`. If you need one, register it with your preferred registrar. Use a spare domain's root: apps will be served at `my-app.example.app`. For workers.dev testing, skip this step and the DNS setup below.
 
 If that domain is already in this Cloudflare account, use its existing zone. Otherwise, [add the domain to Cloudflare](https://developers.cloudflare.com/dns/zone-setups/full-setup/setup/) and follow the nameserver instructions until the zone is active. A zone is Cloudflare's DNS configuration for a domain; creating one does not buy the domain.
 
@@ -30,7 +31,9 @@ You can also let Void create the zone during installation. Setting it up now let
 
 ### If Cloudflare rejects Analytics Engine
 
-The platform stores request metrics and logs in Analytics Engine. If installation stops with "You need to enable Analytics Engine" (code 10089), add an Analytics Engine binding to a Worker that is not part of the platform under **Settings** > **Bindings**, and deploy it once from the dashboard. A new Hello World Worker works. Do not edit the platform's own Workers. Then run the printed `void platform install --resume` command.
+The platform stores request metrics and logs in Analytics Engine. If installation stops with "You need to enable Analytics Engine" (code 10089), open the Analytics Engine dashboard link in the error and select **Enable** for that account. Activation is available on Workers Free; this error does not require a Workers plan upgrade or a replacement API token. Then run the printed `void platform install --resume` command.
+
+If your account's dashboard has no **Enable** action, create a disposable Hello World Worker, add an Analytics Engine binding under **Settings** > **Bindings**, and deploy it once from the dashboard. Then resume installation. Use a separate Worker for this step; leave the platform's own Workers unchanged.
 
 ## Install the CLI and Preview
 
@@ -82,6 +85,8 @@ Use any PostgreSQL provider that accepts connections from your computer and Clou
 | [PlanetScale Postgres](https://planetscale.com/docs/postgres/connecting) | Choose **Postgres**, not Vitess/MySQL. Open **Connect**, create role credentials, and use the direct primary connection on port `5432`, not PgBouncer on `6432`. |
 | [Neon](https://neon.com/docs/get-started-with-neon/connect-neon)         | Open **Connect**, select the database and owner role, and turn **connection pooling off**.                                                                       |
 
+When sizing your database, include the connection pools for every platform installation and application sharing that server. Adjust each Hyperdrive's [origin connection limit](https://developers.cloudflare.com/hyperdrive/configuration/tune-connection-pool/) to fit the server's capacity, leaving room for migrations, administration, provider-reserved connections, and temporary bursts.
+
 Once installation claims the database, continue using that same database for resume and maintenance commands. If installation stops because it cannot use the database, for example because the database is not empty, set `VOID_PLATFORM_DATABASE_URL` to another database's URL before you resume. Uninstall never deletes external PostgreSQL.
 
 ### Use a provider CLI

package/docs/guide/platform/installation/uninstall.md

@@ -91,6 +91,8 @@ If installation configured Cloudflare Access, the uninstall plan lists its recor
 
 Uninstall does not remove the applications created for [project Zero Trust](/guide/platform/administration/zero-trust). While Zero Trust is enabled or still has Access applications, uninstall and `--plan` stop before any change and list those applications. Run `void platform zero-trust disable` first. Uninstall reads this from the installation database, so it also stops when the database cannot be reached.
 
+If the installation database is permanently gone and cannot be restored, there is no uninstall command that can clear the local installation record or list its Cloudflare resources. Once you have decided not to recover that installation, delete `~/.void/platforms/<account-id>/<installation-id>.json` and any sibling `<installation-id>.recovery.enc` or `<installation-id>.secrets.enc` files. This removes only local state and encrypted credentials; it does not delete Cloudflare resources. Review and remove those resources manually using [Remove retained resources](#remove-retained-resources).
+
 If no platform user exists yet, for example because first administrator setup did
 not finish, nobody can run `zero-trust disable`. Uninstall then turns off project
 Zero Trust and deletes its applications itself. Run it on the computer that installed

package/docs/guide/queues.md

@@ -10,7 +10,7 @@ Use queues to process work asynchronously, such as sending emails or handling up
 
 Create a consumer in `queues/`. TypeScript and JavaScript files are supported (`.ts`, `.mts`, `.js`, `.mjs`). Its path determines the queue name: `queues/emails.ts` creates `emails`, and `queues/order/notifications.ts` creates `order-notifications`. Each queue must have a unique name.
 
-The resulting name must follow Cloudflare's queue naming rules: 1–63 characters, only letters, digits, and `-`, beginning and ending with a letter or digit.
+The resulting name must follow Cloudflare's queue naming rules: 1–63 characters, only letters, digits, and `-`, beginning and ending with a letter or digit. On `void deploy --platform cloudflare`, the Cloudflare queue also carries the Worker name, so the limit applies to that full name; see [Cloudflare queue names](#cloudflare-queue-names).
 
 Export a default handler wrapped with [`defineQueue<T>`](../reference/api/handlers.md#definequeue-t-handler). `T` defines the message body for both the consumer and calls to `send()`:
 
@@ -116,6 +116,18 @@ deletes messages that exhaust their retries without one; see
 
 Void provisions queues and connects their producers and consumers when you deploy.
 
+### Cloudflare queue names
+
+Queue names are unique per Cloudflare account. So `void deploy --platform cloudflare` names each queue after the Worker: in a Worker named `app-staging`, `queues/jobs.ts` uses the Cloudflare queue `app-staging-jobs` (a `_` in the Worker name becomes `-`). Two Workers in one account, such as `app-staging` and `app-production`, get separate queues. Your code keeps using the name from `queues/` (`queues.jobs.send()`), and `vp dev` uses that name too.
+
+The deploy stops before creating anything when:
+
+- a new queue's full name is longer than 63 characters. Shorten the Worker name or the file name.
+- one queue's full name is the name of another file in `queues/`, such as `queues/jobs.ts` and `queues/app-jobs.ts` in Worker `app`. Rename one of the files.
+- another Worker already consumes the Cloudflare queue the deploy would use. A Cloudflare queue has one consumer.
+
+A queue that the Worker already consumes keeps its name, so an app deployed before Worker-named queues keeps its queue (for example `jobs`) and the messages in it. The deploy prints a note when it keeps a name. To move to the Worker-named queue, remove the Worker's consumer from the old queue in the Cloudflare dashboard, then deploy again. Messages that reach the old queue before that deploy finishes stay there, so do this when the app is not sending messages, and check that the old queue is empty before you delete it.
+
 ## Local development
 
 In native Void apps, sending a message through a queue binding automatically invokes the consumer in Miniflare. Local delivery uses the same handler as production.