@qzsy/vinext 0.1.7

package/dist/build/standalone.d.ts

@@ -0,0 +1,31 @@
+//#region src/build/standalone.d.ts
+type StandaloneBuildOptions = {
+  root: string;
+  outDir: string;
+  /**
+   * Test hook: override vinext package root used for embedding runtime files.
+   */
+  vinextPackageRoot?: string;
+};
+type StandaloneBuildResult = {
+  standaloneDir: string;
+  copiedPackages: string[];
+};
+/**
+ * Emit standalone production output for self-hosted deployments.
+ *
+ * Creates:
+ * - <outDir>/standalone/server.js
+ * - <outDir>/standalone/dist/{client,server}
+ * - <outDir>/standalone/node_modules (runtime deps only)
+ *
+ * The set of packages copied into node_modules/ is determined by
+ * `dist/server/vinext-externals.json`, which is written by the
+ * `vinext:server-externals-manifest` Vite plugin during the production build.
+ * It contains exactly the packages the server bundle imports at runtime
+ * (i.e. those left external by the bundler), so no client-only deps are
+ * included.
+ */
+declare function emitStandaloneOutput(options: StandaloneBuildOptions): StandaloneBuildResult;
+//#endregion
+export { emitStandaloneOutput };

package/dist/build/standalone.js

@@ -0,0 +1,203 @@
+import { readJsonFile } from "../utils/safe-json-file.js";
+import { resolveVinextPackageRoot } from "../utils/vinext-root.js";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+//#region src/build/standalone.ts
+function readPackageJson(packageJsonPath) {
+	return JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+}
+/** Returns both `dependencies` and `optionalDependencies` keys — the full set of potential runtime deps. */
+function runtimeDeps(pkg) {
+	return Object.keys({
+		...pkg.dependencies,
+		...pkg.optionalDependencies
+	});
+}
+/**
+* Read the externals manifest written by the `vinext:server-externals-manifest`
+* Vite plugin during the production build.
+*
+* The manifest (`dist/server/vinext-externals.json`) contains the exact set of
+* npm packages that the bundler left external in the SSR/RSC output — i.e.
+* packages that the server bundle actually imports at runtime. Using this
+* instead of scanning emitted files with regexes or seeding from
+* `package.json#dependencies` avoids both false negatives (missed imports) and
+* false positives (client-only deps that are never loaded server-side).
+*
+* Falls back to an empty array if the manifest does not exist (e.g. when
+* running against a build that predates this feature).
+*/
+function readServerExternalsManifest(serverDir) {
+	const manifestPath = path.join(serverDir, "vinext-externals.json");
+	if (!fs.existsSync(manifestPath)) return [];
+	return readJsonFile(manifestPath, { onError: (err) => {
+		console.warn(`[vinext] Warning: failed to parse ${manifestPath}, proceeding without externals manifest: ${String(err)}`);
+	} }) ?? [];
+}
+function resolvePackageJsonPath(packageName, resolver) {
+	try {
+		return resolver.resolve(`${packageName}/package.json`);
+	} catch {
+		const lookupPaths = resolver.resolve.paths(packageName) ?? [];
+		for (const lookupPath of lookupPaths) {
+			const candidate = path.join(lookupPath, packageName, "package.json");
+			if (fs.existsSync(candidate)) {
+				if (readPackageJson(candidate).name === packageName) return candidate;
+			}
+		}
+		try {
+			const entryPath = resolver.resolve(packageName);
+			let dir = path.dirname(entryPath);
+			while (dir !== path.dirname(dir)) {
+				const candidate = path.join(dir, "package.json");
+				if (fs.existsSync(candidate)) {
+					if (readPackageJson(candidate).name === packageName) return candidate;
+				}
+				dir = path.dirname(dir);
+			}
+		} catch {}
+		return null;
+	}
+}
+function copyPackageAndRuntimeDeps(root, targetNodeModulesDir, initialPackages, alreadyCopied) {
+	const rootResolver = createRequire(path.join(root, "package.json"));
+	const rootPkg = readPackageJson(path.join(root, "package.json"));
+	const rootOptional = new Set(Object.keys(rootPkg.optionalDependencies ?? {}));
+	const copied = alreadyCopied ?? /* @__PURE__ */ new Set();
+	const queue = initialPackages.map((packageName) => ({
+		packageName,
+		resolver: rootResolver,
+		optional: rootOptional.has(packageName)
+	}));
+	while (queue.length > 0) {
+		const entry = queue.shift();
+		if (!entry) continue;
+		if (copied.has(entry.packageName)) continue;
+		const packageJsonPath = resolvePackageJsonPath(entry.packageName, entry.resolver);
+		if (!packageJsonPath) {
+			if (entry.optional) continue;
+			throw new Error(`Failed to resolve required runtime dependency "${entry.packageName}" for standalone output`);
+		}
+		const realPackageJsonPath = fs.realpathSync(packageJsonPath);
+		const packageRoot = path.dirname(realPackageJsonPath);
+		const packageTarget = path.join(targetNodeModulesDir, entry.packageName);
+		fs.mkdirSync(path.dirname(packageTarget), { recursive: true });
+		fs.cpSync(packageRoot, packageTarget, {
+			recursive: true,
+			dereference: true,
+			filter: (src) => {
+				return !path.relative(packageRoot, src).split(path.sep).includes("node_modules");
+			}
+		});
+		copied.add(entry.packageName);
+		const packageResolver = createRequire(realPackageJsonPath);
+		const pkg = readPackageJson(realPackageJsonPath);
+		const optionalDeps = new Set(Object.keys(pkg.optionalDependencies ?? {}));
+		for (const depName of runtimeDeps(pkg)) if (!copied.has(depName)) queue.push({
+			packageName: depName,
+			resolver: packageResolver,
+			optional: optionalDeps.has(depName)
+		});
+	}
+	return [...copied];
+}
+function writeStandaloneServerEntry(filePath) {
+	fs.writeFileSync(filePath, `#!/usr/bin/env node
+import { join } from "node:path";
+import { startProdServer } from "vinext/server/prod-server";
+
+const port = Number.parseInt(process.env.PORT ?? "3000", 10);
+const host = process.env.HOST ?? "0.0.0.0";
+
+startProdServer({
+  port,
+  host,
+  outDir: join(import.meta.dirname, "dist"),
+}).catch((error) => {
+  console.error("[vinext] Failed to start standalone server");
+  console.error(error);
+  process.exit(1);
+});
+`, "utf-8");
+	fs.chmodSync(filePath, 493);
+}
+function writeStandalonePackageJson(filePath) {
+	fs.writeFileSync(filePath, JSON.stringify({
+		private: true,
+		type: "module"
+	}, null, 2) + "\n", "utf-8");
+}
+/**
+* Emit standalone production output for self-hosted deployments.
+*
+* Creates:
+* - <outDir>/standalone/server.js
+* - <outDir>/standalone/dist/{client,server}
+* - <outDir>/standalone/node_modules (runtime deps only)
+*
+* The set of packages copied into node_modules/ is determined by
+* `dist/server/vinext-externals.json`, which is written by the
+* `vinext:server-externals-manifest` Vite plugin during the production build.
+* It contains exactly the packages the server bundle imports at runtime
+* (i.e. those left external by the bundler), so no client-only deps are
+* included.
+*/
+function emitStandaloneOutput(options) {
+	const root = path.resolve(options.root);
+	const outDir = path.resolve(options.outDir);
+	const clientDir = path.join(outDir, "client");
+	const serverDir = path.join(outDir, "server");
+	if (!fs.existsSync(clientDir) || !fs.existsSync(serverDir)) throw new Error(`No build output found in ${outDir}. Run vinext build first.`);
+	const standaloneDir = path.join(outDir, "standalone");
+	const standaloneDistDir = path.join(standaloneDir, "dist");
+	const standaloneNodeModulesDir = path.join(standaloneDir, "node_modules");
+	fs.rmSync(standaloneDir, {
+		recursive: true,
+		force: true
+	});
+	fs.mkdirSync(standaloneDistDir, { recursive: true });
+	fs.cpSync(clientDir, path.join(standaloneDistDir, "client"), {
+		recursive: true,
+		dereference: true,
+		filter: (src) => !path.relative(clientDir, src).split(path.sep).includes("node_modules")
+	});
+	fs.cpSync(serverDir, path.join(standaloneDistDir, "server"), {
+		recursive: true,
+		dereference: true,
+		filter: (src) => !path.relative(serverDir, src).split(path.sep).includes("node_modules")
+	});
+	const publicDir = path.join(root, "public");
+	if (fs.existsSync(publicDir)) fs.cpSync(publicDir, path.join(standaloneDir, "public"), {
+		recursive: true,
+		dereference: true,
+		filter: (src) => !path.relative(publicDir, src).split(path.sep).includes("node_modules")
+	});
+	fs.mkdirSync(standaloneNodeModulesDir, { recursive: true });
+	const initialPackages = readServerExternalsManifest(serverDir).filter((name) => name !== "vinext");
+	const copiedSet = /* @__PURE__ */ new Set();
+	copyPackageAndRuntimeDeps(root, standaloneNodeModulesDir, initialPackages, copiedSet);
+	const vinextPackageRoot = resolveVinextPackageRoot(options.vinextPackageRoot);
+	const vinextDistDir = path.join(vinextPackageRoot, "dist");
+	if (!fs.existsSync(vinextDistDir)) throw new Error(`vinext runtime dist/ not found at ${vinextPackageRoot}`);
+	const vinextTargetDir = path.join(standaloneNodeModulesDir, "vinext");
+	fs.mkdirSync(vinextTargetDir, { recursive: true });
+	fs.copyFileSync(path.join(vinextPackageRoot, "package.json"), path.join(vinextTargetDir, "package.json"));
+	fs.cpSync(vinextDistDir, path.join(vinextTargetDir, "dist"), {
+		recursive: true,
+		dereference: true,
+		filter: (src) => {
+			return !path.relative(vinextDistDir, src).split(path.sep).includes("node_modules");
+		}
+	});
+	copiedSet.add("vinext");
+	copyPackageAndRuntimeDeps(vinextPackageRoot, standaloneNodeModulesDir, runtimeDeps(readPackageJson(path.join(vinextPackageRoot, "package.json"))).filter((name) => !copiedSet.has(name)), copiedSet);
+	writeStandaloneServerEntry(path.join(standaloneDir, "server.js"));
+	writeStandalonePackageJson(path.join(standaloneDir, "package.json"));
+	return {
+		standaloneDir,
+		copiedPackages: [...copiedSet]
+	};
+}
+//#endregion
+export { emitStandaloneOutput };

package/dist/build/static-export.d.ts

@@ -0,0 +1,55 @@
+import { ResolvedNextConfig } from "../config/next-config.js";
+import { Route } from "../routing/pages-router.js";
+import { AppRoute } from "../routing/app-route-graph.js";
+
+//#region src/build/static-export.d.ts
+type StaticExportOptions = {
+  /**
+   * Absolute path to the pre-built Pages Router server bundle
+   * (e.g. `dist/server/entry.js`).
+   */
+  pagesBundlePath: string; /** Discovered page routes (excludes API routes) */
+  routes: Route[]; /** Discovered API routes */
+  apiRoutes: Route[]; /** Pages directory path */
+  pagesDir: string; /** Output directory for static files */
+  outDir: string; /** Resolved next.config.js */
+  config: ResolvedNextConfig;
+};
+type StaticExportResult = {
+  /** Number of HTML files generated */pageCount: number; /** Generated file paths (relative to outDir) */
+  files: string[]; /** Warnings encountered */
+  warnings: string[]; /** Errors encountered (non-fatal, specific pages) */
+  errors: Array<{
+    route: string;
+    error: string;
+  }>;
+};
+/**
+ * Run static export for Pages Router.
+ *
+ * Delegates to `prerenderPages()` in export mode.
+ */
+declare function staticExportPages(options: StaticExportOptions): Promise<StaticExportResult>;
+type AppStaticExportOptions = {
+  /** Discovered app routes */routes: AppRoute[];
+  /**
+   * App directory path. When provided, static export scans it for file-based
+   * metadata assets such as icon.png and sitemap.xml.
+   */
+  appDir?: string;
+  /**
+   * Absolute path to the pre-built RSC handler bundle
+   * (e.g. `dist/server/index.js`).
+   */
+  rscBundlePath: string; /** Output directory */
+  outDir: string; /** Resolved next.config.js */
+  config: ResolvedNextConfig;
+};
+/**
+ * Run static export for App Router.
+ *
+ * Delegates to `prerenderApp()` in export mode.
+ */
+declare function staticExportApp(options: AppStaticExportOptions): Promise<StaticExportResult>;
+//#endregion
+export { AppStaticExportOptions, StaticExportOptions, StaticExportResult, staticExportApp, staticExportPages };

package/dist/build/static-export.js

@@ -0,0 +1,60 @@
+import { scanMetadataFiles } from "../server/metadata-routes.js";
+import { prerenderApp, prerenderPages } from "./prerender.js";
+//#region src/build/static-export.ts
+/**
+* Convert a `PrerenderResult` into the legacy `StaticExportResult` shape.
+*/
+function toStaticExportResult(routes, extraOutputFiles = []) {
+	const result = {
+		pageCount: 0,
+		files: [],
+		warnings: [],
+		errors: []
+	};
+	for (const r of routes) if (r.status === "rendered") {
+		result.pageCount++;
+		result.files.push(...r.outputFiles.filter((f) => f.endsWith(".html")));
+	} else if (r.status === "skipped") {
+		if (r.reason === "api") result.warnings.push(`API route ${r.route} skipped — API routes are not supported with output: 'export'`);
+	} else if (r.status === "error") result.errors.push({
+		route: r.route,
+		error: r.error
+	});
+	result.files.push(...extraOutputFiles);
+	return result;
+}
+/**
+* Run static export for Pages Router.
+*
+* Delegates to `prerenderPages()` in export mode.
+*/
+async function staticExportPages(options) {
+	return toStaticExportResult((await prerenderPages({
+		mode: "export",
+		pagesBundlePath: options.pagesBundlePath,
+		routes: options.routes,
+		apiRoutes: options.apiRoutes,
+		pagesDir: options.pagesDir,
+		outDir: options.outDir,
+		config: options.config
+	})).routes);
+}
+/**
+* Run static export for App Router.
+*
+* Delegates to `prerenderApp()` in export mode.
+*/
+async function staticExportApp(options) {
+	const metadataRoutes = options.appDir ? scanMetadataFiles(options.appDir) : [];
+	const result = await prerenderApp({
+		mode: "export",
+		rscBundlePath: options.rscBundlePath,
+		routes: options.routes,
+		metadataRoutes,
+		outDir: options.outDir,
+		config: options.config
+	});
+	return toStaticExportResult(result.routes, result.outputFiles);
+}
+//#endregion
+export { staticExportApp, staticExportPages };

package/dist/cache/cache-adapters-virtual.d.ts

@@ -0,0 +1,50 @@
+//#region src/cache/cache-adapters-virtual.d.ts
+/**
+ * Code generation for the `virtual:vinext-cache-adapters` module, resolved by
+ * the vinext vite plugin from the user's `cache` config ({@link VinextCacheConfig}).
+ *
+ * The generated module exports `registerConfiguredCacheAdapters(env)`, which the
+ * server entries call on each request. It self-guards (adapters instantiate once
+ * per isolate) and is a no-op when nothing is configured. Registration is
+ * resilient: a factory that throws (e.g. a KV adapter on the Node.js server,
+ * where the binding can't exist) is logged and skipped rather than failing every
+ * request, so the same config can be registered from every runtime/router entry.
+ *
+ * Descriptor `options` are inlined into the generated module and forwarded to the
+ * factory at runtime, so a config-time builder like `kvDataAdapter({ binding })`
+ * never touches the Workers runtime — instantiation is deferred to the first
+ * request.
+ */
+/**
+ * A serializable pointer to a cache adapter module — the shape of each `cache`
+ * slot in the vinext() plugin config. Produced by an adapter builder (e.g.
+ * `kvDataAdapter(...)` from `@vinext/cloudflare/cache/kv-data-adapter`) or written
+ * by hand. `options` must be JSON-serializable: it is inlined into the generated
+ * registration module and forwarded to the adapter factory at runtime.
+ */
+type CacheAdapterDescriptor<O extends Record<string, unknown> = Record<string, unknown>> = {
+  /**
+   * Module specifier (or absolute path, e.g. from `require.resolve(...)`) whose
+   * default export is a cache adapter factory.
+   */
+  adapter: string; /** JSON-serializable options forwarded to the factory at runtime. */
+  options?: O;
+};
+/**
+ * The `cache` option of the vinext() plugin: declaratively register cache
+ * handlers instead of calling `setDataCacheHandler()` / `setCdnCacheAdapter()`
+ * from a worker entry.
+ */
+type VinextCacheConfig = {
+  /** Page-level ISR serving strategy (CDN cache adapter). */cdn?: CacheAdapterDescriptor; /** Data cache (fetch / `"use cache"` / `unstable_cache`) handler. */
+  data?: CacheAdapterDescriptor;
+};
+/** Public virtual module id imported by the server entries. */
+declare const VIRTUAL_CACHE_ADAPTERS = "virtual:vinext-cache-adapters";
+/**
+ * Generate the source of the `virtual:vinext-cache-adapters` module for the
+ * given config. Always exports `registerConfiguredCacheAdapters(env)`.
+ */
+declare function generateCacheAdaptersModule(cache?: VinextCacheConfig): string;
+//#endregion
+export { VIRTUAL_CACHE_ADAPTERS, VinextCacheConfig, generateCacheAdaptersModule };

package/dist/cache/cache-adapters-virtual.js

@@ -0,0 +1,45 @@
+//#region src/cache/cache-adapters-virtual.ts
+/** Public virtual module id imported by the server entries. */
+const VIRTUAL_CACHE_ADAPTERS = "virtual:vinext-cache-adapters";
+/**
+* Serialize descriptor options into a JS expression for inlining. Plain JSON is
+* a valid JS literal; `undefined` when there are no options. Throws a clear
+* config-time error (not a runtime one) if options are not serializable.
+*/
+function inlineOptions(adapter, options) {
+	if (options === void 0) return "undefined";
+	try {
+		return JSON.stringify(options);
+	} catch (cause) {
+		throw new Error(`[vinext] cache adapter "${adapter}" options must be JSON-serializable.`, { cause });
+	}
+}
+/**
+* Generate the source of the `virtual:vinext-cache-adapters` module for the
+* given config. Always exports `registerConfiguredCacheAdapters(env)`.
+*/
+function generateCacheAdaptersModule(cache) {
+	const data = cache?.data;
+	const cdn = cache?.cdn;
+	if (!data?.adapter && !cdn?.adapter) return [
+		"// vinext: no cache.cdn/cache.data adapter configured — registration is a no-op.",
+		"export function registerConfiguredCacheAdapters() {}",
+		""
+	].join("\n");
+	const lines = ["// vinext: generated from the `cache` option in your vinext() plugin config."];
+	if (data?.adapter) {
+		lines.push(`import __vinextDataAdapterFactory from ${JSON.stringify(data.adapter)};`);
+		lines.push(`import { setDataCacheHandler } from "vinext/shims/cache-handler";`);
+	}
+	if (cdn?.adapter) {
+		lines.push(`import __vinextCdnAdapterFactory from ${JSON.stringify(cdn.adapter)};`);
+		lines.push(`import { setCdnCacheAdapter } from "vinext/shims/cdn-cache";`);
+	}
+	lines.push("", "// A factory that throws (e.g. a missing binding on an incompatible runtime)", "// is logged and skipped so the default handler stays in place.", "let __vinextCacheAdaptersRegistered = false;", "", "export function registerConfiguredCacheAdapters(env) {", "  if (__vinextCacheAdaptersRegistered) return;", "  __vinextCacheAdaptersRegistered = true;");
+	if (data?.adapter) lines.push("  try {", `    setDataCacheHandler(__vinextDataAdapterFactory({ env, options: ${inlineOptions(data.adapter, data.options)} }));`, "  } catch (error) {", "    console.warn(\"[vinext] failed to initialize the configured data cache adapter; using the default handler.\", error);", "  }");
+	if (cdn?.adapter) lines.push("  try {", `    setCdnCacheAdapter(__vinextCdnAdapterFactory({ env, options: ${inlineOptions(cdn.adapter, cdn.options)} }));`, "  } catch (error) {", "    console.warn(\"[vinext] failed to initialize the configured CDN cache adapter; using the default adapter.\", error);", "  }");
+	lines.push("}", "");
+	return lines.join("\n");
+}
+//#endregion
+export { VIRTUAL_CACHE_ADAPTERS, generateCacheAdaptersModule };

package/dist/cache.d.ts

@@ -0,0 +1,2 @@
+import { cacheForRequest } from "./shims/cache-for-request.js";
+export { cacheForRequest };

package/dist/cache.js

@@ -0,0 +1,2 @@
+import { cacheForRequest } from "./shims/cache-for-request.js";
+export { cacheForRequest };

package/dist/check.d.ts

@@ -0,0 +1,87 @@
+//#region src/check.d.ts
+/**
+ * vinext check — compatibility scanner for Next.js apps
+ *
+ * Scans an existing Next.js app and produces a compatibility report
+ * showing what will work, what needs changes, and an overall score.
+ */
+type Status = "supported" | "partial" | "unsupported";
+type CheckItem = {
+  name: string;
+  status: Status;
+  detail?: string;
+  files?: string[];
+};
+type CheckResult = {
+  imports: CheckItem[];
+  config: CheckItem[];
+  libraries: CheckItem[];
+  conventions: CheckItem[];
+  summary: {
+    supported: number;
+    partial: number;
+    unsupported: number;
+    total: number;
+    score: number;
+  };
+};
+/**
+ * Report whether `content` makes a free use of the CommonJS globals `__dirname` or
+ * `__filename` in real code — i.e. not inside a string literal, comment, regex
+ * literal, or plain template literal. Identifiers inside a template expression
+ * (`` `${__dirname}` ``) DO count, since that is real code.
+ *
+ * This is a hand-written single-pass scanner rather than a regex on purpose. The
+ * previous implementation used an alternation regex whose string-body sub-pattern
+ * `(?:[^"\\]|\\.)*` is a star over an alternation group; V8 cannot compile that into
+ * a tight loop, so it pushes one backtrack frame per character and overflows the
+ * regex stack ("Maximum call stack size exceeded") on very large files — e.g. a
+ * multi-megabyte minified bundle or a long/unterminated string literal. This scanner
+ * runs in O(n) time and O(template-nesting) stack, so it cannot blow up on large input.
+ *
+ * It is a lexer-grade scanner, not a parser: it tracks just enough state (string /
+ * template / comment / regex contexts, and whether a `/` is in expression position)
+ * to avoid mistaking quotes inside one context for the start of another. Where the
+ * division-vs-regex distinction is ambiguous it biases toward division, because a
+ * misread division is usually harmless (it never consumes a following identifier)
+ * whereas a misread regex would swallow the rest of the line and could hide a later
+ * __dirname.
+ *
+ * Known limitation: telling a value-position regex literal apart from division after
+ * a `}` needs real parser context (was the `}` a block or an object?). We bias to
+ * division, so a regex used in value position — e.g. a statement-start regex after a
+ * block `}`, like `function f(){} /'/.test(x)` — is read as division; if its body
+ * contains an unpaired quote/backtick, that quote opens a string that can mask a
+ * __dirname *on the same line*. This is rare in hand-written source, the multi-line
+ * case is unaffected (string scanning stops at the newline), and the check is only
+ * advisory — so we accept it rather than pull in a full parser.
+ */
+declare function hasFreeCjsGlobal(content: string): boolean;
+/**
+ * Scan source files for `import ... from 'next/...'` statements.
+ */
+declare function scanImports(root: string): CheckItem[];
+/**
+ * Analyze next.config.js/mjs/ts for supported and unsupported options.
+ */
+declare function analyzeConfig(root: string): CheckItem[];
+/**
+ * Check package.json dependencies for known libraries.
+ */
+declare function checkLibraries(root: string): CheckItem[];
+/**
+ * Check file conventions (pages, app directory, middleware, etc.)
+ */
+declare function checkConventions(root: string): CheckItem[];
+/**
+ * Run the full compatibility check.
+ */
+declare function runCheck(root: string): CheckResult;
+/**
+ * Format the check result as a colored terminal report.
+ */
+declare function formatReport(result: CheckResult, opts?: {
+  calledFromInit?: boolean;
+}): string;
+//#endregion
+export { CheckResult, analyzeConfig, checkConventions, checkLibraries, formatReport, hasFreeCjsGlobal, runCheck, scanImports };