vinext 0.1.8 → 0.2.1

package/dist/packages/cloudflare/src/deploy.js

@@ -0,0 +1,272 @@
+import { detectProject, findInNodeModules, formatMissingCloudflarePluginError, getMissingDeps } from "../../../utils/project.js";
+import { loadNextConfig, resolveNextConfig } from "../../../config/next-config.js";
+import { formatVinextPrerenderLabel, loadVinextPrerenderConfigFromViteConfig, resolveVinextPrerenderDecision } from "../../../config/prerender.js";
+import { runPrerender } from "../../../build/run-prerender.js";
+import { loadDotenv } from "../../../config/dotenv.js";
+import { runTPR } from "./tpr.js";
+import { formatImageOptimizationHint, formatMissingCacheAdapterError, viteConfigHasCacheAdapter, viteConfigHasCloudflarePlugin, viteConfigHasImageAdapter, workerEntryHasCacheHandler } from "./deploy-config.js";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { execFileSync } from "node:child_process";
+//#region ../cloudflare/src/deploy.ts
+/**
+* vinext-cloudflare deploy — one-command Cloudflare Workers deployment.
+*
+* Takes any Next.js app and deploys it to Cloudflare Workers:
+*
+*   1. Validates the project was prepared by `vinext init --platform=cloudflare`
+*   2. Runs the Vite build
+*   3. Deploys to Cloudflare Workers via Wrangler
+*/
+function parsePositiveIntegerArg(raw, flag) {
+	if (raw === "") throw new Error(`${flag} requires a value, but none was provided.`);
+	const parsed = Number(raw);
+	if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${flag} expects a positive integer, but got "${raw}".`);
+	return parsed;
+}
+/** Deploy command flag definitions for util.parseArgs. */
+const deployArgOptions = {
+	help: {
+		type: "boolean",
+		short: "h",
+		default: false
+	},
+	preview: {
+		type: "boolean",
+		default: false
+	},
+	env: { type: "string" },
+	name: { type: "string" },
+	"skip-build": {
+		type: "boolean",
+		default: false
+	},
+	"dry-run": {
+		type: "boolean",
+		default: false
+	},
+	"prerender-all": {
+		type: "boolean",
+		default: false
+	},
+	"prerender-concurrency": { type: "string" },
+	"experimental-tpr": {
+		type: "boolean",
+		default: false
+	},
+	"tpr-coverage": { type: "string" },
+	"tpr-limit": { type: "string" },
+	"tpr-window": { type: "string" }
+};
+function parseDeployArgs(args) {
+	const { values } = parseArgs({
+		args,
+		options: deployArgOptions,
+		strict: true
+	});
+	function parseIntArg(name, raw) {
+		if (!raw) return void 0;
+		const n = parseInt(raw, 10);
+		if (isNaN(n)) {
+			console.error(`  --${name} must be a number (got: ${raw})`);
+			process.exit(1);
+		}
+		return n;
+	}
+	return {
+		help: values.help,
+		preview: values.preview,
+		env: values.env?.trim() || void 0,
+		name: values.name?.trim() || void 0,
+		skipBuild: values["skip-build"],
+		dryRun: values["dry-run"],
+		prerenderAll: values["prerender-all"],
+		prerenderConcurrency: values["prerender-concurrency"] === void 0 ? void 0 : parsePositiveIntegerArg(values["prerender-concurrency"], "--prerender-concurrency"),
+		experimentalTPR: values["experimental-tpr"],
+		tprCoverage: parseIntArg("tpr-coverage", values["tpr-coverage"]),
+		tprLimit: parseIntArg("tpr-limit", values["tpr-limit"]),
+		tprWindow: parseIntArg("tpr-window", values["tpr-window"])
+	};
+}
+/**
+* Run a function with `process.env.CLOUDFLARE_ENV` set to the given value,
+* restoring the previous state (whether set or absent) after the function
+* resolves or throws.
+*
+* The `@cloudflare/vite-plugin` reads `CLOUDFLARE_ENV` from `process.env` to
+* drive the multi-environment merge applied to the emitted `wrangler.json`.
+* Without this propagation the `--env <name>` CLI flag is silently ignored at
+* build time and the top-level config is emitted regardless. See issue #1210.
+*
+* Passing `undefined` is a no-op; the callback runs with `process.env` untouched.
+*/
+async function withCloudflareEnv(env, fn) {
+	if (env === void 0 || env === "") return fn();
+	const hadPrev = "CLOUDFLARE_ENV" in process.env;
+	const prev = process.env.CLOUDFLARE_ENV;
+	process.env.CLOUDFLARE_ENV = env;
+	try {
+		return await fn();
+	} finally {
+		if (hadPrev) process.env.CLOUDFLARE_ENV = prev;
+		else delete process.env.CLOUDFLARE_ENV;
+	}
+}
+async function loadProjectViteApi(root) {
+	let vitePath;
+	try {
+		vitePath = createRequire(path.join(root, "package.json")).resolve("vite");
+	} catch {
+		vitePath = "vite";
+	}
+	return await (vitePath === "vite" ? import(vitePath) : import(pathToFileURL(vitePath).href));
+}
+async function runBuild(info, env) {
+	console.log("\n  Building for Cloudflare Workers...\n");
+	const { createBuilder } = await loadProjectViteApi(info.root);
+	await withCloudflareEnv(env, async () => {
+		await (await createBuilder({ root: info.root })).buildApp();
+	});
+}
+function validateWranglerEnvName(env) {
+	if (env.includes("\0")) throw new Error("Wrangler environment names cannot contain null bytes.");
+	return env;
+}
+function buildWranglerDeployArgs(options) {
+	const args = ["deploy"];
+	const env = options.env || (options.preview ? "preview" : void 0);
+	if (env) args.push("--env", validateWranglerEnvName(env));
+	return {
+		args,
+		env
+	};
+}
+/**
+* Resolve Wrangler's JavaScript CLI entrypoint in node_modules.
+*
+* Invoking the JavaScript file through `process.execPath` avoids the `.cmd`
+* shim and command shell that package managers create on Windows.
+*/
+function resolveWranglerBin(root, resolvePackageJson = (projectRoot) => {
+	try {
+		return createRequire(path.join(projectRoot, "package.json")).resolve("wrangler/package.json");
+	} catch {
+		return findInNodeModules(projectRoot, "wrangler/package.json");
+	}
+}) {
+	const packageJsonPath = resolvePackageJson(root);
+	if (packageJsonPath) {
+		const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+		const bin = typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin?.wrangler;
+		if (bin) return path.resolve(path.dirname(packageJsonPath), bin);
+	}
+	return path.join(root, "node_modules", "wrangler", "bin", "wrangler.js");
+}
+function buildNodeCliInvocation(scriptPath, args, nodeExecutable = process.execPath) {
+	return {
+		file: nodeExecutable,
+		args: [scriptPath, ...args]
+	};
+}
+function buildWranglerInvocation(root, options, nodeExecutable = process.execPath) {
+	const wranglerBin = resolveWranglerBin(root);
+	const { args, env } = buildWranglerDeployArgs(options);
+	return {
+		...buildNodeCliInvocation(wranglerBin, args, nodeExecutable),
+		env
+	};
+}
+function runWranglerDeploy(root, options, execute = execFileSync) {
+	const execOpts = {
+		cwd: root,
+		stdio: "pipe",
+		encoding: "utf-8",
+		shell: false
+	};
+	const { file, args, env } = buildWranglerInvocation(root, options);
+	if (env) console.log(`\n  Deploying to env: ${env}...`);
+	else console.log("\n  Deploying to production...");
+	const output = execute(file, args, execOpts);
+	const urlMatch = output.match(/https:\/\/[^\s]+\.workers\.dev[^\s]*/);
+	const deployedUrl = urlMatch ? urlMatch[0] : null;
+	if (output.trim()) for (const line of output.trim().split("\n")) console.log(`  ${line}`);
+	return deployedUrl ?? "(URL not detected in wrangler output)";
+}
+async function deploy(options) {
+	const deployEnv = validateWranglerEnvName(options.env || (options.preview ? "preview" : "production"));
+	const root = path.resolve(options.root);
+	loadDotenv({
+		root,
+		mode: "production"
+	});
+	console.log("\n  vinext-cloudflare deploy\n");
+	const info = detectProject(root);
+	if (!info.isAppRouter && !info.isPagesRouter) {
+		console.error("  Error: No app/ or pages/ directory found.");
+		console.error("  vinext-cloudflare deploy requires a Next.js project with an app/ or pages/ directory");
+		console.error("  (also checks src/app/ and src/pages/).\n");
+		process.exit(1);
+	}
+	if (options.name) info.projectName = options.name;
+	console.log(`  Project: ${info.projectName}`);
+	console.log(`  Router:  ${info.isAppRouter ? "App Router" : "Pages Router"}`);
+	console.log(`  ISR:     ${info.hasISR ? "detected" : "none"}`);
+	const missingScaffolding = [!info.hasViteConfig && "Vite config", !info.hasWranglerConfig && "Wrangler config"].filter((value) => Boolean(value));
+	if (missingScaffolding.length > 0) throw new Error(`Missing Cloudflare deployment setup: ${missingScaffolding.join(", ")}. Run \`vinext init --platform=cloudflare\` first.`);
+	const missingDeps = getMissingDeps(info);
+	if (missingDeps.length > 0) throw new Error(`Missing deployment dependencies: ${missingDeps.map((dependency) => dependency.name).join(", ")}. Run \`vinext init --platform=cloudflare\` first.`);
+	if (info.hasViteConfig && !viteConfigHasCloudflarePlugin(root)) throw new Error(formatMissingCloudflarePluginError({ isAppRouter: info.isAppRouter }));
+	if (info.hasISR && !viteConfigHasCacheAdapter(root) && !workerEntryHasCacheHandler(root)) throw new Error(formatMissingCacheAdapterError({}));
+	if (!viteConfigHasImageAdapter(root)) {
+		console.log();
+		console.log(formatImageOptimizationHint());
+	}
+	if (options.dryRun) {
+		console.log("\n  Dry run complete. No build or deploy performed.\n");
+		return;
+	}
+	const buildEnv = deployEnv === "production" && !options.env ? void 0 : deployEnv;
+	if (!options.skipBuild) await runBuild(info, buildEnv);
+	else console.log("\n  Skipping build (--skip-build)");
+	{
+		const nextConfig = await resolveNextConfig(await loadNextConfig(info.root), info.root);
+		const vinextPrerenderConfig = !options.prerenderAll && nextConfig.output !== "export" ? await withCloudflareEnv(buildEnv, async () => {
+			return loadVinextPrerenderConfigFromViteConfig(await loadProjectViteApi(info.root), info.root);
+		}) : null;
+		const prerenderDecision = resolveVinextPrerenderDecision({
+			prerenderAllFlag: options.prerenderAll,
+			vinextPrerenderConfig,
+			nextOutput: nextConfig.output
+		});
+		if (prerenderDecision) {
+			console.log(`\n  ${formatVinextPrerenderLabel(prerenderDecision)}`);
+			if (nextConfig.enablePrerenderSourceMaps) {
+				process.setSourceMapsEnabled(true);
+				Error.stackTraceLimit = Math.max(Error.stackTraceLimit, 50);
+			}
+			await runPrerender({
+				root: info.root,
+				concurrency: options.prerenderConcurrency
+			});
+		}
+	}
+	if (options.experimentalTPR) {
+		console.log();
+		const tprResult = await runTPR({
+			root,
+			coverage: Math.max(1, Math.min(100, options.tprCoverage ?? 90)),
+			limit: Math.max(1, options.tprLimit ?? 1e3),
+			window: Math.max(1, options.tprWindow ?? 24)
+		});
+		if (tprResult.skipped) console.log(`  TPR: Skipped (${tprResult.skipped})`);
+	}
+	const url = runWranglerDeploy(root, { env: deployEnv === "production" && !options.env ? void 0 : deployEnv });
+	console.log("\n  ─────────────────────────────────────────");
+	console.log(`  Deployed to: ${url}`);
+	console.log("  ─────────────────────────────────────────\n");
+}
+//#endregion
+export { deploy, parseDeployArgs };

package/dist/{cloudflare → packages/cloudflare/src}/tpr.d.ts

@@ -1,4 +1,4 @@
-//#region src/cloudflare/tpr.d.ts
+//#region ../cloudflare/src/tpr.d.ts
 /**
  * TPR: Traffic-aware Pre-Rendering
  *
@@ -33,50 +33,13 @@ type TPRResult = {
   durationMs: number; /** If TPR was skipped, the reason. */
   skipped?: string;
 };
-type PrerenderResult = {
-  html: string;
-  status: number;
-  headers: Record<string, string>;
-};
-type WranglerConfig = {
-  accountId?: string;
-  kvNamespaceId?: string;
-  customDomain?: string;
-};
-/**
- * Parse wrangler config (JSONC or TOML) to extract the fields TPR needs:
- * account_id, VINEXT_KV_CACHE KV namespace ID, and custom domain.
- */
-declare function parseWranglerConfig(root: string): WranglerConfig | null;
-/**
- * Generate zone lookup candidates from shortest (2-part) to longest.
- * Tries the most common case first (e.g., "example.com") and progressively
- * adds labels for multi-part TLDs (e.g., "co.uk" → "example.co.uk").
- *
- * "shop.example.com"    → ["example.com", "shop.example.com"]
- * "shop.example.co.uk"  → ["co.uk", "example.co.uk", "shop.example.co.uk"]
- * "example.com"         → ["example.com"]
- */
-declare function domainCandidates(domain: string): string[];
-/**
- * Build KV bulk API pairs from pre-rendered entries.
- *
- * Key format matches the runtime KVCacheHandler exactly:
- *   ENTRY_PREFIX + isrCacheKey("app", pathname, buildId) + ":html"
- *   → "cache:app:<buildId>:<pathname>:html"
- */
-declare function buildTprKVPairs(entries: Map<string, PrerenderResult>, buildId: string | undefined, defaultRevalidateSeconds: number): Array<{
-  key: string;
-  value: string;
-  expiration_ttl: number;
-}>;
 /**
  * Run the TPR pipeline: query traffic, select routes, pre-render, upload.
  *
- * Designed to be called between the build step and wrangler deploy in
- * the `vinext deploy` pipeline. Gracefully skips (never errors) when
+ * Designed to be called between the build step and wrangler deploy in the
+ * `vinext-cloudflare deploy` pipeline. Gracefully skips (never errors) when
  * the prerequisites aren't met.
  */
 declare function runTPR(options: TPROptions): Promise<TPRResult>;
 //#endregion
-export { TPROptions, TPRResult, buildTprKVPairs, domainCandidates, parseWranglerConfig, runTPR };
+export { TPROptions, TPRResult, runTPR };

package/dist/{cloudflare → packages/cloudflare/src}/tpr.js

@@ -1,11 +1,13 @@
-import { VINEXT_REVALIDATE_HEADER } from "../server/headers.js";
-import { isrCacheKey } from "../server/isr-cache.js";
-import { buildAppPageCacheTags } from "../server/app-page-cache.js";
-import { ENTRY_PREFIX } from "./src/cache/kv-data-adapter.runtime.js";
+import { VINEXT_REVALIDATE_HEADER } from "../../../server/headers.js";
+import { isrCacheKey } from "../../../server/isr-cache.js";
+import { buildAppPageCacheTags } from "../../../server/app-page-cache.js";
+import { ENTRY_PREFIX } from "./cache/kv-data-adapter.runtime.js";
+import { createRequire } from "node:module";
 import fs from "node:fs";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
-//#region src/cloudflare/tpr.ts
+//#region ../cloudflare/src/tpr.ts
 /**
 * TPR: Traffic-aware Pre-Rendering
 *
@@ -304,6 +306,25 @@ const PRERENDER_PORT = 19384;
 const SERVER_STARTUP_TIMEOUT = 3e4;
 /** Max concurrent fetch requests during pre-rendering. */
 const FETCH_CONCURRENCY = 10;
+const NON_CACHEABLE_CACHE_CONTROL_RE = /\b(?:no-store|no-cache|private)\b/i;
+function getTprHeader(headers, name) {
+	const normalizedName = name.toLowerCase();
+	for (const [key, value] of Object.entries(headers)) if (key.toLowerCase() === normalizedName) return value;
+}
+function hasNonCacheableCacheControl(headers) {
+	const cacheControl = getTprHeader(headers, "cache-control");
+	return cacheControl ? NON_CACHEABLE_CACHE_CONTROL_RE.test(cacheControl) : false;
+}
+function readTprRevalidateHeader(headers) {
+	const revalidateHeader = getTprHeader(headers, VINEXT_REVALIDATE_HEADER);
+	if (revalidateHeader === void 0) return void 0;
+	return Number(revalidateHeader);
+}
+function isTprCacheable(headers) {
+	if (hasNonCacheableCacheControl(headers)) return false;
+	const revalidate = readTprRevalidateHeader(headers);
+	return revalidate === void 0 || Number.isFinite(revalidate) && revalidate > 0;
+}
 /**
 * Start a local production server, fetch each route to produce HTML,
 * and return the results. Pages that fail to render are skipped.
@@ -331,11 +352,12 @@ async function prerenderRoutes(routes, root, hostDomain) {
 						redirect: "manual"
 					});
 					if (response.status < 400) {
-						const html = await response.text();
 						const headers = {};
 						response.headers.forEach((value, key) => {
 							if (key === "content-type" || key === "cache-control" || key === "x-vinext-revalidate" || key === "location") headers[key] = value;
 						});
+						if (!isTprCacheable(headers)) return;
+						const html = await response.text();
 						results.set(routePath, {
 							html,
 							status: response.status,
@@ -360,17 +382,15 @@ async function prerenderRoutes(routes, root, hostDomain) {
 }
 /**
 * Spawn a subprocess running the vinext production server.
-* Uses the same Node.js binary and resolves prod-server.js relative
-* to the current module (works whether vinext is installed or linked).
+* Uses the same Node.js binary and resolves vinext from the project root so
+* linked/package-manager-managed installs use the app's vinext peer.
 */
 function startLocalServer(root, port) {
-	const prodServerPath = path.resolve(import.meta.dirname, "..", "server", "prod-server.js");
+	const prodServerPath = resolveVinextProdServerPath(root);
 	const outDir = path.join(root, "dist");
-	const escapedProdServer = prodServerPath.replace(/\\/g, "\\\\");
-	const escapedOutDir = outDir.replace(/\\/g, "\\\\");
 	const script = [
-		`import("file://${escapedProdServer}")`,
-		`.then(m => m.startProdServer({ port: ${port}, host: "127.0.0.1", outDir: "${escapedOutDir}" }))`,
+		`import(${JSON.stringify(pathToFileURL(prodServerPath).href)})`,
+		`.then(m => m.startProdServer({ port: ${port}, host: "127.0.0.1", outDir: ${JSON.stringify(outDir)} }))`,
 		`.catch(e => { console.error("[vinext-tpr] Server failed to start:", e); process.exit(1); });`
 	].join("");
 	const proc = spawn(process.execPath, [
@@ -391,6 +411,9 @@ function startLocalServer(root, port) {
 	});
 	return proc;
 }
+function resolveVinextProdServerPath(root) {
+	return createRequire(path.join(root, "package.json")).resolve("vinext/server/prod-server");
+}
 /** Poll the local server until it responds or the timeout is reached. */
 async function waitForServer(port, timeoutMs) {
 	const start = Date.now();
@@ -424,10 +447,11 @@ function buildTprKVPairs(entries, buildId, defaultRevalidateSeconds) {
 	const now = Date.now();
 	const pairs = [];
 	for (const [routePath, result] of entries) {
-		const revalidateHeader = result.headers[VINEXT_REVALIDATE_HEADER];
-		const revalidateSeconds = revalidateHeader && !isNaN(Number(revalidateHeader)) ? Number(revalidateHeader) : defaultRevalidateSeconds;
-		const revalidateAt = revalidateSeconds > 0 ? now + revalidateSeconds * 1e3 : null;
-		const kvTtl = revalidateSeconds > 0 ? MAX_KV_TTL_SECONDS : 24 * 3600;
+		if (!isTprCacheable(result.headers)) continue;
+		const revalidateSeconds = readTprRevalidateHeader(result.headers) ?? defaultRevalidateSeconds;
+		if (!Number.isFinite(revalidateSeconds) || revalidateSeconds <= 0) continue;
+		const revalidateAt = now + revalidateSeconds * 1e3;
+		const kvTtl = MAX_KV_TTL_SECONDS;
 		const tags = buildAppPageCacheTags(routePath, []);
 		const entry = {
 			value: {
@@ -477,8 +501,8 @@ const DEFAULT_REVALIDATE_SECONDS = 3600;
 /**
 * Run the TPR pipeline: query traffic, select routes, pre-render, upload.
 *
-* Designed to be called between the build step and wrangler deploy in
-* the `vinext deploy` pipeline. Gracefully skips (never errors) when
+* Designed to be called between the build step and wrangler deploy in the
+* `vinext-cloudflare deploy` pipeline. Gracefully skips (never errors) when
 * the prerequisites aren't met.
 */
 async function runTPR(options) {
@@ -555,4 +579,4 @@ async function runTPR(options) {
 	};
 }
 //#endregion
-export { buildTprKVPairs, domainCandidates, parseWranglerConfig, runTPR };
+export { runTPR };

package/dist/plugins/ast-scope.d.ts

@@ -0,0 +1,16 @@
+import { AstRecord } from "./ast-utils.js";
+
+//#region src/plugins/ast-scope.d.ts
+type AstScope = {
+  parent: AstScope | null;
+  bindings: Set<string>;
+};
+declare function createAstScope<T extends AstScope>(parent: T | null): AstScope;
+declare function hasAstBinding(scope: AstScope, name: string): boolean;
+declare function isFunctionNode(node: AstRecord): boolean;
+declare function collectDirectScopeBindings(node: AstRecord, scope: AstScope, onVariableDeclarator?: (declaration: AstRecord, declarator: AstRecord) => void): void;
+declare function collectLoopScopeBindings(node: AstRecord, scope: AstScope, onVariableDeclarator?: (declaration: AstRecord, declarator: AstRecord) => void): void;
+declare function collectSwitchScopeBindings(node: AstRecord, scope: AstScope, onVariableDeclarator?: (declaration: AstRecord, declarator: AstRecord) => void): void;
+declare function collectVarScopeBindings(node: AstRecord, scope: AstScope, root?: boolean): void;
+//#endregion
+export { AstScope, collectDirectScopeBindings, collectLoopScopeBindings, collectSwitchScopeBindings, collectVarScopeBindings, createAstScope, hasAstBinding, isFunctionNode };

package/dist/plugins/ast-scope.js

@@ -0,0 +1,62 @@
+import { collectBindingNames, forEachAstChild, isAstRecord, nodeArray } from "./ast-utils.js";
+//#region src/plugins/ast-scope.ts
+function createAstScope(parent) {
+	return {
+		parent,
+		bindings: /* @__PURE__ */ new Set()
+	};
+}
+function hasAstBinding(scope, name) {
+	for (let current = scope; current; current = current.parent) if (current.bindings.has(name)) return true;
+	return false;
+}
+function isFunctionNode(node) {
+	return node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression";
+}
+function collectDirectScopeBindings(node, scope, onVariableDeclarator) {
+	for (const statementValue of nodeArray(node.body)) {
+		const statement = isAstRecord(statementValue) ? statementValue : null;
+		if (!statement) continue;
+		const declaration = statement.type === "ExportNamedDeclaration" || statement.type === "ExportDefaultDeclaration" ? isAstRecord(statement.declaration) ? statement.declaration : null : statement;
+		if (!declaration) continue;
+		if (declaration.type === "ImportDeclaration") {
+			if (declaration.importKind === "type") continue;
+			for (const specifier of nodeArray(declaration.specifiers)) if (isAstRecord(specifier) && specifier.importKind !== "type") collectBindingNames(specifier.local, scope.bindings);
+		} else if (declaration.type === "TSImportEqualsDeclaration" && declaration.importKind !== "type") collectBindingNames(declaration.id, scope.bindings);
+		else if (declaration.type === "VariableDeclaration" && declaration.declare !== true) for (const declarator of nodeArray(declaration.declarations)) {
+			if (!isAstRecord(declarator)) continue;
+			collectBindingNames(declarator.id, scope.bindings);
+			onVariableDeclarator?.(declaration, declarator);
+		}
+		else if ((declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") && declaration.declare !== true) collectBindingNames(declaration.id, scope.bindings);
+		else if ((declaration.type === "TSEnumDeclaration" || declaration.type === "TSModuleDeclaration") && declaration.declare !== true) collectBindingNames(declaration.id, scope.bindings);
+	}
+}
+function collectLoopScopeBindings(node, scope, onVariableDeclarator) {
+	const declarationValue = node.type === "ForStatement" ? node.init : node.left;
+	if (!isAstRecord(declarationValue)) return;
+	if (declarationValue.type !== "VariableDeclaration" || declarationValue.declare === true) return;
+	for (const declarator of nodeArray(declarationValue.declarations)) {
+		if (!isAstRecord(declarator)) continue;
+		collectBindingNames(declarator.id, scope.bindings);
+		onVariableDeclarator?.(declarationValue, declarator);
+	}
+}
+function collectSwitchScopeBindings(node, scope, onVariableDeclarator) {
+	for (const caseValue of nodeArray(node.cases)) {
+		if (!isAstRecord(caseValue)) continue;
+		collectDirectScopeBindings({
+			type: "BlockStatement",
+			body: nodeArray(caseValue.consequent)
+		}, scope, onVariableDeclarator);
+	}
+}
+function collectVarScopeBindings(node, scope, root = true) {
+	if (!root && (isFunctionNode(node) || node.type === "StaticBlock" || node.type === "TSModuleBlock")) return;
+	if (node.type === "VariableDeclaration" && node.kind === "var" && node.declare !== true) {
+		for (const declarator of nodeArray(node.declarations)) if (isAstRecord(declarator)) collectBindingNames(declarator.id, scope.bindings);
+	}
+	forEachAstChild(node, (child) => collectVarScopeBindings(child, scope, false));
+}
+//#endregion
+export { collectDirectScopeBindings, collectLoopScopeBindings, collectSwitchScopeBindings, collectVarScopeBindings, createAstScope, hasAstBinding, isFunctionNode };

package/dist/plugins/ast-utils.d.ts

@@ -9,6 +9,32 @@ type AstRange = AstRecord & {
   start: number;
   end: number;
 };
+/**
+ * Cheap pre-parse gate for plugins that only transform *dynamic* `import(...)`.
+ *
+ * Static imports — `import x from "..."`, `import { ... } from "..."`,
+ * `import "..."` — never place a `(` (nor a comment leading to one) immediately
+ * after the `import` keyword. Plugins that act only on dynamic `import(...)` use
+ * this to skip `parseAst` for the overwhelming majority of modules in a large
+ * app: at ~5k routes, where almost every module is a static-import-only page,
+ * it removes most of the build's AST-parse/GC cost. This is a deliberate,
+ * measured performance filter — keep it a regex, never a parse.
+ *
+ * It intentionally errs toward over-matching: a false positive costs one
+ * redundant parse, whereas a false negative would silently skip a real dynamic
+ * import (a correctness bug). `\s*[(/]` therefore tolerates whitespace and
+ * block/line comments between the `import` keyword and its parenthesis.
+ *
+ * Usable directly as a Rolldown `transform.filter.code` regex, or via
+ * {@link mayContainDynamicImport} for an in-handler prescan.
+ */
+declare const DYNAMIC_IMPORT_PRESCAN: RegExp;
+/**
+ * Whether `code` might contain a dynamic `import(...)` call. See
+ * {@link DYNAMIC_IMPORT_PRESCAN} — a cheap, deliberately over-inclusive regex
+ * gate used to avoid parsing static-import-only modules.
+ */
+declare function mayContainDynamicImport(code: string): boolean;
 declare function isAstRecord(value: unknown): value is AstRecord;
 declare function nodeArray(value: unknown): unknown[];
 declare function hasRange(node: AstRecord | null): node is AstRange;
@@ -17,4 +43,4 @@ declare function getAstName(value: unknown): string | null;
 declare function forEachAstChild(node: AstRecord, callback: (child: AstRecord) => void): void;
 declare function collectBindingNames(pattern: unknown, target: Set<string>): void;
 //#endregion
-export { AstRange, AstRecord, collectBindingNames, forEachAstChild, getAstName, hasRange, isAstRecord, isIdentifierNamed, nodeArray };
+export { AstRange, AstRecord, DYNAMIC_IMPORT_PRESCAN, collectBindingNames, forEachAstChild, getAstName, hasRange, isAstRecord, isIdentifierNamed, mayContainDynamicImport, nodeArray };

package/dist/plugins/ast-utils.js

@@ -1,4 +1,32 @@
 //#region src/plugins/ast-utils.ts
+/**
+* Cheap pre-parse gate for plugins that only transform *dynamic* `import(...)`.
+*
+* Static imports — `import x from "..."`, `import { ... } from "..."`,
+* `import "..."` — never place a `(` (nor a comment leading to one) immediately
+* after the `import` keyword. Plugins that act only on dynamic `import(...)` use
+* this to skip `parseAst` for the overwhelming majority of modules in a large
+* app: at ~5k routes, where almost every module is a static-import-only page,
+* it removes most of the build's AST-parse/GC cost. This is a deliberate,
+* measured performance filter — keep it a regex, never a parse.
+*
+* It intentionally errs toward over-matching: a false positive costs one
+* redundant parse, whereas a false negative would silently skip a real dynamic
+* import (a correctness bug). `\s*[(/]` therefore tolerates whitespace and
+* block/line comments between the `import` keyword and its parenthesis.
+*
+* Usable directly as a Rolldown `transform.filter.code` regex, or via
+* {@link mayContainDynamicImport} for an in-handler prescan.
+*/
+const DYNAMIC_IMPORT_PRESCAN = /\bimport\s*[(/]/;
+/**
+* Whether `code` might contain a dynamic `import(...)` call. See
+* {@link DYNAMIC_IMPORT_PRESCAN} — a cheap, deliberately over-inclusive regex
+* gate used to avoid parsing static-import-only modules.
+*/
+function mayContainDynamicImport(code) {
+	return DYNAMIC_IMPORT_PRESCAN.test(code);
+}
 const SKIP_CHILD_KEYS = new Set([
 	"type",
 	"parent",
@@ -59,6 +87,9 @@ function collectBindingNames(pattern, target) {
 		case "AssignmentPattern":
 			collectBindingNames(node.left, target);
 			return;
+		case "TSParameterProperty":
+			collectBindingNames(node.parameter, target);
+			return;
 		case "ArrayPattern":
 			for (const element of nodeArray(node.elements)) collectBindingNames(element, target);
 			return;
@@ -75,4 +106,4 @@ function collectBindingNames(pattern, target) {
 	}
 }
 //#endregion
-export { collectBindingNames, forEachAstChild, getAstName, hasRange, isAstRecord, isIdentifierNamed, nodeArray };
+export { DYNAMIC_IMPORT_PRESCAN, collectBindingNames, forEachAstChild, getAstName, hasRange, isAstRecord, isIdentifierNamed, mayContainDynamicImport, nodeArray };

package/dist/plugins/css-module-imports.d.ts

@@ -0,0 +1,14 @@
+import { Plugin } from "vite";
+import MagicString from "magic-string";
+
+//#region src/plugins/css-module-imports.d.ts
+type ScriptLanguage = "js" | "jsx" | "ts" | "tsx";
+declare function rewriteCssModuleNamespaceImports(code: string, lang?: ScriptLanguage): {
+  code: string;
+  map: ReturnType<MagicString["generateMap"]>;
+} | null;
+declare function createCssModuleImportCompatibilityPlugin(options?: {
+  compiledMdx?: boolean;
+}): Plugin;
+//#endregion
+export { createCssModuleImportCompatibilityPlugin, rewriteCssModuleNamespaceImports };