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

package/build/framework-imports.mjs

@@ -4,6 +4,7 @@ import {readFile} from 'node:fs/promises';
 import {analyzeSource} from './source-analysis.mjs';
 import {cachedTransform} from './transform-cache.mjs';
 const adapters = new Map([
+  ['cache/redis','redis-cache'],
   ['dist/shared/lib/router-context.shared-runtime','next-router-context'],
   ['dist/shared/lib/router-context','next-router-context'],
   ['dist/shared/lib/app-router-context.shared-runtime','next-app-router-context'],
@@ -23,33 +24,42 @@ export function frameworkImportName(specifier) {
 
 // Application graphs must not traverse the programmatic build API's native tools.
 // Outside a compiled application, the package root retains its full Node API.
-export function applicationEntry(builder,readSource=(file,override)=>override??readFile(file,'utf8')){
-  // esbuild understands .mts/.cts, but our framework transforms do not. Never
+export function applicationEntry(builder,readSource=(file,override)=>override??readFile(file,'utf8'),{transformTypedHelpers=false}={}){
+  // Server/client module boundaries in .mts/.cts are not supported. Never
   // silently bundle a server implementation or misclassify a client boundary.
   builder.onLoad({filter:/\.[cm]ts$/i,namespace:'file'},async args=>{
     // Loader bridges dispatch framework callbacks independently of their filters.
     if(!/\.[cm]ts$/i.test(args.path))return;
     const source=await readSource(args.path,args.prnextSource);
     const original=args.prnextSource===undefined?source:await readSource(args.path);
+    let nativeDecorators=false;
     // A loader may remove a directive as well as introduce one. Both versions
     // must be safe before its output can become an ordinary browser module.
     for(const candidate of new Set([original,source])){
-     const unsupported=cachedTransform('unsupported-framework-directives',candidate,[args.path,'v3'],()=>{
+     const unsupported=cachedTransform('unsupported-framework-directives',candidate,[args.path,'v4-native-decorators'],()=>{
       const analysis=analyzeSource(candidate,args.path);
       if(analysis.frameworkBoundary)return 'yes';
-      const pending=[analysis.program];
+      const pending=[analysis.program];let decorators=false;
       while(pending.length){
         const node=pending.pop();
         if(node.type==='ExpressionStatement'&&node.directive==='use server')return 'yes';
+        if(node.type==='Decorator'||node.decorators?.length)decorators=true;
         for(const value of Object.values(node)){
           if(Array.isArray(value)){for(const item of value)if(item?.type)pending.push(item);}
           else if(value&&typeof value==='object'&&value.type)pending.push(value);
         }
       }
-      return 'no';
+      return decorators?'decorated':'no';
      });
      if(unsupported==='yes')throw new Error(`React server/client directives are not supported in ${args.path}. Rename this file to .ts or .tsx.`);
+     nativeDecorators ||= unsupported==='decorated';
     }
+    // Compiler-enabled render graphs can transform ordinary typed helpers after
+    // this boundary check. Other consumers keep the historical esbuild path.
+    // Decorated typed helpers already have a native esbuild implementation.
+    // Keep that path instead of widening the syntax accepted by every Babel
+    // transform, while their importing React components can still be compiled.
+    if(transformTypedHelpers && !nativeDecorators)return;
     return {contents:source,loader:args.prnextSource===undefined?'ts':'tsx',resolveDir:dirname(args.path)};
   });
   builder.onResolve({filter:/^(?:prnext|@thomas\.f\/prnext)(?:\/route(?:\.js)?)?$/},()=>

package/build/html-only-config.mjs

@@ -0,0 +1,53 @@
+import {assertHtmlOnlyDocument} from '../runtime/html-only.mjs';
+const MAX_PATTERNS = 128;
+
+export function validateHtmlOnly(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > MAX_PATTERNS) throw new TypeError('htmlOnly must be an array of at most 128 App route patterns.');
+  for (const pattern of value) {
+    if (typeof pattern !== 'string' || pattern.length > 512 || !pattern.startsWith('/') || pattern.startsWith('//') ||
+        /[\s\\?#\u0000-\u001f\u007f]/.test(pattern) || /%(?![\da-f]{2})/i.test(pattern)) throw new TypeError('htmlOnly entries must be clean absolute route patterns without queries, fragments, whitespace or backslashes.');
+    const pathname = pattern.endsWith('/**') ? pattern.slice(0, -3) || '/' : pattern;
+    if (pathname.includes('*') || (pathname !== '/' && pathname.endsWith('/')) || pathname.slice(1).includes('//')) throw new TypeError('htmlOnly supports exact registered route patterns and a final /** subtree suffix only.');
+    for (const segment of pathname.split('/').slice(1)) {
+      let decoded;
+      try { decoded = decodeURIComponent(segment); } catch { throw new TypeError('htmlOnly patterns must use valid URL encoding.'); }
+      if (decoded === '.' || decoded === '..' || /[\\/\u0000-\u001f\u007f]/.test(decoded)) throw new TypeError('htmlOnly patterns cannot contain dot segments or encoded path separators.');
+    }
+  }
+  return [...new Set(value)];
+}
+
+export function matchesHtmlOnly(pattern, routePattern) {
+  if (!pattern.endsWith('/**')) return pattern === routePattern;
+  const prefix = pattern.slice(0, -3);
+  return !prefix || routePattern === prefix || routePattern.startsWith(prefix + '/');
+}
+
+export function selectHtmlOnlyRoutes(routes, patterns, { cacheComponents = false } = {}) {
+  const selected = new Set();
+  for (const pattern of validateHtmlOnly(patterns)) {
+    const matches = routes.filter(route => !route.internal && matchesHtmlOnly(pattern, route.pattern));
+    if (!matches.length) throw new Error(`htmlOnly pattern ${JSON.stringify(pattern)} does not match a registered route.`);
+    for (const route of matches) {
+      if (route.router !== 'app' || route.kind !== 'page') throw new Error(`htmlOnly route ${route.pattern} must be an App Router page; Pages Router and Route Handlers are not supported.`);
+      const config = route.cacheConfig || {};
+      if (cacheComponents || config.runtime === 'edge' || config.dynamic === 'force-dynamic' || config.forceNoStore || (config.revalidate !== undefined && config.revalidate !== false)) {
+        throw new Error(`htmlOnly route ${route.pattern} must be fully prerendered without Edge, Cache Components/PPR, dynamic rendering or ISR.`);
+      }
+      if (route.parallel || route.interception) throw new Error(`htmlOnly route ${route.pattern} does not support parallel or intercepted routing.`);
+      if (route.pattern.includes('[') && config.dynamicParams !== false) throw new Error(`htmlOnly route ${route.pattern} requires dynamicParams: false and complete generateStaticParams results.`);
+      selected.add(route.id);
+    }
+  }
+  return selected;
+}
+
+export function validateHtmlOnlyPrerender(route, rendered) {
+  if (!route.htmlOnly) return;
+  if (rendered.dynamic || rendered.partial || rendered.revalidate !== false || (rendered.status ?? 200) !== 200) {
+    throw new Error(`htmlOnly route ${route.pattern} must produce a complete successful static HTML document without dynamic data, partial rendering, redirects or ISR.`);
+  }
+  const html = Buffer.isBuffer(rendered.body) ? rendered.body.toString('utf8') : rendered.body;
+  assertHtmlOnlyDocument(html, route.pattern);
+}

package/build/html-only-graph.mjs

@@ -0,0 +1,67 @@
+import path from 'node:path';
+import { builtinModules } from 'node:module';
+import { analyzeSource } from './source-analysis.mjs';
+import { frameworkImportName, frameworkImportPattern } from './framework-imports.mjs';
+
+const builtins = new Set([...builtinModules, ...builtinModules.map(name => 'node:' + name)]);
+const interactive = new Set(['link','image','head','script','dynamic','router','compat/router','next-router-context','next-app-router-context']);
+const namespace = /^prnext-(?:css-mapping|compiled-css|app-empty|edge-empty):/;
+
+export function createHtmlOnlyGraph(root) {
+  const graph = new Map(), issues = new Map();
+  const file = value => path.resolve(root, value.replace(namespace, ''));
+  function issue(filename, reason) {
+    const key = file(filename);
+    if (!issues.has(key)) issues.set(key, reason);
+  }
+  return {
+    issue,
+    alias(source, target) {
+      if (file(source) !== file(target)) graph.set(file(source), [{ path:file(target) }]);
+    },
+    source(filename, source) {
+      const { program, directives, computedRequire, imports } = analyzeSource(source, filename);
+      if (directives.includes('use client')) issue(filename, 'a Client Component (use client)');
+      if (computedRequire) issue(filename, 'a computed require() whose dependencies cannot be validated');
+      for (const dependency of imports) if (frameworkImportPattern.test(dependency.path) && interactive.has(frameworkImportName(dependency.path))) issue(filename, `interactive framework import ${dependency.path}; use ordinary HTML elements instead`);
+      const pending = [program];
+      while (pending.length) {
+        const node = pending.pop();
+        if (node.directive === 'use server') issue(filename, 'a Server Action (use server)');
+        if (node.type === 'ImportExpression' && typeof node.source?.value !== 'string') issue(filename, 'a computed import() whose dependencies cannot be validated');
+        if (node.type === 'JSXOpeningElement' && node.name?.type === 'JSXIdentifier' && ['script','iframe','object','embed'].includes(node.name.name.toLowerCase())) issue(filename, `a <${node.name.name}> element`);
+        if (node.type === 'JSXAttribute' && node.name?.type === 'JSXIdentifier' && /^on[A-Z]/.test(node.name.name)) issue(filename, `interactive event property ${node.name.name}`);
+        for (const value of Object.values(node)) {
+          if (Array.isArray(value)) { for (const child of value) if (child?.type) pending.push(child); }
+          else if (value && typeof value === 'object' && value.type) pending.push(value);
+        }
+      }
+    },
+    record(metafile) {
+      for (const [name, input] of Object.entries(metafile?.inputs || {})) {
+        const key=file(name), dependencies=graph.get(key) || [];
+        for (const dependency of input.imports || []) {
+          if (!dependency.external) dependencies.push({path:file(dependency.path)});
+          else if (!builtins.has(dependency.path) && !/^(?:react|react-dom|react-server-dom-webpack)(?:\/|$)/.test(dependency.path) && !/^\.\.\/compat\/(?:navigation|headers|cache|server|font-local|font-google|og)\.cjs$/.test(dependency.path)) {
+            dependencies.push({external:dependency.path});
+          }
+        }
+        graph.set(key,dependencies);
+      }
+    },
+    validate(route) {
+      const roots = new Set([route.file, ...Object.values(route.segments || {}).flatMap(segment => Object.values(segment).filter(value => typeof value === 'string' && /\.[cm]?[jt]sx?$/.test(value))), ...(route.metadataFiles || []).map(item => item.file)].filter(Boolean));
+      const pending=[...roots].map(file), seen=new Set();
+      while (pending.length) {
+        const current=pending.pop();
+        if (seen.has(current)) continue;
+        seen.add(current);
+        if (issues.has(current)) throw new Error(`htmlOnly route ${route.pattern} reaches ${issues.get(current)} in ${path.relative(root,current)}.`);
+        for (const dependency of graph.get(current) || []) {
+          if (dependency.external) throw new Error(`htmlOnly route ${route.pattern} reaches unverified external dependency ${dependency.external} from ${path.relative(root,current)}. Bundle a static server dependency or remove it from this HTML-only route.`);
+          pending.push(dependency.path);
+        }
+      }
+    },
+  };
+}

package/build/index.mjs

@@ -1,5 +1,6 @@
+import {compileInstrumentation} from './instrumentation.mjs';
 import {prerenderPages as prerender} from './prerender-pages.mjs';
-import {isolatedPrerender} from './production-builder.mjs';
+import {isolatedPrerender,prerenderProduction} from './production-builder.mjs';
 import { rename } from '../runtime/fs.mjs';
 import { writeRuntimeContract } from './runtime-contract.mjs';
 import { writeBuildOutput } from './output-contract.mjs';
@@ -7,11 +8,13 @@ import { bundleRuntime } from './bundle-runtime.mjs';
 import {withPersistentTransforms} from './transform-cache.mjs';
 import {applicationEntry, frameworkImportName, frameworkRuntimeImportPattern} from './framework-imports.mjs';
 import { expandLocales, localizedStaticPaths } from './i18n.mjs';
-import { build as bundle, withCompilation, configureCompiler, compilerSource,buildAnalysisRecords,buildAnalysisRoutes,devDependencies,devStylePlans,devStyleDependencies,devModules,readCompilerFile } from './compiler.mjs';
+import { build as bundle, withCompilation, configureCompiler, compilerSource,buildAnalysisRecords,buildAnalysisRoutes,devDependencies,devStylePlans,devStyleDependencies,devModules,readCompilerFile,compilationGraphCacheReport } from './compiler.mjs';
+import {retainDeploymentAssets} from './deployment-assets.mjs';
+import {selectHtmlOnlyRoutes} from './html-only-config.mjs';
 import {writeBuildAnalysis} from './analyze.mjs';
 import {routeFiles} from './dev-discovery.mjs';
 import {writeTypedRoutes} from './typed-routes.mjs';
-import { mkdir, readFile, writeFile, rm, cp, copyFile, stat, readdir } from 'node:fs/promises';
+import { mkdir, readFile, writeFile, rm, cp, copyFile, stat, readdir, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
@@ -40,20 +43,22 @@ import { createRefreshTransform, createSourceLocationTransform, devSingletonsPlu
 import { snapshotEnvConfig } from '../runtime/env.mjs';
 import { validateStaticPaths } from '../runtime/pages-paths.mjs';
 import { projectTsconfig, checkTypeScript } from './typescript.mjs';
+import {createReactCompilerTransform} from './react-compiler.mjs';
+import {writeReactCompilerReport,reactCompilerReport} from './react-compiler-report.mjs';
 export { staticPath } from '../runtime/pages-paths.mjs';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const compatibleModules = new Set(['link', 'head', 'router', 'compat/router', 'next-router-context', 'next-app-router-context', 'image', 'cache', 'dynamic', 'error', 'document', 'app', 'script', 'og']);
-const extensions = { '.js': 'jsx', '.jsx': 'jsx', '.mjs': 'jsx', '.cjs': 'jsx', '.ts': 'ts', '.tsx': 'tsx' };
+const compatibleModules = new Set(['link', 'head', 'router', 'compat/router', 'next-router-context', 'next-app-router-context', 'image', 'cache', 'dynamic', 'error', 'document', 'app', 'script', 'og', 'offline', 'redis-cache']);
+const extensions = { '.js': 'jsx', '.jsx': 'jsx', '.mjs': 'jsx', '.cjs': 'jsx', '.ts': 'ts', '.tsx': 'tsx', '.mts': 'ts', '.cts': 'ts' };
 const assetLoaders = Object.fromEntries(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.svg', '.ico', '.woff', '.woff2', '.ttf', '.eot'].map(ext => [ext, 'file']));
 
 // These framework files have already been enumerated: copyFile avoids cp's
 // recursive traversal/stat work for every file. Bound I/O on large installations.
-async function copyRuntimeFiles(stage) {
+async function copyRuntimeFiles(stage,{development=true}={}) {
   const files = (await Promise.all(['runtime', 'compat'].map(async directory => {
     await mkdir(path.join(stage, directory), { recursive: true });
     return (await readdir(path.join(packageRoot, directory)))
-      .filter(name => directory === 'runtime' ? name === 'profiles.json' || name.endsWith('.mjs') && !name.endsWith('.test.mjs') : name.endsWith('.cjs'))
+      .filter(name => directory === 'runtime' ? name === 'profiles.json' || development&&name.endsWith('.mjs') && !name.endsWith('.test.mjs') : name.endsWith('.cjs'))
       .map(name => path.join(directory, name));
   }))).flat();
   let next = 0;
@@ -68,18 +73,18 @@ async function copyRuntimeFiles(stage) {
   if (failed) throw failed.reason;
 }
 
-function compatibilityPlugin({ browser, pageFiles, projectRoot, documentFile, fonts, refresh, locations }) {
+function compatibilityPlugin({ browser, pageFiles, projectRoot, documentFile, serverOnlyFiles, fonts, refresh, locations, reactCompiler }) {
   return {
     name: 'prnext-pages-compatibility',
     setup(esbuild) {
-      applicationEntry(esbuild,readCompilerFile);
+      applicationEntry(esbuild,readCompilerFile,{transformTypedHelpers:browser && !!reactCompiler});
       esbuild.onResolve({ filter: /\.(?:css|scss|sass)$/i }, args => args.importer === documentFile
         ? { errors: [{ text: 'CSS cannot be imported within pages/_document. Move global styles to pages/_app, or return collected styles from Document.getInitialProps.' }] } : undefined);
       esbuild.onResolve({ filter: frameworkRuntimeImportPattern }, args => {
         const name = frameworkImportName(args.path);
         if (!compatibleModules.has(name)) return { errors: [{ text: `PRNext does not implement ${args.path} yet (imported by ${args.importer}). Supported runtime imports: next/link, next/head, next/router, next/image, next/cache, next/dynamic, next/error, next/document, next/app, next/script.` }] };
         if (browser && name === 'document') return { errors: [{ text: `${args.path} is server-only. Import Document, Html, Head, Main and NextScript from pages/_document, not from a browser page or component.` }] };
-        if (browser && ['cache', 'og'].includes(name)) return { errors: [{ text: `${args.path} is server-only and cannot be imported by a browser component.` }] };
+        if (browser && ['cache', 'og', 'redis-cache'].includes(name)) return { errors: [{ text: `${args.path} is server-only and cannot be imported by a browser component.` }] };
         const file = name === 'compat/router' ? 'compat-router' : name;
         return browser ? { path: path.join(packageRoot, 'compat', file + '.cjs') } : { path: `../compat/${file}.cjs`, external: true };
       });
@@ -95,10 +100,15 @@ function compatibilityPlugin({ browser, pageFiles, projectRoot, documentFile, fo
         });
         esbuild.onLoad({ filter: /.*/, namespace: 'prnext-empty' }, () => ({ contents: '', loader: 'js' }));
       }
-      esbuild.onLoad({ filter: /\.(?:[cm]?js|jsx|tsx?)$/, namespace: 'file' }, async args => {
+      esbuild.onLoad({ filter: /\.(?:[cm]?[jt]s|[jt]sx)$/, namespace: 'file' }, async args => {
         if (browser && args.path === documentFile) return { errors: [{ text: 'pages/_document is server-only and cannot be imported by a browser page or component.' }] };
         const original=await readCompilerFile(args.path,args.prnextSource);
-        const source = await fonts.transform(locations?await locations(original,args.path):original, args.path);
+        // Pages shares a server graph with API handlers, Document and data
+        // loaders. Keep that entire graph original: an uppercase JSX utility
+        // may be called normally there, outside a React render. Browser render
+        // graphs receive memoization before instrumentation and JSX lowering.
+        const compiled=browser && reactCompiler && args.path!==documentFile && !serverOnlyFiles.has(args.path) ? await reactCompiler(original,args.path,{loaderOutput:args.prnextSource!==undefined}) : original;
+        const source = await fonts.transform(locations?await locations(compiled,args.path):compiled, args.path);
         assertSupportedSource(source, args.path);
         const dynamicSource = transformDynamicImports(source, args.path, { projectRoot, mode: browser ? 'browser' : 'server' });
         let contents = browser && pageFiles.has(args.path) ? stripServerCode(dynamicSource, args.path) : dynamicSource;
@@ -183,13 +193,15 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
   const customRoutes = await compileCustomRoutes(config);
   const buildId = await generateBuildId(config, { dev });
   const scanOptions={basePath:config.basePath,pageExtensions:config.pageExtensions,i18n:config.i18n};
-  let project;
+  let project,deferredRoutes=[];
   if(dev && Array.isArray(devRoutes)) {
     const discovery=await scanProject(projectRoot,{...scanOptions,devAppFiles:new Set()});
     project=await scanProject(projectRoot,{...scanOptions,devAppFiles:routeFiles(discovery,devRoutes)});
     await writeTypedRoutes(projectRoot,discovery,config);
+    deferredRoutes=discovery.routes.filter(route=>!devRoutes.includes(route.pattern)&&!route.internal&&!route.errorStatus);
     project.routes=project.routes.filter(route=>devRoutes.includes(route.pattern)||route.internal||route.errorStatus);
   } else project=await scanProject(projectRoot,scanOptions);
+  if(!dev&&config.htmlOnly.length)selectHtmlOnlyRoutes(project.routes,config.htmlOnly,config);
   if(!dev || !Array.isArray(devRoutes))await writeTypedRoutes(projectRoot,project,config);
   const stage = path.join(project.root, `.prnext-build-${randomUUID()}`);
   const destination = await prepareBuildDirectory(project.root, config.distDir);
@@ -199,25 +211,32 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
   await addBuiltinPagesErrors(project, stage);
   const manifest = { version: 1, dev, buildId, cacheId: randomUUID(), previewModeId: randomUUID().replaceAll('-', ''), previewModeEncryptionKey: randomBytes(32).toString('hex'),
     ...(dev && Array.isArray(devRoutes) ? {devOnDemand:true} : {}), ...(dev && devSession ? {devSequence,devSession} : {}), ...(dev ? {devForceRefresh,devAffectedModules,devIndicators:config.devIndicators,...(devTools?{devTools}:{})} : {}),
-    config: { i18n: config.i18n, skipMiddlewareUrlNormalize: config.skipMiddlewareUrlNormalize, compress: config.compress, poweredByHeader: config.poweredByHeader, reactStrictMode: config.reactStrictMode, cacheComponents: config.cacheComponents, cacheLife: config.cacheLife, images: config.images, ...publicPaths }, customRoutes, routes: [], prerendered: [],
+    config: { i18n: config.i18n, skipMiddlewareUrlNormalize: config.skipMiddlewareUrlNormalize, compress: config.compress, poweredByHeader: config.poweredByHeader, reactStrictMode: config.reactStrictMode, cacheComponents: config.cacheComponents, partialPrefetching: config.partialPrefetching, navigationCache: config.navigationCache, cacheLife: config.cacheLife, htmlOnly:config.htmlOnly, images: config.images, ...publicPaths }, customRoutes, routes: [], prerendered: [],
     ...(project.pagesErrors ? { pagesErrors: project.pagesErrors } : {}) };
   // Its build-unique name is known before bundling and avoids a hash cycle
   // between page entry URLs and the manifest that lists those entries.
+  if(!dev)manifest.config.deploymentId=manifest.cacheId;
   const pagesManifestUrl = `${publicPaths.assetBase}/pages-manifest-${manifest.cacheId}.json`;
   if (dev) manifest.devClient = `${publicPaths.assetBase}/dev-manifest-${manifest.cacheId}.json`;
   const development = dev ? { buildId, clientManifest: manifest.devClient, onDemand:manifest.devOnDemand===true, sequence:devSequence, session:devSession, indicator:config.devIndicators,...(devTools?{tools:devTools}:{}) } : undefined;
   const refresh = dev ? createRefreshTransform(project.root, {generation:manifest.cacheId,forceGeneration:devForceRefresh,forceFiles:devAffectedModules}) : undefined;
   const locations = dev ? createSourceLocationTransform(project.root) : undefined;
+  const reactCompiler = config.reactCompiler ? createReactCompilerTransform(project.root, config.reactCompiler, {dev}) : undefined;
+  const serverOnlyFiles = new Set();
+  if (reactCompiler) for (const file of [...project.routes.filter(route=>route.kind==='api').map(route=>route.file),...(project.document?[project.document]:[])]) {
+    serverOnlyFiles.add(file);serverOnlyFiles.add(await realpath(file));
+  }
   const fonts = createFonts({ projectRoot: project.root, stage, assetBase: publicPaths.assetBase });
-  const cssModules = createCssModules({ projectRoot: project.root, stage, assetBase: publicPaths.assetBase, sassOptions: config.sassOptions, cssEngine:config.cssEngine });
+  const cssModules = createCssModules({ projectRoot: project.root, stage, assetBase: publicPaths.assetBase, sassOptions: config.sassOptions, cssEngine:config.cssEngine,dev,config });
   configureCompiler({config,root:project.root,stage,buildId,dev,incremental,devInputs,tsconfig,assetBase:publicPaths.assetBase});
   try {
-    await copyRuntimeFiles(stage);
+    await copyRuntimeFiles(stage,{development:dev});
     // Runtime copies must work even when dotenv is nested beneath the PRNext
     // package instead of hoisted beside the application's dependencies.
     await bundle({ entryPoints: [path.join(packageRoot, 'runtime/env.mjs')], outfile: path.join(stage, 'runtime/env.mjs'), bundle: true, platform: 'node', format: 'esm', target: 'node22', logLevel: 'silent', banner: { js: "import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);" } });
     await prepareImageResponse(stage);
     manifest.config.serverActions = config.experimental.serverActions;
+    if(config.workerMemory && !dev)manifest.config.workerMemory=config.workerMemory;
     if (config.workerRetirement) manifest.config.workerRetirement = config.workerRetirement;
     if(config.workerPreload&&!dev)manifest.config.workerPreload=config.workerPreload;
     const cacheHandlers = await prepareCacheHandlers({ config, projectRoot: project.root, stage, environment });
@@ -236,7 +255,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
       serverEntries[route.id] = serverEntry;
       if (route.kind === 'page') {
         const clientEntry = path.join(stage, '.entries', route.id + '.client.jsx');
-        await writeFile(clientEntry, browserEntry(route, project.app, pagesManifestUrl, { ...publicPaths, strictMode: config.reactStrictMode === true }, development));
+        await writeFile(clientEntry, browserEntry(route, project.app, pagesManifestUrl, { ...publicPaths, deploymentId:dev?undefined:manifest.cacheId, strictMode: config.reactStrictMode === true }, development));
         clientEntries[route.id] = clientEntry;
       }
       manifest.routes.push({ id: route.id, pattern: route.pattern, kind: route.kind, module: `server/${route.id}.mjs`, css: [],
@@ -245,7 +264,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     }
     const common = { absWorkingDir: project.root, bundle: true, logLevel: 'silent', jsx: 'automatic', loader: assetLoaders, assetNames: '[name]-[hash]', publicPath: publicPaths.assetBase, metafile: true, define: { 'process.env.NODE_ENV': JSON.stringify(dev ? 'development' : 'production'), ...environment } };
     if (Object.keys(serverEntries).length) {
-      const server = await bundle({ ...common, entryPoints: serverEntries, outdir: path.join(stage, 'server'), outExtension: { '.js': '.mjs' }, platform: 'node', format: 'esm', splitting: true, chunkNames: 'chunk-[hash]', banner: { js: "import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);" }, target: 'node22', sourcemap: dev, plugins: [moduleResolutionPlugin(config.turbopack, project.root), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: false, pageFiles, projectRoot: project.root, documentFile: project.document, fonts, locations }), npmPackagesPlugin({ pages: true, projectRoot: project.root, transpilePackages: config.transpilePackages, serverExternalPackages: config.serverExternalPackages }), cssModules.plugin(false)] });
+      const server = await bundle({ ...common, entryPoints: serverEntries, outdir: path.join(stage, 'server'), outExtension: { '.js': '.mjs' }, platform: 'node', format: 'esm', splitting: true, chunkNames: 'chunk-[hash]', banner: { js: "import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);" }, target: 'node22', sourcemap: dev, plugins: [moduleResolutionPlugin(config.turbopack, project.root), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: false, pageFiles, projectRoot: project.root, documentFile: project.document, serverOnlyFiles, fonts, locations, reactCompiler }), npmPackagesPlugin({ pages: true, projectRoot: project.root, transpilePackages: config.transpilePackages, serverExternalPackages: config.serverExternalPackages }), cssModules.plugin(false)] });
       fonts.record(server.metafile);
       const serverChunks = new Set(Object.keys(server.metafile.outputs).filter(file => file.endsWith('.mjs')).map(file => path.basename(file)));
       for (const [output, metadata] of Object.entries(server.metafile.outputs)) {
@@ -260,7 +279,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
       }
     }
     if (Object.keys(clientEntries).length) {
-      const browser = await bundle({ ...common, entryPoints: clientEntries, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', chunkNames: 'chunk-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], splitting: true, minify: !dev, sourcemap: dev || config.productionBrowserSourceMaps, define: { 'process.env': '{}', ...common.define }, plugins: [moduleResolutionPlugin(config.turbopack, project.root), ...(dev ? [devSingletonsPlugin()] : []), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: true, pageFiles, projectRoot: project.root, documentFile: project.document, fonts, refresh, locations }), cssModules.plugin(true)] });
+      const browser = await bundle({ ...common, entryPoints: clientEntries, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', chunkNames: 'chunk-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], splitting: true, minify: !dev, sourcemap: dev || config.productionBrowserSourceMaps, define: { 'process.env': '{}', ...common.define }, plugins: [moduleResolutionPlugin(config.turbopack, project.root), ...(dev ? [devSingletonsPlugin()] : []), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: true, pageFiles, projectRoot: project.root, documentFile: project.document, serverOnlyFiles, fonts, refresh, locations, reactCompiler }), cssModules.plugin(true)] });
       fonts.record(browser.metafile);
       const byEntry = new Map(Object.entries(clientEntries).map(([id, file]) => [path.resolve(file), id]));
       for (const [output, metadata] of Object.entries(browser.metafile.outputs)) {
@@ -277,27 +296,35 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     await compileMiddleware({ project, stage, manifest, dev, moduleResolution: config.turbopack, defineEnvironment: environment });
     if (manifest.middleware) manifest.middleware.bodySizeLimit = config.experimental.proxyClientMaxBodySize;
     await prepareMetadataRoutes(project, stage);
-    await compileApp({ project, stage, manifest, moduleResolution: config.turbopack, cssModules, fonts, images, dev, defineEnvironment: environment, productionBrowserSourceMaps: config.productionBrowserSourceMaps, serverExternalPackages: config.serverExternalPackages });
+    await compileApp({ project, stage, manifest, reactCompiler: config.reactCompiler, moduleResolution: config.turbopack, cssModules, fonts, images, dev, defineEnvironment: environment, productionBrowserSourceMaps: config.productionBrowserSourceMaps, serverExternalPackages: config.serverExternalPackages });
     if(manifest.config.workerPreload)for(const pattern of config.workerPreload.routes){
       const selected=manifest.routes.find(route=>!route.internal&&route.pattern===pattern);
       if(!selected||selected.cacheConfig?.runtime==='edge'||selected.handlerConfig?.runtime==='edge')throw new Error(`workerPreload route ${pattern} must be an existing Node route.`);
     }
+    await compileInstrumentation({root:project.root,stage,manifest,config,dev,environment});
+    if(deferredRoutes.length){
+      for(const route of deferredRoutes){
+        const module=`server/dev-deferred-${route.id}.mjs`;await writeFile(path.join(stage,module),'export {};\n');
+        manifest.routes.push({id:route.id,pattern:route.pattern,kind:route.kind,router:route.router,module,devDeferred:true,css:[],cacheConfig:{maxDuration:120}});
+      }
+    }
     await checkTypeScript(project.root, config, { dev, tsconfig });
     fonts.attach(manifest);
     expandLocales(manifest);
     // All runtime preparation must finish before its shared modules are built;
     // no staged renderer has been imported before this production-only point.
-    if (!dev) await bundleRuntime(stage,{projectRoot:project.root});
+    if (!dev) await bundleRuntime(stage,{projectRoot:project.root,sourceDirectory:path.join(packageRoot,'runtime')});
     // Node caches CJS React by filename, not NODE_ENV. Once development metadata
     // imports load it, subsequent production renders need a clean process too.
     if(dev) developmentModulesLoaded = true;
-    if(!dev && (incremental || developmentModulesLoaded)) Object.assign(manifest,await isolatedPrerender(project.root,stage,manifest));
+    if(!dev) Object.assign(manifest,await (incremental || developmentModulesLoaded ? isolatedPrerender : prerenderProduction)(project.root,stage,manifest,{prerender:config.prerender}));
     else {await prerender(stage, manifest, dev);await prerenderApp(stage, manifest, dev);}
-    const pages = manifest.routes.filter(route => route.kind === 'page' && route.router !== 'app' && !route.internal);
+    const pages = manifest.routes.filter(route => route.kind === 'page' && route.router !== 'app' && !route.internal && !route.devDeferred);
     const publicPage = route => ({ ...(route.locale ? {locale:route.locale,originalPattern:route.originalPattern} : {}), id: route.id, pattern: route.pattern, client: route.client, css: route.css, ...(route.fonts ? { fonts: route.fonts } : {}), ssg: !!route.ssg, ssp: !!route.ssp, gip: !!route.gip, appGip: !!route.appGip });
     if (pages.length || manifest.pagesErrors) {
       const publicPages = {
         buildId: manifest.buildId,
+        ...(manifest.config.deploymentId?{deploymentId:manifest.config.deploymentId}:{}),
         ...publicPaths,
         // Header rules cannot select a different page. Other server routing
         // stays authoritative, including middleware with conditional behavior.
@@ -327,10 +354,16 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
       const appRoute = manifest.routes.find(route => route.router === 'app' && route.kind === 'page' && route.client);
       await writeFile(path.join(stage, 'assets', path.basename(manifest.devClient)), JSON.stringify({ buildId,
         pages: manifest.routes.filter(route => route.router !== 'app' && route.client).map(publicPage),
-        ...(appRoute ? { app: { client: appRoute.client, css: appRoute.css } } : {}),
+        ...(appRoute ? { app: { client: appRoute.client, css: appRoute.css, routes: manifest.routes.filter(route=>route.router==='app'&&route.kind==='page'&&route.client).map(({id,pattern,css,cssScopes})=>({id,pattern,css,cssScopes:cssScopes||[]})) } } : {}),
       }));
     }
-    await writeRuntimeContract(stage);
+    // A report belongs to this successful staging generation, never to the
+    // runtime manifest or public assets. Publishing the stage is atomic below.
+    if(!dev)await retainDeploymentAssets({stage,destination,manifest,policy:config.deploymentRetention});
+    const compilationCache=compilationGraphCacheReport();
+    if(!dev)await writeFile(path.join(stage,'compilation-cache-report.json'),JSON.stringify(compilationCache,null,2)+'\n');
+    const compilerReport=await writeReactCompilerReport(stage,reactCompilerReport());
+    await writeRuntimeContract(stage,{deployment:!dev,htmlOnly:!dev&&manifest.routes.some(route=>route.htmlOnly),workerMemory:Boolean(manifest.config.workerMemory),incrementalCache:Boolean(manifest.config.cacheHandler)});
     await writeFile(path.join(stage, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
     await writeBuildOutput(stage, manifest);
     // Offline compression is a deployment optimization. Recompressing source
@@ -360,7 +393,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     } finally { await rm(pointerTemporary, {force:true}); }
     await exported?.commit();
     if (hadDestination) await rm(backup, { recursive: true, force: true });
-    return { ...manifest, outputDirectory: destination, durationMs: Math.round(performance.now() - started) };
+    return { ...manifest, outputDirectory: destination, durationMs: Math.round(performance.now() - started),reactCompilerReport:compilerReport,compilationCache };
   } catch (error) {
     await rm(stage, { recursive: true, force: true });
     if (error.errors) error.message = error.errors.map(item => `${item.location ? `${item.location.file}:${item.location.line}: ` : ''}${item.text}`).join('\n');

package/build/instrumentation.mjs

@@ -0,0 +1,30 @@
+import {access,writeFile,mkdir} from 'node:fs/promises';
+import path from 'node:path';
+import {build} from './compiler.mjs';
+import {compileEdge} from './edge.mjs';
+import {moduleResolutionPlugin} from './module-resolution.mjs';
+
+export async function compileInstrumentation({root,stage,manifest,config,dev,environment}) {
+  const found=[];
+  for(const directory of ['', 'src'])for(const extension of ['ts','js','mjs','cjs']){
+    const file=path.join(root,directory,'instrumentation.'+extension);
+    try{await access(file);found.push(file);}catch(error){if(error.code!=='ENOENT')throw error;}
+  }
+  if(!found.length)return;
+  if(found.length>1)throw Error('Only one instrumentation file is allowed, in the project root or src directory.');
+  const file=found[0],entry=path.join(stage,'.entries/instrumentation.mjs');manifest.instrumentation={};
+  await mkdir(path.dirname(entry),{recursive:true});
+  await writeFile(entry,`import * as hooks from ${JSON.stringify(file)};export const register=hooks.register??hooks.default?.register;export const onRequestError=hooks.onRequestError??hooks.default?.onRequestError;`);
+  for(const runtime of ['node','rsc']){
+    const module=`server/instrumentation-${runtime}.mjs`;
+    await build({absWorkingDir:root,entryPoints:[entry],outfile:path.join(stage,module),bundle:true,packages:'external',platform:'node',format:'esm',target:'node22',banner:{js:"import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);"},conditions:runtime==='rsc'?['react-server']:[],sourcemap:dev,logLevel:'silent',
+      define:{...environment,'process.env.NODE_ENV':JSON.stringify(dev?'development':'production'),'process.env.NEXT_RUNTIME':'"nodejs"'},
+      plugins:[moduleResolutionPlugin(config.turbopack,root)]});
+    manifest.instrumentation[runtime]=module;
+  }
+  if(manifest.middleware?.runtime==='edge'||manifest.routes.some(route=>route.cacheConfig?.runtime==='edge'||route.handlerConfig?.runtime==='edge')){
+    const module='server/instrumentation-edge.mjs';
+    await compileEdge({file:entry,outfile:path.join(stage,module),projectRoot:root,dev,defineEnvironment:environment});
+    manifest.instrumentation.edge=module;
+  }
+}

package/build/metadata-routes.mjs

@@ -60,7 +60,7 @@ export async function prepareMetadataRoutes(project, stage) {
     let source;
     if (dynamic) {
       const config = await validateAppConfig(route.file);
-      source = `import * as source from ${JSON.stringify(route.file)};import {metadataHandler,metadataStaticParams} from '../runtime/metadata-route.mjs';export * from ${JSON.stringify(route.file)};\n`;
+      source = `import * as source from ${JSON.stringify(route.file)};import {metadataHandler,metadataStaticParams} from 'prnext-internal:metadata-route';export * from ${JSON.stringify(route.file)};\n`;
       if (config.revalidate === undefined) source += 'export const revalidate=false;\n';
       const options = JSON.stringify({ kind, image, multiple, contentType });
       source += `export const GET=metadataHandler(source,${options});\n`;

package/build/migration-audit.mjs

@@ -6,7 +6,7 @@ import { checkProject } from './check.mjs';
 import { frameworkImportName } from './framework-imports.mjs';
 import { packageManifest } from '../native/resolve.mjs';
 
-const supported = new Set([...Object.keys(packageManifest.exports).map(name => name.slice(2)), 'font/google', 'font/local', 'next-router-context', 'next-app-router-context']);
+const supported = new Set([...Object.keys(packageManifest.exports).map(name => frameworkImportName(name.slice(2))), 'font/google', 'font/local', 'next-router-context', 'next-app-router-context']);
 const ignored = new Set(['node_modules', '.git', '.next', '.prnext', '.prnext-cache', 'dist', 'build', 'out', 'coverage', 'test-results', '__tests__']);
 const code = /\.(?:[cm]?[jt]s|[jt]sx)$/;
 function walkAst(node, visit) {

package/build/native-type-config.mjs

@@ -0,0 +1,37 @@
+import {readFile} from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {parseTsconfig,createPathsMatcher} from 'get-tsconfig';
+import {parse,modify,applyEdits} from 'jsonc-parser';
+
+// TypeScript 7 has no stable legacy compiler API. Parse configuration only with
+// the dedicated JSONC/config resolvers; semantic checking stays in native tsc.
+export async function nativeTypeConfig(filename,helper){
+  let source=await readFile(filename,'utf8');const errors=[];
+  const own=parse(source,errors,{allowTrailingComma:true});
+  if(errors.length||!own||typeof own!=='object'||Array.isArray(own))throw new Error('Cannot configure typed routes: invalid tsconfig.');
+  const config=parseTsconfig(filename),directory=path.dirname(filename);
+  const format={insertSpaces:true,tabSize:2,eol:source.includes('\r\n')?'\r\n':'\n'};
+  const update=(location,value)=>{source=applyEdits(source,modify(source,location,value,{formattingOptions:format}));};
+  const files=own.files??config.files??[];
+  if(!Array.isArray(files)||files.some(file=>typeof file!=='string'))throw new Error('tsconfig.files must be an array.');
+  if(!files.some(file=>path.resolve(directory,file)===helper))update(['files'],[...files,path.relative(directory,helper).replaceAll(path.sep,'/')]);
+  const options=config.compilerOptions||{},paths=options.paths||{};
+  const missing=['next','next/*'].filter(name=>!Object.hasOwn(paths,name));
+  if(!missing.length)return source;
+  const base=options.baseUrl?path.resolve(directory,options.baseUrl):directory;
+  const relative=filename=>{const value=path.relative(base,filename).replaceAll(path.sep,'/');return value.startsWith('.')?value:'./'+value;};
+  const resolved=own.compilerOptions?.paths?{...paths}:{};
+  if(!own.compilerOptions?.paths){
+    const matcher=createPathsMatcher({path:filename,config});
+    for(const pattern of Object.keys(paths)){
+      const probe='__prnext_type_path__',values=matcher?.(pattern.replace('*',probe));
+      if(!values?.length)throw new Error('Cannot resolve inherited TypeScript path: '+pattern);
+      resolved[pattern]=values.map(value=>relative(value).replaceAll(probe,'*'));
+    }
+  }
+  const compat=fileURLToPath(new URL('../compat/',import.meta.url));
+  for(const name of missing)resolved[name]=[relative(path.join(compat,name==='next'?'index.d.ts':'*.d.cts'))];
+  update(['compilerOptions','paths'],resolved);
+  return source;
+}

package/build/persistent-cache.mjs

@@ -17,7 +17,21 @@ async function frameworkHash(){
     const hash=createHash('sha256');
     for(const f of files)hash.update(f).update(await readFile(path.join(packageRoot,'build',f)));
     hash.update(await readFile(path.join(packageRoot,'package.json')));
-    for(const name of ['@babel/core','@babel/parser','@babel/traverse','@babel/generator','@babel/types','esbuild'])hash.update(name+':'+require(name+'/package.json').version);
+    for(const name of ['@babel/core','@babel/parser','@babel/traverse','@babel/generator','@babel/types','babel-plugin-react-compiler','esbuild'])hash.update(name+':'+require(name+'/package.json').version);
+    // CSS graph outputs also depend on the installed style engine and browser
+    // database, including nested/non-hoisted installations with different pins.
+    for(const name of ['lightningcss','browserslist','caniuse-lite','electron-to-chromium','postcss','postcss-value-parser','postcss-flexbugs-fixes','postcss-preset-env']){
+      let filename;
+      try{filename=require.resolve(name+'/package.json');}
+      catch{
+        let directory=path.dirname(require.resolve(name));
+        while(true){
+          try{const candidate=path.join(directory,'package.json'),value=JSON.parse(await readFile(candidate,'utf8'));if(value.name===name){filename=candidate;break;}}catch{}
+          const parent=path.dirname(directory);if(parent===directory)throw new Error(`Cannot fingerprint ${name}`);directory=parent;
+        }
+      }
+      hash.update(name).update(await readFile(filename));
+    }
     return hash.digest('hex');
   })();
   return frameworkIdentity;
@@ -78,8 +92,9 @@ export async function readCacheRecord(directory,key,limit=16*1024*1024){
     return JSON.parse(record.payload);
   }catch{return null;}finally{await file?.close().catch(()=>{});}
 }
-export async function writeCacheRecord(directory,key,value,limit=16*1024*1024){
+export async function writeCacheRecord(directory,key,value,limit=16*1024*1024,{maxFiles=64}={}){
   if(!directory||!/^[a-f0-9]{64}$/.test(key))return false;
+  if(!Number.isInteger(maxFiles)||maxFiles<1||maxFiles>4096)return false;
   const filename=path.join(directory,key+'.json'),temporary=filename+'.'+randomUUID()+'.tmp';
   try{
     const payload=JSON.stringify(value),body=JSON.stringify({version:1,key,checksum:cacheHash(payload),payload});
@@ -91,7 +106,7 @@ export async function writeCacheRecord(directory,key,value,limit=16*1024*1024){
       const stat=await lstat(path.join(directory,name)).catch(()=>null);if(stat?.isFile()&&!stat.isSymbolicLink())records.push({name,size:stat.size,time:stat.mtimeMs});
     }
     records.sort((a,b)=>b.time-a.time);let total=0;
-    for(let i=0;i<records.length;i++){total+=records[i].size;if(i>=64||total>MAX_DISK)await unlink(path.join(directory,records[i].name)).catch(()=>{});}
+    for(let i=0;i<records.length;i++){total+=records[i].size;if(i>=maxFiles||total>MAX_DISK)await unlink(path.join(directory,records[i].name)).catch(()=>{});}
     return true;
   }catch{return false;}finally{await unlink(temporary).catch(()=>{});}
 }

package/build/precompress.mjs

@@ -20,7 +20,7 @@ async function digest(stream, limit = Infinity) {
 // this bounded index and serialize publication/eviction, including overwrites.
 // Cached bytes are still decoded and hashed before reuse below.
 async function compressionCache(directory) {
-  if (!directory) return;
+  if (!directory || process.env.PRNEXT_BUILD_CACHE === '0') return;
   try {
     await mkdir(directory,{recursive:true});
     const info=await lstat(directory);