void 0.22.0 → 0.23.0

package/dist/{wrangler-DQF1vKyf.mjs → wrangler-7K-bW_DL.mjs}

@@ -1,243 +1,12 @@
-import { a as join, i as isAbsolute, n as dirname, o as normalize, t as basename } from "./dist-BVqXeR_h.mjs";
+import { a as join, n as dirname, o as normalize, t as basename } from "./dist-BVqXeR_h.mjs";
 import "./project-paths-GgcMozYz.mjs";
 import { m as readConfig } from "./config-Br_JZD6u.mjs";
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { appendSqliteClassMigration, isSandboxRegistryImage } from "@void/deploy-core";
-import { createHash, randomUUID } from "node:crypto";
+import { a as hasSandboxSqliteMigration, c as resolveSandboxConfig, i as assertSandboxNamespaceConfig, l as sandboxContainerConfig, r as SANDBOX_MIGRATION_TAG } from "./config-C_XRIPx2.mjs";
+import { i as persistCloudflareConfig, r as materializeCloudflareConfig } from "./cloudflare-config-Bktvwtpf.mjs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { appendSqliteClassMigration } from "@void/deploy-core";
+import { createHash } from "node:crypto";
 import { SyntaxKind, applyEdits, createScanner, findNodeAtLocation, modify, parse, parseTree } from "jsonc-parser";
-import { isDeepStrictEqual } from "node:util";
-//#region src/cloudflare-config.ts
-const MATERIALIZED_CLOUDFLARE_FILE = ".void-wrangler.jsonc";
-const VOID_LOCK_FILE = "void.lock.json";
-const PREVIEW_POINTER_FILE = "preview-deploy-config.json";
-function isObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function arrayIdentity(value) {
-	if (isObject(value)) {
-		for (const key of [
-			"binding",
-			"name",
-			"tag",
-			"class_name",
-			"pattern",
-			"route"
-		]) if (typeof value[key] === "string") return `${key}:${value[key]}`;
-	}
-	return JSON.stringify(value) ?? String(value);
-}
-/** Keep authored values authoritative while retaining fields produced by Void. */
-function mergeConfig(previous, resolved, authored) {
-	if (isDeepStrictEqual(previous, authored)) return resolved;
-	if (Array.isArray(previous) && Array.isArray(resolved) && Array.isArray(authored)) {
-		const previousByIdentity = new Map(previous.map((item) => [arrayIdentity(item), item]));
-		const resolvedByIdentity = new Map(resolved.map((item) => [arrayIdentity(item), item]));
-		const authoredIdentities = new Set(authored.map(arrayIdentity));
-		return [...authored.map((item) => {
-			const identity = arrayIdentity(item);
-			return previousByIdentity.has(identity) && resolvedByIdentity.has(identity) ? mergeConfig(previousByIdentity.get(identity), resolvedByIdentity.get(identity), item) : item;
-		}), ...resolved.filter((item) => {
-			const identity = arrayIdentity(item);
-			return !previousByIdentity.has(identity) && !authoredIdentities.has(identity);
-		})];
-	}
-	if (isObject(previous) && isObject(resolved) && isObject(authored)) {
-		const result = {};
-		for (const key of /* @__PURE__ */ new Set([
-			...Object.keys(previous),
-			...Object.keys(resolved),
-			...Object.keys(authored)
-		])) {
-			if (!(key in authored)) {
-				if (!(key in previous) && key in resolved) Object.defineProperty(result, key, {
-					value: resolved[key],
-					enumerable: true,
-					writable: true,
-					configurable: true
-				});
-				continue;
-			}
-			const value = mergeConfig(previous[key], resolved[key], authored[key]);
-			Object.defineProperty(result, key, {
-				value,
-				enumerable: true,
-				writable: true,
-				configurable: true
-			});
-		}
-		return result;
-	}
-	return authored;
-}
-function parseCloudflareText(text, path) {
-	const errors = [];
-	const value = parse(text.replace(/^\uFEFF/, ""), errors, { allowTrailingComma: true });
-	if (errors.length > 0 || !isObject(value)) throw new Error(`config: ${path} must contain a valid JSON/JSONC object.`);
-	return value;
-}
-function readState(root) {
-	const path = join(root, VOID_LOCK_FILE);
-	if (!existsSync(path)) return;
-	let value;
-	try {
-		value = JSON.parse(readFileSync(path, "utf8"));
-	} catch {
-		throw new Error(`config: Invalid ${VOID_LOCK_FILE}. Fix or restore it before continuing.`);
-	}
-	if (!isObject(value) || value.version !== 1 || !isObject(value.source) || !isObject(value.resolved) || typeof value.text !== "string") throw new Error(`config: Invalid ${VOID_LOCK_FILE}. Fix or restore it before continuing.`);
-	const state = value;
-	if (!isDeepStrictEqual(parseCloudflareText(state.text, "void.lock.json"), state.resolved)) state.text = `${provenance(state.text)}${JSON.stringify(state.resolved, null, 2)}\n`;
-	return state;
-}
-function writeAtomic(path, content) {
-	const temporary = `${path}.${randomUUID()}.tmp`;
-	writeFileSync(temporary, content, { flag: "wx" });
-	try {
-		renameSync(temporary, path);
-	} finally {
-		rmSync(temporary, { force: true });
-	}
-}
-function writeState(root, state) {
-	const path = join(root, VOID_LOCK_FILE);
-	const content = `${JSON.stringify(state, null, 2)}\n`;
-	if (existsSync(path)) try {
-		if (isDeepStrictEqual(JSON.parse(readFileSync(path, "utf8")), state)) return;
-	} catch {}
-	writeAtomic(path, content);
-}
-/** Keep Vite preview usable without leaving Wrangler's implicit deploy pointer after a build. */
-function stashCloudflareDeployPointer(root) {
-	const pointer = join(root, ".wrangler", "deploy", "config.json");
-	if (!existsSync(pointer)) return;
-	const directory = join(root, ".void");
-	mkdirSync(directory, { recursive: true });
-	writeAtomic(join(directory, PREVIEW_POINTER_FILE), readFileSync(pointer, "utf8"));
-	rmSync(pointer, { force: true });
-}
-function restoreCloudflarePreviewPointer(root) {
-	const saved = join(root, ".void", PREVIEW_POINTER_FILE);
-	if (!existsSync(saved)) return false;
-	const directory = join(root, ".wrangler", "deploy");
-	mkdirSync(directory, { recursive: true });
-	writeAtomic(join(directory, "config.json"), readFileSync(saved, "utf8"));
-	return true;
-}
-/** Preserve Void's JSONC provenance comments when authored settings change. */
-function provenance(text) {
-	const lines = text.match(/^\s*\/\/ void:(?:managed-queues|published-traffic):v1:[A-Za-z0-9_-]+\s*$/gm);
-	return lines ? `${lines.join("\n")}\n` : "";
-}
-/** Resolve the config file passed to Cloudflare tooling. Typed projects use a generated file. */
-function materializeCloudflareConfig(root) {
-	if (!existsSync(join(root, "void.config.ts"))) {
-		for (const name of ["wrangler.jsonc", "wrangler.json"]) if (existsSync(join(root, name))) return join(root, name);
-		return join(root, "wrangler.jsonc");
-	}
-	if (["wrangler.jsonc", "wrangler.json"].some((name) => existsSync(join(root, name)))) throw new Error("config: Run `void migrate` to move the root Wrangler config into void.config.ts.");
-	const authored = readConfig(root).cloudflare ?? {};
-	const state = readState(root);
-	const resolved = state ? mergeConfig(state.source, state.resolved, authored) : authored;
-	const text = state && isDeepStrictEqual(resolved, state.resolved) && isDeepStrictEqual(authored, state.source) ? state.text : `${provenance(state?.text ?? "")}${JSON.stringify(resolved, null, 2)}\n`;
-	const path = join(root, MATERIALIZED_CLOUDFLARE_FILE);
-	if (!existsSync(path) || readFileSync(path, "utf8") !== text) writeAtomic(path, text);
-	if (state) writeState(root, {
-		version: 1,
-		source: authored,
-		resolved,
-		text
-	});
-	return path;
-}
-/** Record Cloudflare settings written by Void so later builds reproduce them. */
-function persistCloudflareConfig(root) {
-	if (!existsSync(join(root, "void.config.ts"))) return;
-	const path = join(root, MATERIALIZED_CLOUDFLARE_FILE);
-	if (!existsSync(path)) throw new Error(`config: Missing generated ${MATERIALIZED_CLOUDFLARE_FILE}.`);
-	const text = readFileSync(path, "utf8");
-	const resolved = parseCloudflareText(text, path);
-	const authored = readConfig(root).cloudflare ?? {};
-	if (readState(root) || !isDeepStrictEqual(resolved, authored) || text !== `${JSON.stringify(authored, null, 2)}\n`) writeState(root, {
-		version: 1,
-		source: authored,
-		resolved,
-		text
-	});
-}
-/** Seed the checked-in lock from a root Wrangler file during migration. */
-function seedCloudflareConfig(root, source, text) {
-	const existing = readState(root);
-	if (existing) {
-		if (isDeepStrictEqual(existing.source, source) && isDeepStrictEqual(existing.resolved, source)) return;
-		throw new Error(`migrate: ${VOID_LOCK_FILE} already exists with different settings. Resolve it before migrating.`);
-	}
-	if (!isDeepStrictEqual(parseCloudflareText(text, ".void-wrangler.jsonc"), source)) throw new Error("migrate: The Cloudflare config changed during migration. Retry.");
-	writeState(root, {
-		version: 1,
-		source,
-		resolved: source,
-		text
-	});
-}
-const DEFAULT_SANDBOX_CLASS_NAME = "SandboxV1";
-const SANDBOX_MIGRATION_TAG = "void-sandbox-v2";
-function isSandboxEnabled(config) {
-	return config.sandbox !== void 0 && config.sandbox !== false;
-}
-function getDefaultSandboxImage() {
-	return fileURLToPath(new URL("../../sandbox.Dockerfile", import.meta.resolve("void/sandbox")));
-}
-function getDefaultSandboxPlatformImage() {
-	return "cloudflare/debian-trixie";
-}
-function isLocalSandboxImage(image) {
-	const lowerImage = image.toLowerCase();
-	return isAbsolute(image) || image.startsWith("./") || image.startsWith("../") || lowerImage === "dockerfile" || lowerImage.includes("dockerfile") || lowerImage.endsWith("/dockerfile") || lowerImage.endsWith("\\dockerfile");
-}
-function requiresSandboxPlatformImage(config) {
-	if (typeof config.sandbox !== "object" || config.sandbox === null) return false;
-	return typeof config.sandbox.image === "string" && isLocalSandboxImage(config.sandbox.image) && config.sandbox.platformImage === void 0;
-}
-function resolveSandboxConfig(config, root = process.cwd()) {
-	const raw = typeof config.sandbox === "object" ? config.sandbox : {};
-	const image = raw.image ?? getDefaultSandboxImage();
-	const imageBuildContext = raw.imageBuildContext;
-	const platformImage = raw.platformImage ?? (raw.image && !isLocalSandboxImage(raw.image) ? raw.image : getDefaultSandboxPlatformImage());
-	if (!isLocalSandboxImage(image) && !isSandboxRegistryImage(image)) throw new Error("sandbox.image must be a Dockerfile or a digest-pinned Cloudflare registry image (registry.cloudflare.com/<account>/<image>@sha256:<digest>).");
-	if (platformImage !== getDefaultSandboxPlatformImage() && !isSandboxRegistryImage(platformImage)) throw new Error("sandbox.platformImage must be a digest-pinned Cloudflare registry image (registry.cloudflare.com/<account>/<image>@sha256:<digest>).");
-	return {
-		binding: raw.binding ?? "SANDBOX",
-		className: raw.className ?? "SandboxV1",
-		containerName: raw.containerName ?? "void-sandbox-v1",
-		image: resolveSandboxImage(image, root),
-		platformImage,
-		...imageBuildContext && { imageBuildContext: isAbsolute(imageBuildContext) ? imageBuildContext : join(root, imageBuildContext) },
-		...raw.instanceType && { instanceType: raw.instanceType }
-	};
-}
-function resolveSandboxImage(image, root) {
-	if (!isLocalSandboxImage(image) || isAbsolute(image)) return image;
-	return join(root, image);
-}
-function sandboxContainerConfig(sandbox) {
-	return {
-		name: sandbox.containerName,
-		class_name: sandbox.className,
-		scheduling_policy: "durable_object",
-		images: { default: isLocalSandboxImage(sandbox.image) ? {
-			dockerfile: sandbox.image,
-			...sandbox.imageBuildContext && { build_context: sandbox.imageBuildContext }
-		} : { image: sandbox.image } }
-	};
-}
-/** Refuse namespace reuse before either uploader can change a live Worker. */
-function assertSandboxNamespaceConfig(config, sandbox) {
-	const containers = Array.isArray(config.containers) ? config.containers : [];
-	const durable = config.durable_objects;
-	if (containers.some((container) => container.class_name === sandbox.className && container.scheduling_policy !== "durable_object") || durable?.bindings?.some((binding) => binding.name === sandbox.binding && binding.class_name !== sandbox.className)) throw new Error("Sandbox SDK 1.0 needs a new Durable Object namespace. Back up existing Sandbox data and deploy to a fresh Worker name with the new Sandbox configuration; remove legacy Sandbox bindings, containers, and migrations from that new Worker configuration. See https://developers.cloudflare.com/containers/guides/migrate-to-durable-object-scheduling-policy/.");
-}
-//#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. */
@@ -620,7 +389,7 @@ function syncWranglerBindings(root, bindings, options) {
 			modified = true;
 		}
 		const migrations = Array.isArray(parsed.migrations) ? parsed.migrations : [];
-		if (!migrations.some((migration) => migration.tag === "void-sandbox-v2" || migration.new_sqlite_classes?.includes(className))) {
+		if (!hasSandboxSqliteMigration(migrations, className)) {
 			parsed.migrations = [...migrations, {
 				tag: SANDBOX_MIGRATION_TAG,
 				new_sqlite_classes: [className]
@@ -1991,4 +1760,4 @@ function canonicalize(value) {
 	return value;
 }
 //#endregion
-export { writeWranglerPublishedTrafficSnapshot as A, materializeCloudflareConfig as B, readWranglerWebSocketTombstones as C, syncWranglerWebSockets as D, syncWranglerDurableObjects as E, requiresSandboxPlatformImage as F, restoreCloudflarePreviewPointer as H, resolveSandboxConfig as I, sandboxContainerConfig as L, SANDBOX_MIGRATION_TAG as M, assertSandboxNamespaceConfig as N, updateWranglerCustomDomain as O, isSandboxEnabled as P, MATERIALIZED_CLOUDFLARE_FILE as R, readWranglerPublishedTrafficSnapshot as S, syncWranglerBindings as T, seedCloudflareConfig as U, persistCloudflareConfig as V, stashCloudflareDeployPointer as W, readProvisionedBindingEntry as _, LIVE_MIGRATION_TAG as a, readWranglerCustomDomains as b, bindingEntriesForField as c, ensureWranglerNodejsAlsFlag as d, findBindingNameOwner as f, readExistingLiveBindingConfig as g, normalizeWranglerCompatibilityFlags as h, LATEST_KNOWN_COMPAT_DATE as i, DEFAULT_SANDBOX_CLASS_NAME as j, writeProvisionedWranglerConfig as k, ensureWranglerCompat as l, nextDurableObjectMigrationTag as m, DEFAULT_LIVE_CLASS as n, acknowledgeWranglerManagedQueueRemovals as o, hasDurableObjectSqliteMigration as p, FRIENDLY_BINDING_NAMES as r, assertNoDuplicateMembers as s, DEFAULT_LIVE_BINDING as t, ensureWranglerCompatibilityDate as u, readRootWranglerConfig as v, resolveLiveBindingConfig as w, readWranglerManagedQueueCleanupCandidates as x, readWranglerCompat as y, VOID_LOCK_FILE as z };
+export { writeProvisionedWranglerConfig as A, readWranglerPublishedTrafficSnapshot as C, syncWranglerDurableObjects as D, syncWranglerBindings as E, syncWranglerWebSockets as O, readWranglerManagedQueueCleanupCandidates as S, resolveLiveBindingConfig as T, readExistingLiveBindingConfig as _, LIVE_MIGRATION_TAG as a, readWranglerCompat as b, bindingEntriesForField as c, ensureWranglerCompatibilityDate as d, ensureWranglerNodejsAlsFlag as f, normalizeWranglerCompatibilityFlags as g, nextDurableObjectMigrationTag as h, LATEST_KNOWN_COMPAT_DATE as i, writeWranglerPublishedTrafficSnapshot as j, updateWranglerCustomDomain 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, readProvisionedBindingEntry as v, readWranglerWebSocketTombstones as w, readWranglerCustomDomains as x, readRootWranglerConfig as y };

package/dist/{ws-BoY7vQML.d.mts → ws-CL1w7GXU.d.mts}

@@ -1,10 +1,13 @@
 import { t as StandardSchemaV1 } from "./standard-schema-Fo_vCAZh.mjs";
 import { r as AuthUser } from "./auth-DkcFflXV.mjs";
-import { a as CloudEnv } from "./handler-HEcZsaij.mjs";
+import { a as CloudEnv } from "./handler-CZ4nAylQ.mjs";
 import { WebSocketRouteMap } from "void/routes";
 //#region src/runtime/ws.d.ts
 type MaybePromise<T> = T | Promise<T>;
 type ParamsRecord = Record<string, string>;
+type WebSocketInstanceKey = (context: {
+  params: ParamsRecord;
+}) => string;
 type WsEntry<P extends keyof WebSocketRouteMap> = WebSocketRouteMap[P];
 type ParamsOf<P extends keyof WebSocketRouteMap> = WsEntry<P> extends {
   params: infer T;
@@ -45,6 +48,10 @@ type SocketContext<ServerEvent = unknown> = WebSocketBaseContext & {
 };
 type RoomDefinition<ClientSchema extends StandardSchemaV1 = StandardSchemaV1, ServerSchema extends StandardSchemaV1 = StandardSchemaV1> = {
   readonly __kind: "room";
+  /** Optional persistent resource name. Pin the name reported by `void info` before moving this route. */
+  readonly name?: string;
+  /** Optional instance key; preserve existing keys when renaming route parameters. */
+  readonly key?: WebSocketInstanceKey;
   readonly messages: {
     client: ClientSchema;
     server: ServerSchema;
@@ -61,6 +68,10 @@ type RoomDefinition<ClientSchema extends StandardSchemaV1 = StandardSchemaV1, Se
 };
 type SocketDefinition<ClientSchema extends StandardSchemaV1 = StandardSchemaV1, ServerSchema extends StandardSchemaV1 = StandardSchemaV1> = {
   readonly __kind: "socket";
+  /** Optional persistent resource name. Pin the name reported by `void info` before moving this route. */
+  readonly name?: string;
+  /** Optional instance key; preserve existing keys when renaming route parameters. */
+  readonly key?: WebSocketInstanceKey;
   readonly messages: {
     client: ClientSchema;
     server: ServerSchema;
@@ -119,4 +130,4 @@ declare class VoidSocket<P extends keyof WebSocketRouteMap & string> {
 declare function connect<P extends keyof WebSocketRouteMap & string>(path: HasParams<P> extends false ? P : never): VoidSocket<P>;
 declare function connect<P extends keyof WebSocketRouteMap & string>(path: P, options: ConnectOptions<P>): VoidSocket<P>;
 //#endregion
-export { RoomDefinition as a, VoidSocket as c, WebSocketConnection as d, connect as f, RoomController as i, VoidSocketCloseEvent as l, defineWebSocket as m, ConnectCommonOptions as n, SocketContext as o, defineRoom as p, RoomContext as r, SocketDefinition as s, AnyWebSocketDefinition as t, WebSocketBaseContext as u };
+export { RoomDefinition as a, VoidSocket as c, WebSocketConnection as d, WebSocketInstanceKey as f, defineWebSocket as h, RoomController as i, VoidSocketCloseEvent as l, defineRoom as m, ConnectCommonOptions as n, SocketContext as o, connect as p, RoomContext as r, SocketDefinition as s, AnyWebSocketDefinition as t, WebSocketBaseContext as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "void",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/voidzero-dev/void.git",
@@ -39,10 +39,12 @@
     "#self/runtime/live-server": "./dist/runtime/live-server.mjs",
     "#self/runtime/fetch": "./dist/runtime/fetch.mjs",
     "#self/runtime/fetch-stream": "./dist/runtime/fetch-stream.mjs",
+    "#self/runtime/route-url": "./dist/runtime/route-url.mjs",
     "#self/runtime/migration-handler": "./dist/runtime/migration-handler.mjs",
     "#self/runtime/migration-handler-pg": "./dist/runtime/migration-handler-pg.mjs",
     "#self/runtime/migration-handler-mysql": "./dist/runtime/migration-handler-mysql.mjs",
-    "#self/runtime/ws-server": "./dist/runtime/ws-server.mjs"
+    "#self/runtime/ws-server": "./dist/runtime/ws-server.mjs",
+    "#self/runtime/routing": "./dist/runtime/routing.mjs"
   },
   "exports": {
     ".": {
@@ -321,6 +323,11 @@
     "./_sandbox-container": {
       "types": "./dist/runtime/sandbox-container.d.mts",
       "import": "./dist/runtime/sandbox-container.mjs"
+    },
+    "./limits": {
+      "types": "./dist/runtime/limits.d.mts",
+      "import": "./dist/runtime/limits.mjs",
+      "require": "./dist/runtime/limits.mjs"
     }
   },
   "dependencies": {
@@ -332,11 +339,11 @@
     "@cloudflare/workers-auth": "0.9.5",
     "@cloudflare/workers-types": "^4.20260702.1",
     "@napi-rs/keyring": "2.1.0",
-    "@void/deploy-cloudflare": "0.22.0",
-    "@void/deploy-core": "0.22.0",
-    "@void/edge": "0.22.0",
-    "@void/isr": "0.22.0",
-    "@void/platform": "0.22.0",
+    "@void/deploy-cloudflare": "0.23.0",
+    "@void/deploy-core": "0.23.0",
+    "@void/edge": "0.23.0",
+    "@void/isr": "0.23.0",
+    "@void/platform": "0.23.0",
     "acorn": "^8.18.0",
     "better-auth": "^1.7.6",
     "better-sqlite3": "^13.0.3",
@@ -387,7 +394,7 @@
     "zod": "^4.6.5"
   },
   "peerDependencies": {
-    "@void/md": "0.22.0",
+    "@void/md": "0.23.0",
     "arktype": ">=2.0.0",
     "valibot": ">=1.0.0-beta.7",
     "vite": "^8.0.0",

package/skills/migrate-vite-cloudflare-to-void/SKILL.md

@@ -1,175 +1,52 @@
 ---
 name: migrate-cloudflare-to-void
-description: Migrate an existing Vite app using @cloudflare/vite-plugin to Vite + void. Use when a project already runs on Cloudflare Workers but needs Void file-based routes, inferred bindings, and void deploy workflow.
+description: Migrate an existing Vite app using @cloudflare/vite-plugin to Void while preserving its routes, bindings, and deployment identity.
 ---
 
-# Migrate Vite + Cloudflare Plugin to Void
+# Migrate a Cloudflare Vite app to Void
 
-## When to use
+Read the app's package manifest, Vite config, Worker entry, Cloudflare config,
+and migrations. Identify its framework, endpoints, bindings, and deployed Worker
+before changing them.
 
-Use this skill when the user has an existing Vite app with `@cloudflare/vite-plugin` and wants to migrate to `void` with minimal breakage.
+Use the bundled guides under `../void/docs/`:
 
-Do not use this for greenfield apps started via `npm install -D void` + `npx void init`.
+- `integrations/cloudflare.md` for existing Worker handoff and configuration.
+- `integrations/frameworks/overview.md` and the matching framework guide when
+  another framework owns routing and SSR.
+- `guide/server-routing.md` for native Void handlers and middleware.
+- `guide/database.md` for schema and migration setup.
+- `reference/cli.md` before running commands.
 
-## Inputs to gather first
+Add `void` and replace `cloudflare()` with `voidPlugin()`, preserving the
+framework plugins and unrelated Vite settings. Remove dependencies and scripts
+only when their replacement is working and no other workflow uses them.
 
-Read these files before editing:
-
-- `package.json`
-- `vite.config.*`
-- `wrangler.jsonc` (if present)
-- Current worker entrypoint (`src/worker.*`, `src/index.*`, etc.)
-- Any existing API handlers and migration SQL files
-
-Confirm:
-
-- existing routes/endpoints and HTTP methods
-- bindings currently used (`DB`, `KV`, `R2`, etc.)
-- whether the app uses framework SSR or only SPA + API
-
-## Migration workflow
-
-1. Update dependencies
-
-- Remove `@cloudflare/vite-plugin` if it is only used for runtime/deploy.
-- Add `void`.
-- Keep existing framework plugins (React/Vue/Svelte/etc.).
-
-2. Update Vite config
-
-- Replace `cloudflare(...)` plugin usage with `voidPlugin()`.
-- Keep plugin order stable unless there is a known conflict.
-- Keep unrelated Vite settings unchanged.
-
-Target shape:
+For native Void routes, use one file per URL with named HTTP method exports:
 
 ```ts
-import { defineConfig } from 'vite';
-import { voidPlugin } from 'void';
+// routes/api/users/[id].ts
+import { defineHandler } from 'void';
 
-export default defineConfig({
-  plugins: [voidPlugin()],
+export const GET = defineHandler((c) => {
+  return { id: c.req.param('id') };
 });
 ```
 
-3. Migrate API surface to file-based routes
-
-- Create `routes/` if missing.
-- Convert each existing endpoint into route files:
-  - `routes/api/users.get.ts`
-  - `routes/api/users.post.ts`
-  - `routes/api/users/[id].get.ts`
-- Use `defineHandler` from `void`.
-- If there is shared logic, move it into regular modules and import from route files.
-
-4. Migrate middleware
-
-- Move request-wide middleware to `middleware/*.ts`.
-- Export with `defineMiddleware`.
-- Preserve behavior order by filename prefix when needed (`01.auth.ts`, `02.logger.ts`).
-
-5. Preserve bindings with Void conventions
-
-- Keep Cloudflare-style uppercase names on `c.env` (`DB`, `KV`, `STORAGE`, etc.).
-- Remove manual binding config from Vite plugin config where Void now infers usage.
-- Ensure route code actually references required bindings so inference can detect them.
-
-6. Migrations
-
-- Place SQL files in `migrations/` (sorted by filename).
-- Keep destructive operations gated by explicit pragma if needed.
-- If old migrations live elsewhere, copy/rename into this directory with stable ordering.
-
-7. Deploy workflow migration
-
-- Replace old deploy instructions with:
-  - `void account login`
-  - `void deploy`
-- If CI must target a specific project, use:
-  - `void deploy --project <slug>`
-  - or `VOID_PROJECT=<slug> void deploy`
-
-8. Post-migration cleanup (remove obsolete Wrangler wiring)
-
-- If the app no longer uses direct Wrangler workflows, remove `wrangler.jsonc`.
-- Remove direct `wrangler` dependency/devDependency from `package.json` when it is only used for old deploy/dev scripts.
-- Remove or rewrite npm scripts that call `wrangler` directly (for example old deploy/publish scripts).
-- Keep Wrangler only if the project still has explicit non-Void workflows that require it.
-
-## Routing behavior reference (use during file conversion)
-
-Apply these filename rules exactly when mapping old handlers to `routes/`:
-
-1. Extension and suffix parsing order
-
-- Strip extension (`.ts`, `.js`, `.mts`, `.mjs`).
-- Strip env suffix (`.dev`, `.prod`). The suffix restricts the route to that environment, so only use it for handlers that must not ship to the other one.
-- Strip HTTP method suffix (`.get`, `.post`, `.put`, `.delete`, `.patch`).
-- Strip trailing `index` segment.
-- Remove route group segments `(group-name)` from URL path.
-
-2. Method mapping
-
-- `users.get.ts` matches only `GET /users`.
-- `users.post.ts` matches only `POST /users`.
-- `users.ts` matches all methods.
-- Split multi-method handlers into one file per method when preserving behavior matters.
-
-3. Dynamic and catch-all params
-
-- `[id]` -> `:id`
-- `[...slug]` -> catch-all named param
-- `[...]` -> catch-all unnamed fallback
-- Use folder nesting for multiple params: `routes/api/org/[org]/repo/[repo].get.ts`.
-
-4. Route groups and organization
-
-- Directories like `(internal)` are for code organization only and do not appear in URL.
-- Use them when reorganizing large route sets without changing public paths.
-
-5. Ignored files
-
-- Files or directories starting with `_` are ignored by route scanner.
-- Do not place active handlers under `_legacy`, `_draft`, etc.
-
-6. Middleware behavior
-
-- Middleware files live in `middleware/` and run in filename order.
-- Prefix numerically if order is important (`01.auth.ts`, `02.logger.ts`).
-
-7. Concrete mapping examples
-
-- `src/worker.ts` handling `GET /api/users/:id` -> `routes/api/users/[id].get.ts`
-- single handler switching on method for `/api/users` -> `routes/api/users.get.ts` and `routes/api/users.post.ts`
-- legacy `GET /health` endpoint -> `routes/health.get.ts`
-
-## Verification checklist
-
-Run and validate:
-
-1. `npm run dev` (or project dev command)
-2. Exercise representative API routes locally.
-3. `npm run build`
-4. `void deploy` and verify live URL responds.
-5. Confirm no deploy-critical scripts still depend on `wrangler`.
-
-In the Void deploy output, verify:
-
-- worker modules uploaded
-- static assets uploaded
-- migrations applied (if present)
-
-## Common migration pitfalls
-
-- Importing from the main `void` runtime in worker route files when a lighter handler import is expected by tooling.
-- Forgetting to split method-specific handlers (`GET`/`POST`) into filename suffixes.
-- Keeping old custom worker entry wiring that conflicts with generated route runtime.
-- Binding names changed to lowercase (`db`) instead of expected uppercase (`DB`), breaking inference/provisioning.
+Keep GET and POST for the same URL in the same file. Middleware lives in
+`middleware/` and runs in filename order. Preserve existing URLs and behavior;
+framework apps keep their framework's routing conventions.
 
-## Deliverable format
+Preserve configured bindings and resource IDs. Use `void.config.ts` for authored
+settings and `void.lock.json` for provisioned state. Let Void migrate supported
+root Cloudflare configuration rather than deleting it before the handoff.
+Database migrations live in `db/migrations/`; preserve their journal, ordering,
+and deployed history instead of recreating them.
 
-When applying this migration, produce:
+Verify the app's development server, representative routes, and production build.
+When deployment is part of the user's request, follow the existing Worker
+handoff in the Cloudflare guide and verify the reported URL. Keep new resources,
+auth setup, and database or secret changes separate from that first handoff;
+follow its explicit ISR cache choice when needed.
 
-1. A change summary grouped by config/routes/migrations/CI.
-2. A list of moved or newly created route files.
-3. Exact commands to run locally and in CI.
+Summarize the changes and any remaining migration work.