@qzsy/vinext 0.1.12 → 0.1.81

package/README.md

@@ -72,7 +72,10 @@ Options: `-p / --port <port>`, `-H / --hostname <host>`, `--turbopack` (accepted
 
 `vinext deploy` options: `--preview`, `--env <name>`, `--name <name>`, `--skip-build`, `--dry-run`, `--experimental-tpr`.
 
-`vinext init` options: `--port <port>` (default: 3001), `--skip-check`, `--force`.
+`vinext init` prompts for a deployment target, defaulting to Cloudflare. Agents must ask the
+user which target they want, then pass `--platform=cloudflare` or `--platform=node`.
+
+Other options: `--port <port>` (default: 3001), `--skip-check`, `--force`.
 
 If your `next.config.*` sets `output: "standalone"`, `vinext build` emits a self-hosting bundle at `dist/standalone/`. Start it with:
 
@@ -105,7 +108,9 @@ This will:
 3. Rename CJS config files (e.g. `postcss.config.js` -> `.cjs`) to avoid ESM conflicts
 4. Add `"type": "module"` to `package.json`
 5. Add `dev:vinext`, `build:vinext`, and `start:vinext` scripts to `package.json`
-6. Generate a minimal `vite.config.ts`
+6. Prompt for a deployment platform (Cloudflare by default, or Node)
+7. Generate the matching `vite.config.ts`
+8. For Cloudflare, generate `wrangler.jsonc` and `worker/index.ts`
 
 The migration is non-destructive -- your existing Next.js setup continues to work alongside vinext. It does not modify `next.config`, `tsconfig.json`, or any source files, and it does not remove Next.js dependencies.
 
@@ -118,7 +123,10 @@ npm run start:vinext  # Start vinext production server
 npm run dev           # Still runs Next.js as before
 ```
 
-Use `--force` to overwrite an existing `vite.config.ts`, or `--skip-check` to skip the compatibility report.
+Use `--platform=cloudflare` or `--platform=node` to skip the platform prompt. Cloudflare init
+updates an existing JavaScript or TypeScript Vite config using its AST, preserving unrelated
+settings. Use `--force` to replace an existing Node-target Vite config, or `--skip-check` to skip
+the compatibility report.
 
 ## Why
 
@@ -208,7 +216,13 @@ Find your account ID in the Cloudflare dashboard URL (`dash.cloudflare.com/<acco
 
 Alternatively, set the `CLOUDFLARE_ACCOUNT_ID` environment variable instead of hardcoding it in the config file.
 
-`vinext deploy` auto-generates the necessary configuration files (`vite.config.ts`, `wrangler.jsonc`, `worker/index.ts`) if they don't exist, builds the application, and deploys to Workers.
+Run `vinext init --platform=cloudflare` first to install dependencies and create or AST-update
+`vite.config.*`, `wrangler.jsonc`, and `worker/index.ts`. `vinext deploy` then validates that setup,
+builds the application, and deploys to Workers without rewriting project configuration.
+
+Cloudflare init can also configure image optimization declaratively in the Vite config with
+`imagesOptimizer()` and add the matching Wrangler Images binding. The generated Worker entry remains a
+thin request forwarder; image optimization is not implemented or generated by `vinext deploy`.
 
 ```bash
 vinext deploy
@@ -217,7 +231,7 @@ vinext deploy --env staging
 
 Use `--env <name>` to target `wrangler.jsonc` `env.<name>`. `--preview` is shorthand for `--env preview`.
 
-The deploy command also auto-detects and fixes common migration issues:
+The init command also auto-detects and fixes common migration issues:
 
 - Adds `"type": "module"` to package.json if missing
 - Resolves tsconfig.json path aliases automatically (via `vite-tsconfig-paths`)

package/dist/build/inject-pregenerated-paths.d.ts

@@ -0,0 +1,4 @@
+//#region src/build/inject-pregenerated-paths.d.ts
+declare function injectPregeneratedConcretePaths(root: string): void;
+//#endregion
+export { injectPregeneratedConcretePaths };

package/dist/build/inject-pregenerated-paths.js

@@ -0,0 +1,18 @@
+import { escapeRegExp } from "../utils/regex.js";
+import { readPrerenderManifest } from "../server/prerender-manifest.js";
+import fs from "node:fs";
+import path from "node:path";
+//#region src/build/inject-pregenerated-paths.ts
+const VINEXT_PREGEN_START = "/* __VINEXT_PREGENERATED_CONCRETE_PATHS_START__ */";
+const VINEXT_PREGEN_END = "/* __VINEXT_PREGENERATED_CONCRETE_PATHS_END__ */";
+const VINEXT_PREGEN_RE = new RegExp(`${escapeRegExp(VINEXT_PREGEN_START)}[\\s\\S]*?${escapeRegExp(VINEXT_PREGEN_END)}\\n?`, "g");
+function injectPregeneratedConcretePaths(root) {
+	const workerEntry = path.resolve(root, "dist", "server", "index.js");
+	if (!fs.existsSync(workerEntry)) return;
+	let code = fs.readFileSync(workerEntry, "utf-8").replace(VINEXT_PREGEN_RE, "");
+	const table = readPrerenderManifest(path.join(root, "dist", "server", "vinext-prerender.json"))?.pregeneratedConcretePaths ?? [];
+	if (table.length > 0) code = `${VINEXT_PREGEN_START}\nglobalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = ${JSON.stringify(table)};\n${VINEXT_PREGEN_END}\n` + code;
+	fs.writeFileSync(workerEntry, code);
+}
+//#endregion
+export { injectPregeneratedConcretePaths };

package/dist/build/pages-client-assets-module.d.ts

@@ -0,0 +1,11 @@
+import { PagesClientAssets } from "../server/pages-client-assets.js";
+
+//#region src/build/pages-client-assets-module.d.ts
+declare const PAGES_CLIENT_ASSETS_MODULE = "vinext-client-assets.js";
+declare function buildPagesClientAssetsModule(assets: PagesClientAssets): string;
+declare function writePagesClientAssetsModuleIfMissing(outputDir: string, moduleSource: string): void;
+declare function setPagesClientAssetsBuildMetadata(buildSession: string, moduleSource: string): void;
+declare function takePagesClientAssetsBuildMetadata(buildSession: string): string | null;
+declare function clearPagesClientAssetsBuildMetadata(buildSession: string): void;
+//#endregion
+export { PAGES_CLIENT_ASSETS_MODULE, buildPagesClientAssetsModule, clearPagesClientAssetsBuildMetadata, setPagesClientAssetsBuildMetadata, takePagesClientAssetsBuildMetadata, writePagesClientAssetsModuleIfMissing };

package/dist/build/pages-client-assets-module.js

@@ -0,0 +1,27 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region src/build/pages-client-assets-module.ts
+const PAGES_CLIENT_ASSETS_MODULE = "vinext-client-assets.js";
+const pagesClientAssetsByBuildSession = /* @__PURE__ */ new Map();
+function buildPagesClientAssetsModule(assets) {
+	return `export default ${JSON.stringify(assets)};\n`;
+}
+function writePagesClientAssetsModuleIfMissing(outputDir, moduleSource) {
+	const outputPath = path.join(outputDir, PAGES_CLIENT_ASSETS_MODULE);
+	if (fs.existsSync(outputPath)) return;
+	fs.mkdirSync(outputDir, { recursive: true });
+	fs.writeFileSync(outputPath, moduleSource);
+}
+function setPagesClientAssetsBuildMetadata(buildSession, moduleSource) {
+	pagesClientAssetsByBuildSession.set(buildSession, moduleSource);
+}
+function takePagesClientAssetsBuildMetadata(buildSession) {
+	const moduleSource = pagesClientAssetsByBuildSession.get(buildSession) ?? null;
+	pagesClientAssetsByBuildSession.delete(buildSession);
+	return moduleSource;
+}
+function clearPagesClientAssetsBuildMetadata(buildSession) {
+	pagesClientAssetsByBuildSession.delete(buildSession);
+}
+//#endregion
+export { PAGES_CLIENT_ASSETS_MODULE, buildPagesClientAssetsModule, clearPagesClientAssetsBuildMetadata, setPagesClientAssetsBuildMetadata, takePagesClientAssetsBuildMetadata, writePagesClientAssetsModuleIfMissing };

package/dist/build/prerender.d.ts

@@ -22,7 +22,8 @@ type PrerenderRouteResult = {
    * Omitted for non-dynamic routes where pattern === path.
    */
   path?: string; /** Which router produced this route. Used by cache seeding. */
-  router: "app" | "pages"; /** Set to true when this is a PPR fallback shell. */
+  router: "app" | "pages"; /** Response headers that must be replayed with the prerendered artifact. */
+  headers?: Record<string, string>; /** Set to true when this is a PPR fallback shell. */
   fallback?: boolean;
 } | {
   route: string;

package/dist/build/prerender.js

@@ -1,16 +1,17 @@
 import { createValidFileMatcher, findFileWithExtensions } from "../routing/file-matcher.js";
-import { VINEXT_PRERENDER_ROUTE_PARAMS_HEADER, VINEXT_PRERENDER_SECRET_HEADER } from "../server/headers.js";
-import { normalizeStaticPathsEntry } from "../routing/route-pattern.js";
+import { VINEXT_PRERENDER_ROUTE_PARAMS_HEADER, VINEXT_PRERENDER_SECRET_HEADER } from "../utils/protocol-headers.js";
 import { NoOpCacheHandler, getCacheHandler, setCacheHandler } from "../shims/cache-handler.js";
 import { headersContextFromRequest, runWithHeadersContext } from "../shims/headers.js";
 import { _consumeRequestScopedCacheLife } from "../shims/cache-request-state.js";
+import { normalizeStaticPathsEntry } from "../routing/route-pattern.js";
 import { classifyAppRoute, classifyPagesRoute, getAppRouteRenderEntryPath } from "./report.js";
 import { BLOCKED_PAGES } from "../shims/constants.js";
+import { buildPregeneratedConcretePathTable } from "../server/prerender-manifest.js";
 import { concatUint8Arrays, decodeRscEmbeddedChunk } from "../server/app-rsc-embedded-chunks.js";
 import { navigationRuntimeRscBootstrapExpression } from "../server/app-ssr-stream.js";
-import { createAppPprFallbackShells, markAppPprDynamicFallbackShellHtml } from "../server/app-ppr-fallback-shell.js";
 import { encodePrerenderRouteParams, serializePrerenderRouteParamsHeader } from "../server/prerender-route-params.js";
 import { readPrerenderSecret } from "./server-manifest.js";
+import { createAppPprFallbackShells, markAppPprDynamicFallbackShellHtml } from "../server/app-ppr-fallback-shell.js";
 import { getOutputPath, getRscOutputPath } from "../utils/prerender-output-paths.js";
 import { startProdServer } from "../server/prod-server.js";
 import fs from "node:fs";
@@ -721,10 +722,12 @@ async function prerenderApp({ routes, metadataRoutes = [], outDir, config, mode,
 				const htmlRender = await runWithHeadersContext(headersContextFromRequest(htmlRequest), async () => {
 					const response = await rscHandler(htmlRequest);
 					const cacheControl = response.headers.get("cache-control") ?? "";
+					const linkHeader = response.headers.get("link");
 					if (!response.ok || isSpeculative && cacheControl.includes("no-store")) {
 						await response.body?.cancel();
 						return {
 							cacheControl,
+							linkHeader,
 							html: null,
 							ok: response.ok,
 							requestCacheLife: null,
@@ -733,6 +736,7 @@ async function prerenderApp({ routes, metadataRoutes = [], outDir, config, mode,
 					}
 					return {
 						cacheControl,
+						linkHeader,
 						html: await response.text(),
 						ok: true,
 						requestCacheLife: _consumeRequestScopedCacheLife(),
@@ -800,6 +804,7 @@ async function prerenderApp({ routes, metadataRoutes = [], outDir, config, mode,
 					revalidate: renderedRevalidate,
 					...typeof renderedRevalidate === "number" ? { expire: renderedCacheControl.expire } : {},
 					router: "app",
+					...htmlRender.linkHeader ? { headers: { link: htmlRender.linkHeader } } : {},
 					...urlPath !== routePattern ? { path: urlPath } : {},
 					...isFallback ? { fallback: true } : {}
 				};
@@ -907,6 +912,7 @@ function writePrerenderIndex(routes, outDir, options) {
 			revalidate: r.revalidate,
 			...typeof r.revalidate === "number" ? { expire: r.expire } : {},
 			router: r.router,
+			...r.headers ? { headers: r.headers } : {},
 			...r.path ? { path: r.path } : {},
 			...r.fallback ? { fallback: true } : {}
 		};
@@ -924,7 +930,8 @@ function writePrerenderIndex(routes, outDir, options) {
 	const index = {
 		...buildId ? { buildId } : {},
 		...typeof trailingSlash === "boolean" ? { trailingSlash } : {},
-		routes: indexRoutes
+		routes: indexRoutes,
+		pregeneratedConcretePaths: buildPregeneratedConcretePathTable({ routes: indexRoutes })
 	};
 	fs.writeFileSync(path.join(outDir, "vinext-prerender.json"), JSON.stringify(index, null, 2), "utf-8");
 }

package/dist/build/report.d.ts

@@ -121,7 +121,8 @@ declare function formatBuildReport(rows: RouteRow[], routerLabel?: string): stri
  * Scans the project at `root`, classifies all routes, and prints the
  * Next.js-style build report to stdout.
  *
- * Called at the end of `vinext build` in cli.ts.
+ * `root` must be forward-slash — it is passed to `findDir`. The caller (the
+ * `vinext build` entry in cli.ts) normalizes it.
  */
 declare function printBuildReport(options: {
   root: string;

package/dist/build/report.js

@@ -474,7 +474,8 @@ function formatBuildReport(rows, routerLabel = "app") {
 * Scans the project at `root`, classifies all routes, and prints the
 * Next.js-style build report to stdout.
 *
-* Called at the end of `vinext build` in cli.ts.
+* `root` must be forward-slash — it is passed to `findDir`. The caller (the
+* `vinext build` entry in cli.ts) normalizes it.
 */
 async function printBuildReport(options) {
 	const { root } = options;

package/dist/build/run-prerender.d.ts

@@ -56,6 +56,13 @@ type RunPrerenderOptions = {
  * `output: 'export'`. Exported for direct unit testing. Refs cloudflare/vinext#1982
  */
 declare function assertNoFatalPrerenderRoutes(routes: readonly PrerenderRouteResult[]): void;
+/**
+ * Statically generate routes and return the prerender result.
+ *
+ * `options.root` must be forward-slash — it is passed to `findDir` and flows
+ * into the route model. The caller (the `vinext build` entry in cli.ts)
+ * normalizes it.
+ */
 declare function runPrerender(options: RunPrerenderOptions): Promise<PrerenderResult | null>;
 //#endregion
 export { assertNoFatalPrerenderRoutes, runPrerender };

package/dist/build/run-prerender.js

@@ -6,6 +6,7 @@ import { loadNextConfig, resolveNextConfig } from "../config/next-config.js";
 import { readPrerenderSecret } from "./server-manifest.js";
 import { startProdServer } from "../server/prod-server.js";
 import { prerenderApp, prerenderPages, writePrerenderIndex } from "./prerender.js";
+import { injectPregeneratedConcretePaths } from "./inject-pregenerated-paths.js";
 import fs from "node:fs";
 import path from "node:path";
 //#region src/build/run-prerender.ts
@@ -95,6 +96,13 @@ function assertNoFatalPrerenderRoutes(routes) {
 	const fatalList = fatalRoutes.map((r) => `  ${r.route}: ${r.error}`).join("\n");
 	throw new Error(`Prerender failed: ${fatalRoutes.length} route${fatalRoutes.length !== 1 ? "s" : ""} errored during static generation.\n${fatalList}`);
 }
+/**
+* Statically generate routes and return the prerender result.
+*
+* `options.root` must be forward-slash — it is passed to `findDir` and flows
+* into the route model. The caller (the `vinext build` entry in cli.ts)
+* normalizes it.
+*/
 async function runPrerender(options) {
 	const { root } = options;
 	const appDir = findDir(root, "app", "src/app");
@@ -215,6 +223,7 @@ async function runPrerender(options) {
 		const errorRoutes = allRoutes.filter((r) => r.status === "error").map((r) => `  ${r.route}: ${r.error}`).join("\n");
 		throw new Error(`Static export failed: ${errors} route${errors !== 1 ? "s" : ""} cannot be statically exported.\n${errorRoutes}\n\nRemove server-side data fetching (getServerSideProps, force-dynamic, revalidate) from these routes, or remove \`output: "export"\` from next.config.js.`);
 	}
+	injectPregeneratedConcretePaths(root);
 	return {
 		routes: allRoutes,
 		...allOutputFiles.length > 0 ? { outputFiles: allOutputFiles } : {}

package/dist/build/standalone.js

@@ -167,6 +167,8 @@ function emitStandaloneOutput(options) {
 		dereference: true,
 		filter: (src) => !path.relative(serverDir, src).split(path.sep).includes("node_modules")
 	});
+	const clientAssetsSidecar = path.join(outDir, "vinext-client-assets.js");
+	if (fs.existsSync(clientAssetsSidecar)) fs.copyFileSync(clientAssetsSidecar, path.join(standaloneDistDir, "vinext-client-assets.js"));
 	const publicDir = path.join(root, "public");
 	if (fs.existsSync(publicDir)) fs.cpSync(publicDir, path.join(standaloneDir, "public"), {
 		recursive: true,

package/dist/check.d.ts

@@ -59,22 +59,40 @@ type CheckResult = {
 declare function hasFreeCjsGlobal(content: string): boolean;
 /**
  * Scan source files for `import ... from 'next/...'` statements.
+ *
+ * `root` must be forward-slash: it is passed to `findSourceFiles` (which
+ * requires it) and used as the base of `path.posix.relative`, which only yields
+ * a canonical relative path when both operands are forward-slash.
  */
 declare function scanImports(root: string): CheckItem[];
 /**
  * Analyze next.config.js/mjs/ts for supported and unsupported options.
+ *
+ * `root` must be forward-slash — joined with `path.posix.join`. Only called
+ * from `runCheck`, which normalizes it.
  */
 declare function analyzeConfig(root: string): CheckItem[];
 /**
  * Check package.json dependencies for known libraries.
+ *
+ * `root` must be forward-slash — joined with `path.posix.join`. Only called
+ * from `runCheck`, which normalizes it.
  */
 declare function checkLibraries(root: string): CheckItem[];
 /**
  * Check file conventions (pages, app directory, middleware, etc.)
+ *
+ * `root` must be forward-slash — joined with `path.posix.join`, passed to
+ * `findDir`, and used as the base of `path.posix.relative`. Only called from
+ * `runCheck`, which normalizes it.
  */
 declare function checkConventions(root: string): CheckItem[];
 /**
  * Run the full compatibility check.
+ *
+ * `root` must be forward-slash — callers normalize it at the CLI entry, and it
+ * is forwarded to `scanImports` / `checkConventions` / `findDir`, which build
+ * paths with `path.posix.*`.
  */
 declare function runCheck(root: string): CheckResult;
 /**

package/dist/check.js

@@ -1,5 +1,4 @@
 import { detectPackageManager, findDir } from "./utils/project.js";
-import { normalizePathSeparators } from "./utils/path.js";
 import fs from "node:fs";
 import path from "node:path";
 import { parseAst } from "vite";
@@ -193,7 +192,7 @@ const CONFIG_SUPPORT = {
 	env: { status: "supported" },
 	images: {
 		status: "partial",
-		detail: "remotePatterns validated, no local optimization"
+		detail: "remotePatterns validated; on-the-fly optimization via images.optimizer (Cloudflare Images), passthrough otherwise"
 	},
 	allowedDevOrigins: {
 		status: "supported",
@@ -259,6 +258,42 @@ const CONFIG_SUPPORT = {
 		status: "partial",
 		detail: "config recognized; vinext does not implement navigation result caching"
 	},
+	"experimental.middlewarePrefetch": {
+		status: "unsupported",
+		detail: "not recognized; use of this option is ignored"
+	},
+	"experimental.proxyPrefetch": {
+		status: "unsupported",
+		detail: "not recognized; use of this option is ignored"
+	},
+	"experimental.middlewareClientMaxBodySize": {
+		status: "unsupported",
+		detail: "not recognized; use of this option is ignored"
+	},
+	"experimental.proxyClientMaxBodySize": {
+		status: "unsupported",
+		detail: "not recognized; use of this option is ignored"
+	},
+	"experimental.externalMiddlewareRewritesResolve": {
+		status: "unsupported",
+		detail: "not recognized; use of this option is ignored"
+	},
+	"experimental.externalProxyRewritesResolve": {
+		status: "unsupported",
+		detail: "not recognized; use of this option is ignored"
+	},
+	"experimental.instrumentationHook": {
+		status: "unsupported",
+		detail: "not recognized; instrumentation files are enabled automatically"
+	},
+	skipMiddlewareUrlNormalize: {
+		status: "unsupported",
+		detail: "not recognized; use of this option is ignored"
+	},
+	skipProxyUrlNormalize: {
+		status: "unsupported",
+		detail: "not recognized; use of this option is ignored"
+	},
 	"i18n.domains": {
 		status: "partial",
 		detail: "supported for Pages Router; App Router unchanged"
@@ -331,6 +366,11 @@ const LIBRARY_SUPPORT = {
 };
 /**
 * Recursively find all source files in a directory.
+*
+* `dir` must be forward-slash, and the returned paths are forward-slash too:
+* each entry is joined with `path.posix.join`, which only stays canonical when
+* the base already is. This keeps downstream substring checks (e.g.
+* `f.includes("/api/")`) and reported paths consistent across platforms.
 */
 function findSourceFiles(dir, extensions = [
 	".ts",
@@ -343,7 +383,7 @@ function findSourceFiles(dir, extensions = [
 	if (!fs.existsSync(dir)) return results;
 	const entries = fs.readdirSync(dir, { withFileTypes: true });
 	for (const entry of entries) {
-		const fullPath = normalizePathSeparators(path.join(dir, entry.name));
+		const fullPath = path.posix.join(dir, entry.name);
 		if (entry.isDirectory()) {
 			if (entry.name === "node_modules" || entry.name === ".next" || entry.name === "dist" || entry.name === ".git") continue;
 			results.push(...findSourceFiles(fullPath, extensions));
@@ -547,6 +587,10 @@ function hasFreeCjsGlobal(content) {
 }
 /**
 * Scan source files for `import ... from 'next/...'` statements.
+*
+* `root` must be forward-slash: it is passed to `findSourceFiles` (which
+* requires it) and used as the base of `path.posix.relative`, which only yields
+* a canonical relative path when both operands are forward-slash.
 */
 function scanImports(root) {
 	const files = findSourceFiles(root);
@@ -564,7 +608,7 @@ function scanImports(root) {
 			if (mod.startsWith("next/") || mod === "next" || mod === "server-only" || mod === "client-only") {
 				const normalized = mod === "next" ? "next" : mod;
 				if (!importUsage.has(normalized)) importUsage.set(normalized, []);
-				const relFile = normalizePathSeparators(path.relative(root, file));
+				const relFile = path.posix.relative(root, file);
 				const usedInFiles = importUsage.get(normalized) ?? [];
 				if (!usedInFiles.includes(relFile)) usedInFiles.push(relFile);
 			}
@@ -691,6 +735,9 @@ function collectConfigKeys(source) {
 }
 /**
 * Analyze next.config.js/mjs/ts for supported and unsupported options.
+*
+* `root` must be forward-slash — joined with `path.posix.join`. Only called
+* from `runCheck`, which normalizes it.
 */
 function analyzeConfig(root) {
 	const configFiles = [
@@ -702,7 +749,7 @@ function analyzeConfig(root) {
 	];
 	let configPath = null;
 	for (const f of configFiles) {
-		const p = path.join(root, f);
+		const p = path.posix.join(root, f);
 		if (fs.existsSync(p)) {
 			configPath = p;
 			break;
@@ -729,7 +776,9 @@ function analyzeConfig(root) {
 		"transpilePackages",
 		"webpack",
 		"reactStrictMode",
-		"poweredByHeader"
+		"poweredByHeader",
+		"skipMiddlewareUrlNormalize",
+		"skipProxyUrlNormalize"
 	]) {
 		if (!present.top.has(opt)) continue;
 		const support = CONFIG_SUPPORT[opt];
@@ -757,9 +806,12 @@ function analyzeConfig(root) {
 }
 /**
 * Check package.json dependencies for known libraries.
+*
+* `root` must be forward-slash — joined with `path.posix.join`. Only called
+* from `runCheck`, which normalizes it.
 */
 function checkLibraries(root) {
-	const pkgPath = path.join(root, "package.json");
+	const pkgPath = path.posix.join(root, "package.json");
 	if (!fs.existsSync(pkgPath)) return [];
 	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
 	const allDeps = {
@@ -777,17 +829,19 @@ function checkLibraries(root) {
 }
 /**
 * Check file conventions (pages, app directory, middleware, etc.)
+*
+* `root` must be forward-slash — joined with `path.posix.join`, passed to
+* `findDir`, and used as the base of `path.posix.relative`. Only called from
+* `runCheck`, which normalizes it.
 */
 function checkConventions(root) {
 	const items = [];
-	const pagesDir = findDir(root, "pages", path.join("src", "pages"));
-	const appDirPath = findDir(root, "app", path.join("src", "app"));
-	const hasPages = pagesDir !== null;
-	const hasApp = appDirPath !== null;
-	const hasProxy = fs.existsSync(path.join(root, "proxy.ts")) || fs.existsSync(path.join(root, "proxy.js"));
-	const hasMiddleware = fs.existsSync(path.join(root, "middleware.ts")) || fs.existsSync(path.join(root, "middleware.js"));
+	const pagesDir = findDir(root, "pages", "src/pages");
+	const appDirPath = findDir(root, "app", "src/app");
+	const hasProxy = fs.existsSync(path.posix.join(root, "proxy.ts")) || fs.existsSync(path.posix.join(root, "proxy.js"));
+	const hasMiddleware = fs.existsSync(path.posix.join(root, "middleware.ts")) || fs.existsSync(path.posix.join(root, "middleware.js"));
 	if (pagesDir !== null) {
-		const isSrc = pagesDir.includes(path.join("src", "pages"));
+		const isSrc = pagesDir.includes("src/pages");
 		items.push({
 			name: isSrc ? "Pages Router (src/pages/)" : "Pages Router (pages/)",
 			status: "supported"
@@ -813,7 +867,7 @@ function checkConventions(root) {
 		});
 	}
 	if (appDirPath !== null) {
-		const isSrc = appDirPath.includes(path.join("src", "app"));
+		const isSrc = appDirPath.includes("src/app");
 		items.push({
 			name: isSrc ? "App Router (src/app/)" : "App Router (app/)",
 			status: "supported"
@@ -858,12 +912,12 @@ function checkConventions(root) {
 		name: "middleware.ts (deprecated in Next.js 16)",
 		status: "supported"
 	});
-	if (!hasPages && !hasApp) items.push({
+	if (pagesDir === null && appDirPath === null) items.push({
 		name: "No pages/ or app/ directory found",
 		status: "unsupported",
 		detail: "vinext requires a pages/ or app/ directory"
 	});
-	const pkgPath = path.join(root, "package.json");
+	const pkgPath = path.posix.join(root, "package.json");
 	if (fs.existsSync(pkgPath)) {
 		if (JSON.parse(fs.readFileSync(pkgPath, "utf-8")).type !== "module") items.push({
 			name: "Missing \"type\": \"module\" in package.json",
@@ -877,7 +931,7 @@ function checkConventions(root) {
 	const cjsGlobalFiles = [];
 	for (const file of allSourceFiles) {
 		const content = fs.readFileSync(file, "utf-8");
-		const rel = normalizePathSeparators(path.relative(root, file));
+		const rel = path.posix.relative(root, file);
 		if (viewTransitionRegex.test(content)) viewTransitionFiles.push(rel);
 		if (hasFreeCjsGlobal(content)) cjsGlobalFiles.push(rel);
 	}
@@ -892,7 +946,7 @@ function checkConventions(root) {
 		"postcss.config.js",
 		"postcss.config.cjs"
 	]) {
-		const configPath = path.join(root, configFile);
+		const configPath = path.posix.join(root, configFile);
 		if (fs.existsSync(configPath)) {
 			const content = fs.readFileSync(configPath, "utf-8");
 			if (/plugins\s*:\s*\[\s*['"]/.test(content)) items.push({
@@ -913,6 +967,10 @@ function checkConventions(root) {
 }
 /**
 * Run the full compatibility check.
+*
+* `root` must be forward-slash — callers normalize it at the CLI entry, and it
+* is forwarded to `scanImports` / `checkConventions` / `findDir`, which build
+* paths with `path.posix.*`.
 */
 function runCheck(root) {
 	const imports = scanImports(root);

package/dist/cli-dev-config.d.ts

@@ -0,0 +1,12 @@
+import { Plugin, ServerOptions } from "vite";
+
+//#region src/cli-dev-config.d.ts
+type DevServerCliOptions = {
+  port?: number;
+  hostname?: string;
+};
+declare function applyDevServerDefaults(server: ServerOptions, options: DevServerCliOptions): void;
+declare function createDevServerConfigPlugin(options: DevServerCliOptions): Plugin;
+declare function normalizeDevServerHostname(host: string | boolean | undefined): string;
+//#endregion
+export { DevServerCliOptions, applyDevServerDefaults, createDevServerConfigPlugin, normalizeDevServerHostname };

package/dist/cli-dev-config.js

@@ -0,0 +1,23 @@
+//#region src/cli-dev-config.ts
+function applyDevServerDefaults(server, options) {
+	server.port = options.port ?? server.port ?? 3e3;
+	server.host = options.hostname ?? server.host ?? "localhost";
+}
+function createDevServerConfigPlugin(options) {
+	return {
+		name: "vinext:dev-server-config",
+		enforce: "post",
+		config: {
+			order: "post",
+			handler(config) {
+				applyDevServerDefaults(config.server ??= {}, options);
+			}
+		}
+	};
+}
+function normalizeDevServerHostname(host) {
+	if (typeof host === "string") return host;
+	return host === true ? "0.0.0.0" : "localhost";
+}
+//#endregion
+export { applyDevServerDefaults, createDevServerConfigPlugin, normalizeDevServerHostname };