@thomas.f/prnext 0.1.16-alpha → 0.1.18-alpha

package/build/compilation-store.mjs

@@ -0,0 +1,142 @@
+// Optional content-addressed compilation outputs. Records contain metadata and
+// references only; binary output bytes are shared across compilation graphs.
+import { constants } from 'node:fs';
+import { open, lstat, rename, unlink, readdir } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { serialize, deserialize } from 'node:v8';
+import { deflateRaw, inflateRaw } from 'node:zlib';
+import { promisify } from 'node:util';
+import path from 'node:path';
+import { cacheHash } from './persistent-cache.mjs';
+
+const compress = promisify(deflateRaw), decompress = promisify(inflateRaw);
+const MAGIC = Buffer.from('PRNG2\0');
+const HEADER = MAGIC.length + 1 + 4 + 32;
+const MAX_BLOB = 16 * 1024 * 1024, MAX_RECORD = 16 * 1024 * 1024;
+const MAX_DISK = 64 * 1024 * 1024, MAX_SCAN = 8192, MAX_RECORDS = 1024;
+const digest = /^[a-f0-9]{64}$/;
+const namePattern = /^([a-f0-9]{64})\.(graph|blob)$/;
+
+async function encode(bytes) {
+  let payload = bytes, codec = 0;
+  if (bytes.length >= 16384) {
+    const packed = await compress(bytes, { level: 1 });
+    if (packed.length < bytes.length * 0.9) { payload = packed; codec = 1; }
+  }
+  const header = Buffer.alloc(HEADER);
+  MAGIC.copy(header); header[MAGIC.length] = codec;
+  header.writeUInt32BE(bytes.length, MAGIC.length + 1);
+  Buffer.from(cacheHash(bytes), 'hex').copy(header, MAGIC.length + 5);
+  return [header, payload];
+}
+
+async function read(directory, name, limit) {
+  let file;
+  try {
+    const filename = path.join(directory, name), info = await lstat(filename);
+    if (!info.isFile() || info.isSymbolicLink() || info.size > limit + HEADER || info.size < HEADER) return null;
+    file = await open(filename, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.size > limit + HEADER) return null;
+    const packed = await file.readFile();
+    if (!packed.subarray(0, MAGIC.length).equals(MAGIC)) return null;
+    const size = packed.readUInt32BE(MAGIC.length + 1), codec = packed[MAGIC.length];
+    if (size > limit || codec > 1) return null;
+    const payload = packed.subarray(HEADER);
+    const bytes = codec ? await decompress(payload, { maxOutputLength: Math.max(1, size) }) : payload;
+    if (bytes.length !== size || cacheHash(bytes) !== packed.subarray(MAGIC.length + 5, HEADER).toString('hex')) return null;
+    return bytes;
+  } catch { return null; } finally { await file?.close().catch(() => {}); }
+}
+
+async function write(directory, name, bytes) {
+  const filename = path.join(directory, name), temporary = filename + '.' + randomUUID() + '.tmp';
+  try {
+    const parts = await encode(bytes), file = await open(temporary, 'wx', 0o600);
+    try { for (const part of parts) await file.writeFile(part); } finally { await file.close(); }
+    await rename(temporary, filename);
+  } finally { await unlink(temporary).catch(() => {}); }
+}
+
+function references(record) {
+  const files = record?.value?.files;
+  if (record?.format !== 2 || !Array.isArray(files) || files.length > 4096) return null;
+  if (!files.every(file => Array.isArray(file) && file.length === 4 && typeof file[0] === 'string' && digest.test(file[1]) && typeof file[2] === 'string' && Number.isInteger(file[3]) && file[3] >= 0 && file[3] <= MAX_BLOB)) return null;
+  if (files.reduce((sum, file) => sum + file[3], 0) > 48 * 1024 * 1024) return null;
+  return files;
+}
+
+export async function readCompilationRecord(directory, key) {
+  if (!directory || !digest.test(key)) return null;
+  try {
+    const bytes = await read(directory, key + '.graph', MAX_RECORD);
+    if (!bytes) return null;
+    const record = deserialize(bytes), files = references(record);
+    if (!files || record.cacheKey !== key) return null;
+    const blobs = new Map(), restored = [];
+    for (const [name, id, hash, size] of files) {
+      let value = blobs.get(id);
+      if (!value) {
+        value = await read(directory, id + '.blob', MAX_BLOB);
+        if (!value || value.length !== size || cacheHash(value) !== id) return null;
+        blobs.set(id, value);
+      }
+      if (value.length !== size) return null;
+      restored.push([name, value, hash]);
+    }
+    return { ...record, format: 1, value: { ...record.value, files: restored } };
+  } catch { return null; }
+}
+
+// Concurrent eviction may turn a read into a miss, never into a partial hit.
+// Retain the newest complete records and their shared blobs within one budget.
+export async function pruneCompilationRecords(directory) {
+  try {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.slice(0, MAX_SCAN)) {
+      if (!entry.isFile() || !namePattern.test(entry.name)) continue;
+      const info = await lstat(path.join(directory, entry.name));
+      if (info.isFile() && !info.isSymbolicLink()) files.push({ name: entry.name, size: info.size, time: info.mtimeMs });
+    }
+    const blobs = new Map(files.filter(file => file.name.endsWith('.blob')).map(file => [file.name.slice(0, -5), file]));
+    const retained = new Set(); let total = 0, count = 0;
+    for (const file of files.filter(file => file.name.endsWith('.graph')).sort((a, b) => b.time - a.time)) {
+      let refs;
+      try { const bytes = await read(directory, file.name, MAX_RECORD); refs = bytes && references(deserialize(bytes)); } catch {}
+      const ids = refs && [...new Set(refs.map(item => item[1]))];
+      const added = file.size + (ids || []).reduce((sum, id) => sum + (retained.has(id + '.blob') ? 0 : blobs.get(id)?.size ?? MAX_DISK), 0);
+      if (ids && ids.every(id => blobs.has(id)) && count < MAX_RECORDS && total + added <= MAX_DISK) {
+        retained.add(file.name); for (const id of ids) retained.add(id + '.blob');
+        total += added; count++;
+      }
+    }
+    for (const file of files) if (!retained.has(file.name)) await unlink(path.join(directory, file.name)).catch(() => {});
+  } catch { /* Disk cache maintenance cannot fail a build. */ }
+}
+
+export async function writeCompilationRecord(directory, key, record) {
+  if (!directory || !digest.test(key)) return false;
+  try {
+    const files = [], written = new Set();
+    for (const [name, data, hash] of record.value.files) {
+      if (!(data instanceof Uint8Array) || data.byteLength > MAX_BLOB) return false;
+      const bytes = Buffer.from(data.buffer, data.byteOffset, data.byteLength), id = cacheHash(bytes);
+      files.push([name, id, hash, bytes.length]);
+      if (!written.has(id)) {
+        // Verify existing bytes before reuse, including a corrupted blob from an
+        // interrupted previous build. Atomic replacement repairs that entry.
+        const existing = await read(directory, id + '.blob', MAX_BLOB);
+        if (!existing || cacheHash(existing) !== id) await write(directory, id + '.blob', bytes);
+        written.add(id);
+      }
+    }
+    const saved = { ...record, format: 2, cacheKey: key, value: { ...record.value, files } };
+    if (!references(saved)) return false;
+    const bytes = serialize(saved);
+    if (bytes.length > MAX_RECORD) return false;
+    await write(directory, key + '.graph', bytes);
+    await pruneCompilationRecords(directory);
+    return true;
+  } catch { return false; }
+}

package/build/compiler.mjs

@@ -6,6 +6,7 @@ import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
+import {createHash} from 'node:crypto';
 import { moduleResolutionPlugin, validateWebpackResolution } from './module-resolution.mjs';
 import { cachedLoader } from './loader-cache.mjs';
 import { incrementalBuild } from './incremental.mjs';
@@ -13,11 +14,36 @@ import { webpackGraph } from './webpack-graph.mjs';
 import { turbopackRules, sourceReader } from './turbopack-conditions.mjs';
 import {withSourceMaps,configureSourceMaps,inlineSourceMap} from './source-maps.mjs';
 import { optimizeImportsPlugins } from './optimize-imports.mjs';
+import {recordBuildAnalysis} from './analyze.mjs';
+import {recordDevDependencies,developmentDependencies,developmentStylePlans,developmentStyleDependencies,developmentModules} from './dev-dependencies.mjs';
+import {normalizeReactCompilerConfig,REACT_COMPILER_VERSION} from './react-compiler.mjs';
+import {withReactCompilerReporting,configureReactCompilerReporting,withReactCompilerGraph,recordReactCompilerGraph} from './react-compiler-report.mjs';
+import {withCompilationGraphCacheReporting,cachedGraphBuild} from './compilation-cache.mjs';
+export {reactCompilerReport} from './react-compiler-report.mjs';
+export {compilationGraphCacheReport} from './compilation-cache.mjs';
 
 let validateOptions;
 const compilation = new AsyncLocalStorage();
-export const withCompilation = callback => withSourceMaps(()=>compilation.run({ targets: new Map(), loaded: new Map() }, callback));
-export function configureCompiler(options) { Object.assign(compilation.getStore() || {}, options);configureSourceMaps(options.dev || options.config?.productionBrowserSourceMaps); }
+export const withCompilation = callback => withCompilationGraphCacheReporting(()=>withReactCompilerReporting(()=>withSourceMaps(()=>compilation.run({ targets: new Map(), loaded: new Map() }, callback))));
+export function configureCompiler(options) {
+  Object.assign(compilation.getStore() || {}, options);configureSourceMaps(options.dev || options.config?.productionBrowserSourceMaps);
+  configureReactCompilerReporting({...options,config:{reactCompiler:options.config?.reactCompiler ? normalizeReactCompilerConfig(options.config.reactCompiler) : false},compilerVersion:REACT_COMPILER_VERSION});
+}
+export const buildAnalysisRecords=()=>compilation.getStore()?.analysis;
+export const buildAnalysisRoutes=()=>compilation.getStore()?.analysisRoutes;
+export const devDependencies=(project,manifest)=>developmentDependencies(compilation.getStore(),project,manifest);
+export const devStylePlans=()=>developmentStylePlans(compilation.getStore());
+export const devStyleDependencies=()=>developmentStyleDependencies(compilation.getStore());
+export const devModules=root=>developmentModules(compilation.getStore(),root);
+export async function readCompilerFile(file,override){
+  if(override!==undefined)return override;
+  const state=compilation.getStore();if(!state)return readFile(file,'utf8');
+  state.sourceFiles||=new Map();
+  if(state.sourceFiles.has(file))return state.sourceFiles.get(file);
+  const pending=readFile(file,'utf8').then(source=>{state.devInputs?.record(file,source);state.sourceBytes=(state.sourceBytes||0)+source.length*2;if(state.sourceBytes>8*1024*1024)state.sourceFiles.delete(file);return source;});
+  if(state.sourceFiles.size<512)state.sourceFiles.set(file,pending);
+  return pending;
+}
 export async function compilerSource(file, fallback) {
   return compilation.getStore()?.loaded.get(file)?.source ?? fallback ?? await readFile(file, 'utf8');
 }
@@ -101,7 +127,7 @@ async function targetConfig(state, target) {
       }
       const validateDefinitions = (values,prefix='') => {for(const [name,value] of Object.entries(values)) {
         const key=prefix+name;
-        if (/^(?:process\.env\.(?:NODE_ENV|NEXT_RUNTIME|PRNEXT_)|__prnext)/.test(key.replace(/^typeof /,''))) throw new Error(`DefinePlugin cannot override reserved ${key}`);
+        if (/^(?:process\.env\.(?:NODE_ENV|NEXT_RUNTIME|PRNEXT_)|__prnext|__PRNEXT_CACHE_COMPONENTS__(?:$|\.))/.test(key.replace(/^typeof /,''))) throw new Error(`DefinePlugin cannot override reserved ${key}`);
         if(value && Object.getPrototypeOf(value)===Object.prototype)validateDefinitions(value,key+'.');
       }};
       validateDefinitions(plugin.definitions);
@@ -120,7 +146,27 @@ export async function validateCompilerConfig(config, root, {dev=false,edge=false
   for (const target of ['node','browser',...(edge?['edge']:[])]) await targetConfig(state,target);
 }
 export async function build(options) {
+  const state=compilation.getStore();
+  const target=options.define?.['process.env.NEXT_RUNTIME']==='"edge"'?'edge':options.platform==='browser'?'browser':'node';
+  return withReactCompilerGraph(target,async()=>{
+    const result=await compileGraph(options);
+    recordReactCompilerGraph(result);
+    recordBuildAnalysis(state,options,result);
+    recordDevDependencies(state,options,result);
+    return result;
+  });
+}
+async function compileGraph(options) {
   const state = compilation.getStore();
+  // The transform is captured by the framework's per-build callbacks. Give both
+  // esbuild and the webpack bridge a new graph identity when its options change,
+  // even if none of the application's source files have changed. The marker has
+  // no hooks or runtime output and leaves the opt-out graph exactly as before.
+  if ((options.plugins || []).some(plugin => framework.test(plugin.name)) && state?.config?.reactCompiler) {
+    const settings=normalizeReactCompilerConfig(state.config.reactCompiler);
+    const fingerprint=createHash('sha256').update(JSON.stringify([REACT_COMPILER_VERSION,settings])).digest('hex').slice(0,24);
+    options={...options,plugins:[...options.plugins,{name:'prnext-react-compiler-'+fingerprint,setup(){}}]};
+  }
   if ((options.plugins || []).some(plugin => framework.test(plugin.name))) options = { ...options, plugins: optimizeImportsPlugins(options.plugins, state?.config?.experimental?.optimizePackageImports) };
   // esbuild's shared service dispatches callbacks from its own async context.
   // Re-enter this build so transforms never inherit another project's map mode,
@@ -137,7 +183,8 @@ export async function build(options) {
   // Runtime vendor bundles are framework-owned, not project webpack targets.
   const projectGraph = (options.plugins || []).some(plugin => framework.test(plugin.name));
   if (projectGraph && state?.tsconfig) options = { ...options, tsconfig: state.tsconfig };
-  const compile = input => state?.incremental && state.dev && (projectGraph || !input.plugins?.length) ? incrementalBuild(input,{root:state.root,stage:state.stage,group:projectGraph?'project':'auxiliary',run:callback=>compilation.run(state,callback)}) : esbuild(input);
+  const nativeCompile = input => state?.incremental && (projectGraph || !input.plugins?.length) ? incrementalBuild(input,{root:state.root,stage:state.stage,group:projectGraph?'project':'auxiliary',run:callback=>compilation.run(state,callback)}) : esbuild(input);
+  const compile = input => state?.root && state?.stage ? cachedGraphBuild(input,state,nativeCompile) : nativeCompile(input);
   if (!(state?.config?.webpack || Object.keys(state?.config?.turbopack?.rules || {}).length) || !projectGraph) return compile(options);
   const target = options.define?.['process.env.NEXT_RUNTIME'] === '"edge"' ? 'edge' : options.platform === 'browser' ? 'browser' : 'node';
   const config = await targetConfig(state,target);

package/build/concurrent.mjs

@@ -0,0 +1,12 @@
+import {availableParallelism} from 'node:os';
+
+// A shared finite worker set, with deterministic results and full settlement
+// before a caller discards its stage. No new work starts after a failure.
+export async function mapConcurrent(items,run,limit=Math.min(4,availableParallelism())) {
+  if(!Number.isInteger(limit)||limit<1||limit>32)throw new RangeError('Invalid build concurrency');
+  const values=Array.from(items),results=new Array(values.length);let next=0,failure,failed=false;
+  await Promise.all(Array.from({length:Math.min(limit,values.length)},async()=>{
+    while(!failed&&next<values.length){const index=next++;try{results[index]=await run(values[index],index);}catch(error){if(!failed){failed=true;failure=error;}}}
+  }));
+  if(failed)throw failure;return results;
+}

package/build/config.mjs

@@ -16,16 +16,30 @@ import { validateTurbopack } from './module-resolution.mjs';
 import { validateI18n } from './i18n.mjs';
 import { frameworkPackages } from './framework-imports.mjs';
 import { validateTypeScript } from './typescript.mjs';
+import {validateWorkerMemory} from './worker-memory.mjs';
 import { validateWorkerRetirement } from './worker-retirement.mjs';
+import {validateWorkerPreload} from './worker-preload.mjs';
 import { validateOptimizePackageImports } from './optimize-imports.mjs';
+import {validateDeploymentRetention} from './deployment-config.mjs';
+import {validatePrerenderConfig} from './prerender-config.mjs';
+import {validateHtmlOnly} from './html-only-config.mjs';
 import { validateProxyBodySize } from './proxy-body-config.mjs';
+import { normalizeReactCompilerConfig } from './react-compiler.mjs';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const configName = /^(?:next|prnext)\.config\.(?:js|mjs|cjs|ts)$/;
 const supported = new Set(['env', 'redirects', 'headers', 'rewrites', 'generateBuildId', 'compress', 'poweredByHeader', 'productionBrowserSourceMaps', 'basePath', 'assetPrefix', 'experimental', 'sassOptions', 'transpilePackages', 'serverExternalPackages', 'cacheComponents', 'cacheLife', 'images', 'reactStrictMode', 'pageExtensions', 'trailingSlash', 'skipTrailingSlashRedirect', 'skipMiddlewareUrlNormalize', 'skipProxyUrlNormalize', 'cacheHandlers', 'distDir']);
 const defaults = { distDir: '.prnext', env: {}, compress: true, poweredByHeader: true, productionBrowserSourceMaps: false, basePath: '', assetPrefix: '', trailingSlash: false, skipTrailingSlashRedirect: false, skipMiddlewareUrlNormalize: false, experimental: { nextScriptWorkers: false } };
 supported.add('cacheHandler');
+supported.add('partialPrefetching');
+supported.add('navigationCache');
+supported.add('workerMemory');
 supported.add('workerRetirement');
+supported.add('workerPreload');
+supported.add('deploymentRetention');
+supported.add('prerender');
+supported.add('htmlOnly');
+supported.add('cssEngine');
 supported.add('cacheMaxMemorySize');
 supported.add('turbopack');
 supported.add('i18n');
@@ -47,7 +61,7 @@ export function publicAssetBase(config) {
   return (config.assetPrefix || config.basePath || '').replace(/\/+$/, '') + '/_prnext/assets';
 }
 
-function configPlugin() {
+function configPlugin(devInputs) {
   return {
     name: 'prnext-project-config',
     setup(build) {
@@ -56,20 +70,21 @@ function configPlugin() {
         if (filename.includes(`${path.sep}node_modules${path.sep}`)) return;
         // Preserve filesystem paths after bundling config's relative helpers.
         const prefix = `const __prnext_config_url=${JSON.stringify(pathToFileURL(filename).href)};const __prnext_config_file=${JSON.stringify(filename)};const __prnext_config_dir=${JSON.stringify(path.dirname(filename))};\n`;
-        const source = (await readFile(filename, 'utf8')).replace(/^#![^\n]*(?:\n|$)/, '');
+        const raw = await readFile(filename, 'utf8');devInputs?.record(filename,raw);
+        const source = raw.replace(/^#![^\n]*(?:\n|$)/, '');
         return { contents: prefix + source, loader: filename.endsWith('.ts') ? 'ts' : 'js', resolveDir: path.dirname(filename) };
       });
     },
   };
 }
 
-async function importConfig(filename) {
+async function importConfig(filename,devInputs) {
   const temporary = path.join(path.dirname(filename), `.prnext-config-${randomUUID()}.mjs`);
   try {
     const result = await bundle({ entryPoints: [filename], absWorkingDir: path.dirname(filename), bundle: true, write: false, platform: 'node', target: 'node22', format: 'esm', packages: 'external', logLevel: 'silent',
       define: { 'import.meta.url': '__prnext_config_url', __filename: '__prnext_config_file', __dirname: '__prnext_config_dir' },
       banner: { js: `import {createRequire as __prnext_create_require} from 'node:module';const require=__prnext_create_require(${JSON.stringify(pathToFileURL(filename).href)});` },
-      plugins: [configPlugin()],
+      plugins: [configPlugin(devInputs)],
     });
     await writeFile(temporary, result.outputFiles[0].contents, { flag: 'wx' });
     const imported = await import(pathToFileURL(temporary).href);
@@ -85,14 +100,22 @@ export function validateProjectConfig(input, filename = 'project config') {
   // Optional properties explicitly set to undefined still use their defaults,
   // as in common process.env-based Next configuration wrappers.
   const config = { ...defaults, ...Object.fromEntries(Object.entries(input).filter(([,value]) => value !== undefined)) };
-  for (const key of ['reactCompiler', 'typedRoutes']) {
-    if (config[key] === undefined || config[key] === false) continue;
-    if (key === 'reactCompiler') throw new Error('reactCompiler currently supports only false. PRNext does not run the React Compiler transform; keep Next.js for builds that require it.');
-    throw new Error('typedRoutes currently supports only false. PRNext does not generate or validate typed route declarations; keep Next.js for builds that require them.');
-  }
+  if(config.typedRoutes!==undefined&&typeof config.typedRoutes!=='boolean')throw new TypeError('typedRoutes must be a boolean');
+  config.reactCompiler = normalizeReactCompilerConfig(config.reactCompiler);
   config.typescript = validateTypeScript(config.typescript);
+  config.workerMemory = validateWorkerMemory(config.workerMemory);
   config.workerRetirement = validateWorkerRetirement(config.workerRetirement);
-  if (config.devIndicators !== undefined && config.devIndicators !== false) throw new TypeError('devIndicators currently supports only false. PRNext provides development errors and Fast Refresh, but no Next.js development indicator menu.');
+  config.workerPreload=validateWorkerPreload(config.workerPreload);
+  config.deploymentRetention=validateDeploymentRetention(config.deploymentRetention);
+  config.prerender=validatePrerenderConfig(config.prerender);
+  config.htmlOnly=validateHtmlOnly(config.htmlOnly);
+  config.cssEngine ??= 'auto';
+  if (!['auto','postcss','lightningcss'].includes(config.cssEngine)) throw new TypeError('cssEngine must be auto, postcss or lightningcss.');
+  if (config.devIndicators !== false) {
+    const indicator = config.devIndicators ?? {};
+    if (config.devIndicators === null || typeof indicator !== 'object' || Array.isArray(indicator) || Object.keys(indicator).some(key => key !== 'position') || (indicator.position !== undefined && !['bottom-right', 'bottom-left', 'top-right', 'top-left'].includes(indicator.position))) throw new TypeError('devIndicators must be false or an object with position: bottom-right, bottom-left, top-right or top-left.');
+    config.devIndicators = { position: indicator.position ?? 'bottom-left' };
+  }
   if (config.onDemandEntries !== undefined) {
     const entries = config.onDemandEntries;
     if (!entries || typeof entries !== 'object' || Array.isArray(entries)) throw new TypeError('onDemandEntries must be an object');
@@ -114,6 +137,20 @@ export function validateProjectConfig(input, filename = 'project config') {
   if (config.reactStrictMode !== undefined && typeof config.reactStrictMode !== 'boolean') throw new Error(`${filename}: reactStrictMode must be a boolean.`);
   config.cacheComponents ??= false;
   if (typeof config.cacheComponents !== 'boolean') throw new TypeError('cacheComponents must be a boolean');
+  config.partialPrefetching ??= false;
+  if (typeof config.partialPrefetching !== 'boolean') throw new TypeError('partialPrefetching must be a boolean');
+  if (config.partialPrefetching && !config.cacheComponents) throw new Error('partialPrefetching requires cacheComponents: true.');
+  if (config.navigationCache === false) config.navigationCache = { maxEntries: 0, ttlMs: 120000 };
+  else {
+    if (config.navigationCache === null) throw new TypeError('navigationCache must be false or an object with maxEntries and ttlMs.');
+    const value = config.navigationCache ?? {};
+    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !['maxEntries', 'ttlMs', 'authCookies'].includes(key))) throw new TypeError('navigationCache must be false or an object with maxEntries, ttlMs and authCookies.');
+    const maxEntries = value.maxEntries ?? 4, ttlMs = value.ttlMs ?? 120000;
+    if (!Number.isSafeInteger(maxEntries) || maxEntries < 0 || maxEntries > 8 || !Number.isSafeInteger(ttlMs) || ttlMs < 1000 || ttlMs > 600000) throw new TypeError('navigationCache requires maxEntries between 0 and 8, and ttlMs between 1000 and 600000.');
+    const authCookies = value.authCookies;
+    if (authCookies !== undefined && (!Array.isArray(authCookies) || authCookies.length > 32 || authCookies.some(name => typeof name !== 'string' || !name || name.length > 256 || !/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name)))) throw new TypeError('navigationCache.authCookies must contain at most 32 valid cookie names.');
+    config.navigationCache = { maxEntries, ttlMs, ...(authCookies !== undefined ? {authCookies: [...new Set(authCookies)].sort()} : {}) };
+  }
   config.cacheLife = cacheProfiles.profiles(config.cacheLife);
   for (const key of ['transpilePackages', 'serverExternalPackages']) {
     const names = config[key] ?? [];
@@ -182,9 +219,9 @@ export function validateProjectConfig(input, filename = 'project config') {
 }
 
 /** Config and its relative imports are evaluated fresh on every build. */
-export async function loadProjectConfig(projectRoot, { dev = false, envMode, phase = dev ? constants.PHASE_DEVELOPMENT_SERVER : constants.PHASE_PRODUCTION_BUILD } = {}) {
+export async function loadProjectConfig(projectRoot, { dev = false, envMode, devInputs, phase = dev ? constants.PHASE_DEVELOPMENT_SERVER : constants.PHASE_PRODUCTION_BUILD } = {}) {
   const root = path.resolve(projectRoot);
-  loadEnvConfig(root, { dev, mode: envMode });
+  loadEnvConfig(root, { dev, mode: envMode, inputs:devInputs });
   const files = await readdir(root);
   const names = files.filter(name => configName.test(name));
   const unsupportedFiles = files.filter(name => /^(?:next|prnext)\.config\.(?:mts|cts|jsx|tsx|json)$/.test(name));
@@ -192,7 +229,7 @@ export async function loadProjectConfig(projectRoot, { dev = false, envMode, pha
   if (names.length > 1) throw new Error(`Multiple configuration files found: ${names.sort().join(', ')}. Keep one next.config.* or prnext.config.* file.`);
   if (!names.length) return validateProjectConfig({});
   const filename = path.join(root, names[0]);
-  let input = await importConfig(filename);
+  let input = await importConfig(filename,devInputs);
   if (typeof input === 'function') input = await input(phase, { defaultConfig: { ...defaults, env: {}, experimental: { ...defaults.experimental } } });
   return validateProjectConfig(input, names[0]);
 }

package/build/create.mjs

@@ -0,0 +1,239 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readFile, readdir, realpath, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { packageManifest } from '../native/resolve.mjs';
+import { supportedNode } from '../native/diagnostics.mjs';
+import { npmCommand } from '../native/npm.mjs';
+
+export const createHelp = `Usage: prnext create <directory> [--js] [--no-install] [--json]
+
+Create a minimal App Router project and install its dependencies with npm.
+TypeScript is the default; --js creates a JavaScript project.
+The directory must be absent or completely empty. Existing files are never replaced.
+--no-install prepares files without running npm or accessing the network.
+Inside an existing workspace, use --no-install and its own package manager.
+
+  npx @thomas.f/prnext create my-app
+  cd my-app
+  npm run dev
+`;
+
+export function parseCreateArgs(args, cwd = process.cwd()) {
+  const flags = new Set(), positional = [];
+  let literal = false;
+  for (const arg of args) {
+    if (literal) positional.push(arg);
+    else if (arg === '--') literal = true;
+    else if (['--no-install', '--js', '--json'].includes(arg)) {
+      if (flags.has(arg)) throw new Error(`Duplicate create option: ${arg}`);
+      flags.add(arg);
+    } else if (arg.startsWith('-')) throw new Error(`Unknown create option: ${arg}`);
+    else positional.push(arg);
+  }
+  if (positional.length !== 1 || !positional[0].trim() || /[\0\r\n]/.test(positional[0])) throw new Error('Provide one project directory: prnext create my-app');
+  return { directory: path.resolve(cwd, positional[0]), options: { install: !flags.has('--no-install'), typescript: !flags.has('--js'), json: flags.has('--json') } };
+}
+
+const samePath = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino;
+async function info(file, options) {
+  try { return await lstat(file, options); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+async function physicalDirectory(directory, missing = false) {
+  // macOS exposes standard directories through root-owned /private aliases.
+  // Resolve only those exact system targets; every user-controlled descendant
+  // still goes through the strict no-symlink walk below, on every write.
+  if (process.platform === 'darwin') {
+    const alias = /^\/(?:var|tmp|etc)(?=\/|$)/.exec(directory)?.[0];
+    if (alias && (await info(alias))?.isSymbolicLink() && await realpath(alias) === `/private${alias}`) {
+      directory = `/private${directory}`;
+    }
+  }
+  const root = path.parse(directory).root;
+  const inspected = [];
+  let current = root;
+  for (const part of path.relative(root, directory).split(path.sep).filter(Boolean)) {
+    if (process.platform === 'win32' && (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part) || /[<>:"|?*]|[. ]$/.test(part))) throw new Error(`Invalid Windows directory name: ${part}`);
+    current = path.join(current, part);
+    const entry = await info(current, { bigint: true });
+    if (!entry && missing) continue;
+    if (!entry?.isDirectory() || entry.isSymbolicLink()) throw new Error(`Project directories must not be files, symbolic links or junctions: ${current}`);
+    inspected.push([current, entry]);
+  }
+  if (!missing) {
+    const canonical = await realpath(directory);
+    if (!samePath(canonical, directory)) {
+      if (process.platform !== 'win32') throw new Error('Use a physical project directory without symbolic links or junctions.');
+      // DOS 8.3 names are directory aliases, not reparse points. Accept the
+      // expanded name only after rechecking every observed directory identity
+      // and proving that the canonical target is the same physical directory.
+      for (const [file, original] of inspected) {
+        const observed = await info(file, { bigint: true });
+        if (!observed?.isDirectory() || observed.isSymbolicLink() || !sameFile(original, observed)) throw new Error(`Project directory changed during creation: ${file}`);
+      }
+      const original = inspected.at(-1)?.[1] || await info(directory, { bigint: true });
+      const resolved = await info(canonical, { bigint: true });
+      if (!original?.isDirectory() || original.isSymbolicLink() || original.ino === 0n || !resolved?.isDirectory() || resolved.isSymbolicLink() || !sameFile(original, resolved)) throw new Error('Use a physical project directory without symbolic links or junctions.');
+    }
+  }
+}
+
+async function parentWorkspace(directory) {
+  for (let current = path.dirname(directory); ; current = path.dirname(current)) {
+    const workspace = await info(path.join(current, 'pnpm-workspace.yaml'));
+    if (workspace) return current;
+    const file = path.join(current, 'package.json'), entry = await info(file);
+    if (entry) {
+      if (!entry.isFile() || entry.isSymbolicLink() || entry.size > 1024 * 1024) throw new Error(`Cannot safely inspect parent package.json: ${file}`);
+      let manifest;
+      try { manifest = JSON.parse((await readFile(file, 'utf8')).replace(/^\uFEFF/, '')); }
+      catch { throw new Error(`Parent package.json is invalid: ${file}`); }
+      if (manifest.workspaces) return current;
+    }
+    if (current === path.dirname(current)) return null;
+  }
+}
+
+function projectName(directory) {
+  const name = path.basename(directory).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[._-]+|[._-]+$/g, '').slice(0, 100);
+  return !name || ['node_modules', 'favicon.ico'].includes(name) ? 'prnext-app' : name;
+}
+const json = value => JSON.stringify(value, null, 2) + '\n';
+
+function projectFiles(name, typescript) {
+  const extension = typescript ? 'tsx' : 'jsx';
+  const scripts = { dev: 'prnext dev', build: 'prnext build', start: 'prnext start', check: 'prnext check', ...(typescript ? { typecheck: 'prnext typecheck' } : {}) };
+  const manifest = { name, version: '0.0.0', private: true, type: 'module', scripts,
+    dependencies: { [packageManifest.name]: packageManifest.version, ...Object.fromEntries(Object.entries(packageManifest.peerDependencies).filter(([name])=>!packageManifest.peerDependenciesMeta?.[name]?.optional)) },
+    ...(typescript ? { devDependencies: { typescript: '^5.9.0', '@types/node': '^22.0.0', '@types/react': '^19.0.0', '@types/react-dom': '^19.0.0' } } : {}),
+    engines: { node: packageManifest.engines.node } };
+  const files = new Map([
+    ['package.json', json(manifest)],
+    [`app/layout.${extension}`, `import './globals.css';\n${typescript ? "import type { ReactNode } from 'react';\n" : ''}
+export const metadata = { title: 'My PRNext app', description: 'A React application built with PRNext.' };
+
+export default function RootLayout({ children }${typescript ? ': { children: ReactNode }' : ''}) {
+  return <html lang="en"><body>{children}</body></html>;
+}
+`],
+    [`app/page.${extension}`, `export default function Home() {
+  return <main><h1>PRNext</h1><p>Edit <code>app/page.${extension}</code> to get started.</p></main>;
+}
+`],
+    ['app/globals.css', `:root { color-scheme: dark; font-family: system-ui, sans-serif; background: #0a0a0a; color: #ededed; }
+* { box-sizing: border-box; }
+body { margin: 0; }
+main { max-width: 64rem; margin: auto; padding: clamp(2rem, 8vw, 6rem) 1.5rem; }
+h1 { font-size: clamp(2.5rem, 8vw, 4rem); letter-spacing: -.04em; }
+p { line-height: 1.6; }
+code { font-size: .95em; }
+`],
+    ['.gitignore', 'node_modules/\n.prnext/\n.prnext-types/\n.prnext-dev/\n.prnext-cache/\n.env*\n!.env.example\n*.tsbuildinfo\n'],
+    ['README.md', `# ${name}\n\nA minimal PRNext application.\n\nRun \`npm install\` if dependencies have not been installed, then:\n\n\`\`\`sh\nnpm run dev\n\`\`\`\n\nEdit \`app/page.${extension}\`. Use the local URL printed by the server.\n\n\`\`\`sh\nnpm run check\n${typescript ? 'npm run typecheck\n' : ''}npm run build\nnpm start\n\`\`\`\n\nUse another port with \`npm run dev -- --port 3001\` when needed.\n\n[PRNext documentation](https://prnext.dev) · Installed AI guide: \`npx --no-install prnext docs --ai\`.\nPRNext is experimental; Next.js compatibility is partial.\n`],
+    ['AGENTS.md', `# PRNext project\n\nThis application uses \`@thomas.f/prnext\`. Before changing routing, configuration, data fetching or deployment, read the installed guide at \`node_modules/@thomas.f/prnext/AI.md\` or run:\n\n\`\`\`sh\nnpx --no-install prnext docs --ai\nnpx --no-install prnext docs --ai --list\n\`\`\`\n\nRead only the relevant topic with \`npx --no-install prnext docs --ai <topic>\`. The installed documentation is version-specific; do not assume full Next.js compatibility. Preserve the project's package manager and lockfile.\n`],
+  ]);
+  if (typescript) files.set('tsconfig.json', json({ compilerOptions: { target: 'ES2022', lib: ['DOM', 'DOM.Iterable', 'ES2022'], module: 'ESNext', moduleResolution: 'Bundler', jsx: 'preserve', strict: true, noEmit: true, esModuleInterop: true, skipLibCheck: true }, include: ['**/*.ts', '**/*.tsx'], exclude: ['node_modules', '.prnext', '.prnext-dev', '.prnext-cache'] }));
+  return files;
+}
+
+function abortError() { const error = new Error('Project creation canceled.'); error.name = 'AbortError'; return error; }
+function aborted(signal) { if (signal?.aborted) throw abortError(); }
+
+/** Run npm without a shell; a canceled command waits for its own installer tree. */
+export async function installProject(directory, { signal, onOutput = () => {} } = {}) {
+  aborted(signal);
+  // npm resolves its working directory physically. Keep its environment on
+  // that same path so macOS aliases cannot split the lock tree.
+  directory = await realpath(directory);
+  aborted(signal);
+  const env = { ...process.env, INIT_CWD: directory, PWD: directory };
+  for (const key of Object.keys(env)) if (/^npm_config_(?:workspace|workspaces|global|prefix)$/i.test(key)) delete env[key];
+  const npm = npmCommand(env);
+  await new Promise((resolve, reject) => {
+    // The generated package.json already anchors npm's local project here.
+    // npm 10 on Windows treats an explicit --prefix as its global top and can
+    // add the project to its own dependencies even with --global=false.
+    const child = spawn(npm.command, [...npm.args, 'install', '--workspaces=false', '--global=false'], { cwd: directory, env, windowsHide: true, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
+    let tail = '', timer, canceling = false;
+    const receive = stream => chunk => { tail = (tail + chunk).slice(-16000); onOutput(String(chunk), stream); };
+    child.stdout.on('data', receive('stdout'));
+    child.stderr.on('data', receive('stderr'));
+    function terminate(force) {
+      if (!child.pid) return;
+      if (process.platform === 'win32') {
+        if (child.exitCode !== null || child.signalCode) return;
+        const executable = path.join(env.SystemRoot || 'C:\\Windows', 'System32', 'taskkill.exe');
+        const killer = spawn(executable, ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
+        killer.on('error', () => child.kill());
+      } else {
+        try { process.kill(-child.pid, force ? 'SIGKILL' : 'SIGTERM'); } catch (error) { if (error.code !== 'ESRCH') child.kill(force ? 'SIGKILL' : 'SIGTERM'); }
+      }
+    }
+    function cancel() { canceling = true; terminate(false); timer ||= setTimeout(() => terminate(true), 5000); }
+    function cleanup() { clearTimeout(timer); signal?.removeEventListener('abort', cancel); }
+    child.once('error', error => { cleanup(); reject(error); });
+    child.once('close', (code, childSignal) => {
+      // A detached lifecycle script can close npm's pipes before it exits.
+      // Do not let npm's exit cancel escalation for that remaining group.
+      if ((canceling || signal?.aborted) && process.platform !== 'win32') terminate(true);
+      cleanup();
+      if (canceling || signal?.aborted) reject(abortError());
+      else if (code === 0) resolve();
+      else reject(new Error(`npm install failed (${childSignal || code}).${tail.trim() ? '\n' + tail.trim() : ''}`));
+    });
+    signal?.addEventListener('abort', cancel, { once: true });
+    if (signal?.aborted) cancel();
+  });
+}
+
+export async function createProject(directory, options = {}, services = {}) {
+  const root = path.resolve(directory), typescript = options.typescript !== false, install = options.install !== false;
+  aborted(options.signal);
+  const nodeVersion = services.nodeVersion || process.version;
+  if (!supportedNode(nodeVersion)) throw new Error(`Node ${nodeVersion} is unsupported. Use Node ${packageManifest.engines.node}.`);
+  await physicalDirectory(root, true);
+  const existing = await info(root);
+  if (existing && (await readdir(root)).length) throw new Error(`Project directory must be empty; no files were changed: ${root}`);
+  if (install && await parentWorkspace(root)) throw new Error('Automatic installation inside an existing workspace is not supported. Use --no-install, then add the project with the workspace package manager. No files were changed.');
+  aborted(options.signal);
+  await mkdir(root, { recursive: true });
+  await physicalDirectory(root);
+  const lockPath = path.join(root, '.prnext-create.lock');
+  const lock = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | (constants.O_NOFOLLOW || 0), 0o600);
+  const locked = await lock.stat();
+  try {
+    if ((await readdir(root)).some(name => name !== '.prnext-create.lock')) throw new Error(`Project directory is no longer empty; existing files were preserved: ${root}`);
+    const name = projectName(root), files = projectFiles(name, typescript);
+    for (const [relative, content] of files) {
+      aborted(options.signal);
+      await physicalDirectory(root);
+      const target = path.join(root, relative), parent = path.dirname(target);
+      await physicalDirectory(parent, true);
+      await mkdir(parent, { recursive: true });
+      await physicalDirectory(parent);
+      const file = await open(target, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | (constants.O_NOFOLLOW || 0), 0o644);
+      try { await file.writeFile(content, 'utf8'); } finally { await file.close(); }
+    }
+    const report = { ok: true, status: 'prepared', root, name, typescript, files: [...files.keys()], installed: false, next: install ? ['npm run dev'] : ['npm install', 'npm run dev'] };
+    if (install) {
+      try {
+        aborted(options.signal);
+        await (services.runInstall || installProject)(root, { signal: options.signal, onOutput: options.onOutput });
+        aborted(options.signal);
+        report.installed = true;
+        report.status = 'created';
+      } catch (error) {
+        report.ok = false;
+        report.status = error.name === 'AbortError' || options.signal?.aborted ? 'cancelled' : 'install-failed';
+        report.error = error.message;
+        report.next = ['npm install', 'npm run dev'];
+      }
+    }
+    return report;
+  } finally {
+    await lock.close();
+    const current = await info(lockPath);
+    if (current?.isFile() && !current.isSymbolicLink() && sameFile(current, locked)) await unlink(lockPath);
+  }
+}