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

package/build/dev-lazy-build.mjs

@@ -0,0 +1,77 @@
+import { mkdir, readdir, lstat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { compileApp } from './app.mjs';
+import { configureCompiler } from './compiler.mjs';
+import { createCssModules } from './css-modules.mjs';
+import { createFonts } from './fonts.mjs';
+import { createImages } from './images.mjs';
+import { discardLazyBuild } from '../runtime/dev-lazy-staging.mjs';
+import { loadEnvConfig } from '../runtime/env.mjs';
+
+// Only the latest successful ordinary generation per project is reusable.
+// This private compiler-process registry is not part of browser metadata or IPC.
+const contexts = new Map();
+const CONTEXT_LIMIT = 8, FILE_LIMIT = 16384, BYTE_LIMIT = 128 * 1024 * 1024;
+export function forgetLazyBuildContext(root) {
+  if (root === undefined) contexts.clear(); else contexts.delete(root);
+}
+export function rememberLazyBuildContext(root, { manifest, config, environment, tsconfig, envMode }) {
+  contexts.delete(root);
+  if (!manifest.devLazy || !manifest.dev || !config.experimental.lazyDynamicImports) return;
+  while (contexts.size >= CONTEXT_LIMIT) contexts.delete(contexts.keys().next().value);
+  contexts.set(root, { config, environment, tsconfig, envMode, cacheId: manifest.cacheId,
+    buildId: manifest.buildId, session: manifest.devSession,
+    manifestConfig: structuredClone(manifest.config) });
+}
+/** Reuse the validated configuration of the running generation, not its routes. */
+export async function tryBuildLazyGraph(root, { base, request, devInputs, devSession,
+  devActionSecret, incremental = true } = {}) {
+  if (!base || typeof base.cacheId !== 'string' || !request) throw Error('Invalid deferred build generation');
+  const context = contexts.get(root);
+  // Compiler recycling loses its private context. The caller retains the ordinary
+  // build path for this recovery case; it must never guess another generation.
+  if (!context || context.cacheId !== base.cacheId || context.session !== devSession) return;
+  // Preserve the running generation's env-file mode for supported build-time
+  // hooks. The enclosing build() scope restores the caller's env on every exit.
+  loadEnvConfig(root,{dev:true,mode:context.envMode,inputs:devInputs});
+  const { config, environment, tsconfig } = context;
+  const stage = path.join(root, '.prnext-build-' + randomUUID());
+  try {
+    await mkdir(path.join(stage, '.entries'), { recursive: true });
+    const manifest = { version: 1, dev: true, buildId: context.buildId,
+      cacheId: context.cacheId, devSession, config: structuredClone(context.manifestConfig),
+      routes: [], prerendered: [] };
+    const project = { root, routes: [] };
+    configureCompiler({ config, root, stage, buildId: context.buildId, dev: true,
+      incremental, devInputs, tsconfig, assetBase: manifest.config.assetBase });
+    const fonts = createFonts({ projectRoot: root, stage, assetBase: manifest.config.assetBase });
+    const cssModules = createCssModules({ projectRoot: root, stage,
+      assetBase: manifest.config.assetBase, sassOptions: config.sassOptions,
+      cssEngine: config.cssEngine, dev: true, config });
+    const images = await createImages({ projectRoot: root, stage,
+      assetBase: manifest.config.assetBase, config: config.images });
+    await compileApp({ project, stage, manifest, cssModules, fonts, images, dev: true,
+      devActionSecret, reactCompiler: config.reactCompiler, defineEnvironment: environment,
+      moduleResolution: config.turbopack, serverExternalPackages: config.serverExternalPackages,
+      lazyDynamicImports: true, devLazyRequest: request, devLazyOnly: true });
+    const files = [];
+    let bytes = 0;
+    // This unpublished stage contains only this deferred graph, never other
+    // routes or a copied framework runtime. Publication uses this exact receipt.
+    for (const entry of await readdir(path.join(stage, 'assets'), { withFileTypes: true })) {
+      if (!entry.isFile() || files.length >= FILE_LIMIT) throw Error('Invalid or excessive deferred output assets');
+      const info = await lstat(path.join(stage, 'assets', entry.name));
+      bytes += info.size;
+      if (!info.isFile() || bytes > BYTE_LIMIT) throw Error('Deferred output exceeds the 128 MiB generation budget');
+      files.push({ name: entry.name, bytes: info.size });
+    }
+    files.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    return { ...manifest, outputDirectory: stage, devLazyTemporary: true,
+      devLazyAssets: { version: 1, baseCacheId: context.cacheId, files } };
+  } catch (error) {
+    try { await discardLazyBuild(root, { outputDirectory: stage, devLazyTemporary: true }); }
+    catch (cleanupError) { error.cleanupError = cleanupError; error.message += '; deferred compiler staging cleanup also failed'; }
+    throw error;
+  }
+}

package/build/dynamic.mjs

@@ -59,17 +59,19 @@ function loaderBody(loader) {
 }
 
 /** Add shared hydration IDs without resolving, evaluating or eagerly importing loaders. */
-export function transformDynamicImports(source, filename, { projectRoot, mode = 'browser' } = {}) {
+export function transformDynamicImports(source, filename, { projectRoot, mode = 'browser',dev=false } = {}) {
   if (![...sources].some(name => source.includes(name))) return source;
   projectRoot ||= process.cwd();
-  return cachedTransform('dynamic',source,[filename,projectRoot,mode],()=>transformDynamicImportsUncached(source,filename,{projectRoot,mode}));
+  return cachedTransform('dynamic',source,[filename,projectRoot,mode,dev],()=>transformDynamicImportsUncached(source,filename,{projectRoot,mode,dev}));
 }
 
-function transformDynamicImportsUncached(source, filename, {projectRoot,mode}) {
+function transformDynamicImportsUncached(source, filename, {projectRoot,mode,dev}) {
   const ast = parse(source, { sourceType: 'unambiguous', sourceFilename: filename,
     plugins: ['jsx', ...(/\.[cm]?tsx?$/.test(filename) ? ['typescript'] : [])] });
   const relative = path.relative(projectRoot || process.cwd(), filename).replaceAll(path.sep, '/');
+  const developmentRevision=dev&&mode==='browser'?createHash('sha256').update(generate(ast,{compact:true,comments:false}).code).digest('hex'):undefined;
   let changed = false;
+  let ordinal=0;
   traverse(ast, {
     CallExpression(call) {
       let callee = call.get('callee');
@@ -105,6 +107,10 @@ function transformDynamicImportsUncached(source, filename, {projectRoot,mode}) {
       const generated = t.objectProperty(t.identifier('loadableGenerated'), t.objectExpression([
         t.objectProperty(t.identifier('modules'), t.arrayExpression(ids.map(id => t.stringLiteral(id)))),
       ]));
+      const statement=call.findParent(value=>value.isStatement());
+      const declaration=statement?.parentPath?.isExportNamedDeclaration()?statement.parentPath:statement;
+      const stableModuleCall=call.scope===call.scope.getProgramParent()&&declaration?.parentPath?.isProgram()&&!t.isLoop(declaration.node);
+      const identity=developmentRevision&&stableModuleCall?t.objectProperty(t.identifier('__prnextDevIdentity'),t.stringLiteral(createHash('sha256').update(relative+'\0'+ordinal+++'\0'+developmentRevision).digest('hex').slice(0,24))):undefined;
 
       if (noSSR && mode !== 'browser') {
         const empty = t.arrowFunctionExpression([], t.nullLiteral(), true);
@@ -115,9 +121,10 @@ function transformDynamicImportsUncached(source, filename, {projectRoot,mode}) {
         loader.replaceWith(t.arrowFunctionExpression([], loader.node));
       }
       const target = secondOptions || firstOptions;
-      if (target?.isObjectExpression()) target.node.properties.push(generated);
-      else if (target?.node) target.replaceWith(t.objectExpression([t.spreadElement(target.node), generated]));
-      else call.node.arguments.push(t.objectExpression([generated]));
+      const fields=[generated,...(identity?[identity]:[])];
+      if (target?.isObjectExpression()) target.node.properties.push(...fields);
+      else if (target?.node) target.replaceWith(t.objectExpression([t.spreadElement(target.node), ...fields]));
+      else call.node.arguments.push(t.objectExpression(fields));
       changed = true;
     },
   });

package/build/incremental.mjs

@@ -1,14 +1,76 @@
 import { context } from 'esbuild';
 import { readFile, writeFile, mkdir, realpath } from 'node:fs/promises';
+import { realpath as legacyRealpath } from 'node:fs';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import {clearDirectoryCache} from './directory-cache.mjs';
 import {closeWebpackCompiler,webpackCompilerStats} from './webpack-graph.mjs';
 const contexts = new Map();
 const LIMIT = 8;
-let created = 0, reused = 0;
-export const incrementalCompilerStats = () => ({contexts:contexts.size, created, reused,webpack:webpackCompilerStats()});
+const AUXILIARY_LIMIT = 2;
+const RESERVES = Object.freeze({ main: 6, styles: 2 });
+const counters = () => ({ created: 0, reused: 0, evicted: 0 });
+const roles = () => ({ main: counters(), styles: counters(), auxiliary: counters() });
+const totals = counters(), roleTotals = roles();
+
+function record(metrics, role, event) {
+  totals[event]++;
+  roleTotals[role][event]++;
+  metrics[event]++;
+  metrics.roles[role][event]++;
+}
+
+function roleStats(metrics, active) {
+  return Object.fromEntries(Object.entries(metrics).map(([role, values]) => [role, {
+    ...values,
+    contexts: active.filter(slot => slot.role === role).length,
+  }]));
+}
+
+export function incrementalCompilerStats() {
+  const active = [...contexts.values()];
+  // Counters belong to retained projects, rather than an unbounded registry of
+  // every project ever compiled by this process. Global role totals persist.
+  const projects = [...new Set(active.map(slot => slot.metrics))].map(metrics => {
+    const retained = active.filter(slot => slot.metrics === metrics);
+    return {
+      root: metrics.root,
+      created: metrics.created,
+      reused: metrics.reused,
+      evicted: metrics.evicted,
+      contexts: retained.length,
+      roles: roleStats(metrics.roles, retained),
+    };
+  });
+  return {
+    contexts: contexts.size,
+    ...totals,
+    roles: roleStats(roleTotals, active),
+    projects,
+    limits: { project: LIMIT, auxiliary: AUXILIARY_LIMIT, reserves: { ...RESERVES } },
+    webpack: webpackCompilerStats(),
+  };
+}
+
+function evictionCandidate(group, role) {
+  const candidates = [...contexts].filter(([, slot]) => slot.group === group);
+  if (group === 'auxiliary') return candidates[0];
+  const count = candidateRole => candidates.filter(([, slot]) => slot.role === candidateRole).length;
+  // Both roles can borrow unused capacity. Once full, a role at its reserve
+  // replaces its own oldest graph; a role below its reserve reclaims a loan.
+  if (count(role) >= RESERVES[role]) return candidates.find(([, slot]) => slot.role === role);
+  return candidates.find(([, slot]) => count(slot.role) > RESERVES[slot.role]);
+}
 export async function closeIncrementalCompiler(root) {
+  if (root !== undefined) {
+    try { root = await realpath(root); }
+    catch (error) {
+      // Disposal also runs after users remove a project directory. A supplied
+      // canonical path must still match its retained contexts in that case.
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error;
+      root = path.resolve(root);
+    }
+  }
   clearDirectoryCache();
   const active=[];for(const [key,slot] of contexts)if(root===undefined||slot.root===root){contexts.delete(key);active.push(slot);}
   const results=await Promise.allSettled([...active.map(slot=>slot.context.dispose()),closeWebpackCompiler(root)]);
@@ -16,18 +78,42 @@ export async function closeIncrementalCompiler(root) {
   if(errors.length)throw new AggregateError(errors,'Unable to dispose incremental compiler sessions');
 }
 /** Retain esbuild's parsed module graphs while rebinding per-build framework plugins. */
-export async function incrementalBuild(options, {root,stage,group='project',run=callback=>callback()}) {
-  const canonicalRoot = await realpath(root);
-  if (canonicalRoot !== root) {
-    const canonical = value => typeof value === 'string' ? value.replaceAll(root, canonicalRoot) : Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' && !(value instanceof RegExp) && !ArrayBuffer.isView(value) ? Object.fromEntries(Object.entries(value).map(([key,item]) => [key,canonical(item)])) : value;
-    return incrementalBuild(canonical(options),{root:canonicalRoot,stage:stage.replace(root,canonicalRoot),group,run});
+export async function incrementalBuild(options, {root,stage,group='project',role=group==='auxiliary'?'auxiliary':'main',run=callback=>callback()}) {
+  if (!['project', 'auxiliary'].includes(group) || (group === 'project' ? !Object.hasOwn(RESERVES, role) : role !== 'auxiliary')) {
+    throw new TypeError('Invalid incremental compiler group or role');
   }
+  // Canonical identity is for ownership and disposal only. Compilation paths
+  // and application strings retain the caller's lexical spelling.
+  const ownerRoot = await realpath(root);
   const virtual=path.join(root,'.prnext-incremental-stage');
+  const rootPaths=[root,ownerRoot];
+  if(process.platform==='win32'&&root!==ownerRoot){
+    // Windows resolvers can preserve a short ancestor while resolving the
+    // junction target. The JS realpath walk retains that third spelling.
+    rootPaths.push(await new Promise((resolve,reject)=>legacyRealpath(root,(error,value)=>error?reject(error):resolve(value))));
+  }
+  const virtualPaths=[...new Set(rootPaths.map(directory=>path.join(directory,'.prnext-incremental-stage')))];
+  const stageRelative=path.relative(root,stage);
+  const stagePaths=[...new Set([stage,...rootPaths.map(directory=>path.resolve(directory,stageRelative))])];
+  const relativePath=(directory,value)=>{
+    if(typeof value!=='string'||!path.isAbsolute(value))return;
+    const relative=path.relative(directory,value);
+    if(relative===''||!path.isAbsolute(relative)&&relative!=='..'&&!relative.startsWith('..'+path.sep))return relative;
+  };
+  const withinPaths=(directories,value)=>directories.some(directory=>relativePath(directory,value)!==undefined);
+  const remapPath=(value,directories,target)=>{
+    for(const directory of directories){const relative=relativePath(directory,value);if(relative!==undefined)return path.join(target,relative);}
+    return value;
+  };
   const toVirtual=value=>typeof value==='string'?value.replaceAll(stage,virtual):value;
-  const fromVirtual=value=>typeof value==='string'?value.replaceAll(virtual,stage):value;
+  // esbuild can canonicalize only the parent of a nonexistent virtual file.
+  // Recognize both staging identities on path fields, never application text.
+  const fromVirtual=value=>remapPath(value,[...virtualPaths,...stagePaths],stage);
+  const toVirtualPath=value=>remapPath(value,stagePaths,virtual);
+  const isVirtual=value=>withinPaths(virtualPaths,value),isStaged=value=>withinPaths(stagePaths,value);
   const deep=(value,map)=>typeof value==='string'?map(value):Array.isArray(value)?value.map(item=>deep(item,map)):value&&typeof value==='object'&&!(value instanceof RegExp)&&!ArrayBuffer.isView(value)?Object.fromEntries(Object.entries(value).map(([key,item])=>[map(key),deep(item,map)])):value;
   const realResult=result=>result && {...result,...(result.path?{path:fromVirtual(result.path)}:{}),...(result.resolveDir?{resolveDir:fromVirtual(result.resolveDir)}:{})};
-  const virtualResult=result=>result && {...result,...(result.path?{path:toVirtual(result.path)}:{}),...(result.resolveDir?{resolveDir:toVirtual(result.resolveDir)}:{}),...(result.watchFiles?{watchFiles:result.watchFiles.map(toVirtual)}:{}),...(result.watchDirs?{watchDirs:result.watchDirs.map(toVirtual)}:{})};
+  const virtualResult=result=>result && {...result,...(result.path?{path:toVirtualPath(result.path)}:{}),...(result.resolveDir?{resolveDir:toVirtualPath(result.resolveDir)}:{}),...(result.watchFiles?{watchFiles:result.watchFiles.map(toVirtualPath)}:{}),...(result.watchDirs?{watchDirs:result.watchDirs.map(toVirtualPath)}:{})};
   const hooks=[];
   const initialOptions={...options,plugins:undefined,write:false};
   let slot;
@@ -39,18 +125,24 @@ export async function incrementalBuild(options, {root,stage,group='project',run=
   });
   const normalized=deep(initialOptions,toVirtual);
   const signature=JSON.stringify([normalized,hooks.map(({kind,settings})=>[kind,settings?.namespace,settings?.filter?.source,settings?.filter?.flags]),(options.plugins||[]).map(plugin=>plugin.name)]);
-  const key=group+':'+createHash('sha256').update(signature).digest('hex');
+  const key=JSON.stringify([ownerRoot,root,group,role,createHash('sha256').update(signature).digest('hex')]);
   slot=contexts.get(key);
-  if(slot){contexts.delete(key);reused++;}
+  if(slot){contexts.delete(key);record(slot.metrics,role,'reused');}
   else {
-    while([...contexts.values()].filter(slot=>slot.group===group).length>=(group==='auxiliary'?2:LIMIT)){const [oldest,previous]=[...contexts].find(([,slot])=>slot.group===group);contexts.delete(oldest);await previous.context.dispose();}
-    created++;slot={group,root};
-    slot.current={hooks,run,toVirtual,fromVirtual,virtualResult,stage};
+    const metrics = [...contexts.values()].find(slot => slot.root === ownerRoot)?.metrics || { root: ownerRoot, ...counters(), roles: roles() };
+    while ([...contexts.values()].filter(slot => slot.group === group).length >= (group === 'auxiliary' ? AUXILIARY_LIMIT : LIMIT)) {
+      const [oldest, previous] = evictionCandidate(group, role);
+      contexts.delete(oldest);
+      record(previous.metrics, previous.role, 'evicted');
+      await previous.context.dispose();
+    }
+    slot={group,role,root:ownerRoot,metrics};
+    slot.current={hooks,run,toVirtual,fromVirtual,virtualResult,stage,isVirtual,isStaged};
     slot.context=await context({...normalized,plugins:[{name:'prnext-incremental-delegates',setup(builder){
       slot.builder=builder;
       builder.onResolve({filter:/.*/},async args=>{
         const active=slot.current;
-        if(args.pluginData?.prnextVirtualResolution || !(args.path.startsWith(virtual+path.sep)||args.path.startsWith(active.stage+path.sep)||(args.resolveDir===virtual || args.resolveDir.startsWith(virtual+path.sep))))return;
+        if(args.pluginData?.prnextVirtualResolution || !(active.isVirtual(args.path)||active.isStaged(args.path)||active.isVirtual(args.resolveDir)||active.isStaged(args.resolveDir)))return;
         const result=await builder.resolve(active.fromVirtual(args.path),{resolveDir:active.fromVirtual(args.resolveDir),importer:active.fromVirtual(args.importer),kind:args.kind,with:args.with,pluginData:{...args.pluginData,prnextVirtualResolution:true}});
         const pluginData={...(result.pluginData || args.pluginData)}; delete pluginData.prnextVirtualResolution;
         return {...active.virtualResult(result),pluginData};
@@ -63,13 +155,15 @@ export async function incrementalBuild(options, {root,stage,group='project',run=
         if(settings)builder[kind](settings,callback);else builder[kind](callback);
       });
       builder.onLoad({filter:/.*/,namespace:'file'},async args=>{
-        if(!args.path.startsWith(virtual+path.sep))return;
-        const actual=slot.current.fromVirtual(args.path),extension=path.extname(actual);
+        const active=slot.current;
+        if(!active.isVirtual(args.path))return;
+        const actual=active.fromVirtual(args.path),extension=path.extname(actual);
         return {contents:await readFile(actual),loader:options.loader?.[extension] || ({'.json':'json','.ts':'ts','.tsx':'tsx','.jsx':'jsx','.css':'css'}[extension] || 'js'),resolveDir:path.dirname(args.path)};
       });
     }}]});
+    record(metrics,role,'created');
   }
-  slot.current={hooks,run,toVirtual,fromVirtual,virtualResult,stage};
+  slot.current={hooks,run,toVirtual,fromVirtual,virtualResult,stage,isVirtual,isStaged};
   contexts.set(key,slot);
   const result=await slot.context.rebuild();
   const relativeVirtual=path.basename(virtual),relativeStage=path.basename(stage);

package/build/index.mjs

@@ -13,6 +13,7 @@ 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 {tryBuildLazyGraph,rememberLazyBuildContext,forgetLazyBuildContext} from './dev-lazy-build.mjs';
 import {writeTypedRoutes} from './typed-routes.mjs';
 import { mkdir, readFile, writeFile, rm, cp, copyFile, stat, readdir, realpath } from 'node:fs/promises';
 import path from 'node:path';
@@ -154,7 +155,12 @@ let buildQueue = Promise.resolve();
 let developmentModulesLoaded = false;
 /** Disposing shared compiler contexts must not interrupt another queued build. */
 export function disposeBuildSession(root){
-  const task=buildQueue.then(async()=>{const {closeIncrementalCompiler}=await import('./incremental.mjs');await closeIncrementalCompiler(root);});
+  const task=buildQueue.then(async()=>{
+    const canonicalRoot=root===undefined?undefined:await realpath(root).catch(error=>{if(error.code==='ENOENT'||error.code==='ENOTDIR')return path.resolve(root);throw error;});
+    forgetLazyBuildContext(canonicalRoot);
+    const {closeIncrementalCompiler}=await import('./incremental.mjs');
+    await closeIncrementalCompiler(canonicalRoot);
+  });
   buildQueue=task.catch(()=>{});return task;
 }
 /** Isolate process.env between programmatic builds, including simultaneous calls. */
@@ -184,8 +190,13 @@ export function build(projectRoot, options = {}) {
 }
 
 /** Compile Pages Router and App Router projects. A failed build preserves .prnext. */
-async function buildProject(projectRoot, { dev = false, envMode, incremental = false, devInputs, devRoutes, devSequence, devSession, devTools,devForceRefresh=false,devAffectedModules } = {}) {
+async function buildProject(projectRoot, { dev = false, envMode, incremental = false, devInputs, devRoutes, devSequence, devSession, devActionSecret, devTools,devForceRefresh=false,devAffectedModules,devLazyRequest,devLazyBase,devLazyActivated=[] } = {}) {
   const started = performance.now();
+  if (dev && devLazyRequest && devLazyBase) {
+    const deferred = await tryBuildLazyGraph(projectRoot,{base:devLazyBase,request:devLazyRequest,
+      devInputs,devSession,devActionSecret,incremental});
+    if (deferred) return deferred;
+  }
   const config = await loadProjectConfig(projectRoot, { dev, envMode, devInputs });
   const tsconfig = config.typescript ? await projectTsconfig(projectRoot, config) : undefined;
   const environment = defineEnvironment(config);
@@ -201,6 +212,11 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     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.experimental.lazyDynamicImports){
+    if(project.routes.some(route=>route.router!=='app'&&!route.internal))throw Error('experimental.lazyDynamicImports currently requires an App Router-only application.');
+    if(config.webpack||Object.keys(config.turbopack?.rules||{}).length)throw Error('experimental.lazyDynamicImports currently requires the native compiler without webpack hooks or custom loaders.');
+    if(/^https?:\/\//.test(config.assetPrefix))throw Error('experimental.lazyDynamicImports requires same-origin development assets.');
+  }
   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()}`);
@@ -296,7 +312,18 @@ 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, reactCompiler: config.reactCompiler, 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, devActionSecret:dev?devActionSecret:undefined, defineEnvironment: environment, productionBrowserSourceMaps: config.productionBrowserSourceMaps, serverExternalPackages: config.serverExternalPackages, lazyDynamicImports:dev&&config.experimental.lazyDynamicImports,devLazyRequest,devLazyActivated });
+    if(manifest.devLazy){
+      const css=Object.values(manifest.devLazy.outputs).flatMap(module=>module.css);
+      for(const route of manifest.routes)if(route.router==='app'&&route.kind==='page'){
+        route.css=[...new Set([...route.css,...css])];
+        if(css.length&&Array.isArray(route.cssScopes)){
+          const root=route.cssScopes.find(scope=>scope.kind==='layout'&&!scope.path);
+          if(root)root.css=[...new Set([...root.css,...css])];
+          else route.cssScopes.push({kind:'layout',path:'',css:[...new Set(css)]});
+        }
+      }
+    }
     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.`);
@@ -353,6 +380,7 @@ 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,
+        ...(manifest.devLazy?{lazy:Object.values(manifest.devLazy.outputs)}:{}),
         pages: manifest.routes.filter(route => route.router !== 'app' && route.client).map(publicPage),
         ...(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||[]})) } } : {}),
       }));
@@ -393,6 +421,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 });
+    if(dev&&!devLazyRequest)rememberLazyBuildContext(project.root,{manifest,config,environment,tsconfig,envMode});
     return { ...manifest, outputDirectory: destination, durationMs: Math.round(performance.now() - started),reactCompilerReport:compilerReport,compilationCache };
   } catch (error) {
     await rm(stage, { recursive: true, force: true });

package/build/lazy-dynamic-imports.mjs

@@ -0,0 +1,137 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {createHash} from 'node:crypto';
+import {readFile,writeFile} from 'node:fs/promises';
+import {parse} from '@babel/parser';
+import traverseModule from '@babel/traverse';
+import generateModule from '@babel/generator';
+import * as t from '@babel/types';
+import {generateMapped} from './source-maps.mjs';
+
+const traverse=traverseModule.default||traverseModule;
+const generate=generateModule.default||generateModule;
+const packageRoot=fileURLToPath(new URL('../',import.meta.url));
+const client=fileURLToPath(new URL('../runtime/lazy-import-client.mjs',import.meta.url));
+export const LAZY_IMPORT_LIMIT=128;
+export const LAZY_BRIDGE_LIMIT=4096;
+const javascript=/\.(?:[cm]?[jt]s|[jt]sx)$/;
+// esbuild exposes JSON as an ESM entry with a shared default object and named
+// exports. Give it the same native URL identity as JavaScript export bridges.
+const bridgeable=file=>javascript.test(file)||file.endsWith('.json');
+const digest=value=>createHash('sha256').update(value).digest('hex').slice(0,24);
+const suffixError=()=>({errors:[{text:'lazyDynamicImports cannot safely defer a module with a query or fragment suffix. Disable experimental.lazyDynamicImports to compile this graph normally.'}]});
+
+/** Development-only graph boundaries. No source path is sent to the browser. */
+export function createLazyDynamicImports({root,stage,manifest,request,activated=[]}){
+  const modules=new Map(),bridges=new Map(),shared=new Set(),existingShared=new Set(),entries=new Map(),targetFiles=new Map(),nativeOutputs=new Map(),outputs={};
+  const active=new Set(activated);
+  if(active.size>LAZY_IMPORT_LIMIT)throw Error(`lazyDynamicImports supports at most ${LAZY_IMPORT_LIMIT} active imports`);
+  if(request){
+    if(!/^[a-f0-9]{24}$/.test(request.id)||!Array.isArray(request.modules)||request.modules.length>LAZY_IMPORT_LIMIT||!Array.isArray(request.bridges)||request.bridges.length>LAZY_BRIDGE_LIMIT||!Array.isArray(request.shared)||request.shared.length>LAZY_BRIDGE_LIMIT)throw Error('Invalid deferred import compiler descriptor');
+    for(const item of request.modules){
+      const file=path.resolve(root,item.importer);
+      if(!file.startsWith(root+path.sep)||file.includes(`${path.sep}node_modules${path.sep}`)||!javascript.test(file)||typeof item.request!=='string'||item.request.length>4096||item.id!==digest(item.importer+'\0'+item.request))throw Error('Invalid deferred import registration');
+      modules.set(item.id,item);
+    }
+    if(!modules.has(request.id))throw Error('Unknown deferred import identifier');
+    for(const item of request.bridges){
+      if(typeof item.file!=='string'||typeof item.url!=='string'||!item.url.startsWith(manifest.config.assetBase+'/')||/[\r\n\0]/.test(item.url))throw Error('Invalid deferred module bridge');
+      bridges.set(path.resolve(root,item.file),item.url);
+    }
+    for(const file of request.shared){const absolute=path.resolve(root,file);shared.add(absolute);existingShared.add(absolute);}
+    active.clear();active.add(request.id);
+  }
+  const sourceAst=(source,file)=>parse(source,{sourceType:'unambiguous',sourceFilename:file,plugins:['jsx',...(/\.[cm]?tsx?$/.test(file)?['typescript']:[])]});
+  const eligible=file=>file.startsWith(root+path.sep)&&!file.includes(`${path.sep}node_modules${path.sep}`)&&!file.includes(`${path.sep}.prnext-build-`);
+  function transform(source,file){
+    if(!eligible(file)||!source.includes('import'))return source;
+    const ast=sourceAst(source,file);let binding,changed=false;
+    const replace=node=>{
+      const value=t.isStringLiteral(node)?node.value:t.isTemplateLiteral(node)&&!node.expressions.length?node.quasis[0].value.cooked:undefined;
+      // Suffixes are part of ESM identity; path-only export bridges cannot
+      // represent them. Keep explicit suffixes in the ordinary compiler graph.
+      if(!value||value.length>4096||/[?#]/.test(value)||/^(?:[a-z]+:|\/\/)/i.test(value))return;
+      const importer=path.relative(root,file).split(path.sep).join('/'),id=digest(importer+'\0'+value);
+      if(!modules.has(id)&&modules.size>=LAZY_IMPORT_LIMIT)throw Error(`lazyDynamicImports supports at most ${LAZY_IMPORT_LIMIT} registered imports per generation`);
+      modules.set(id,{id,importer,request:value});
+      changed=true;return id;
+    };
+    traverse(ast,{Program(p){binding=p.scope.generateUidIdentifier('prnextLazyImport');},CallExpression(p){
+      if(!t.isImport(p.node.callee)||p.node.arguments.length!==1)return;
+      const id=replace(p.node.arguments[0]);if(id)p.replaceWith(t.callExpression(t.cloneNode(binding),[t.stringLiteral(id),t.stringLiteral(manifest.config.basePath||'')]));
+    },ImportExpression(p){if(p.node.options)return;const id=replace(p.node.source);if(id)p.replaceWith(t.callExpression(t.cloneNode(binding),[t.stringLiteral(id),t.stringLiteral(manifest.config.basePath||'')]));}});
+    if(!changed)return source;
+    ast.program.body.unshift(t.importDeclaration([t.importSpecifier(t.cloneNode(binding),t.identifier('lazyImport'))],t.stringLiteral(client)));
+    return generateMapped(generate,ast,{comments:true},source,file);
+  }
+  async function discover(metafile){
+    for(const input of Object.keys(metafile.inputs)){
+      const file=path.resolve(root,input);
+      if(!bridgeable(file)||input.startsWith('prnext-')||file.startsWith(packageRoot)||file.startsWith(stage+path.sep)||/\/node_modules\/(?:react|react-dom|react-refresh|react-server-dom-webpack)\//.test(file.split(path.sep).join('/'))||shared.has(file))continue;
+      if(shared.size>=LAZY_BRIDGE_LIMIT)throw Error(`lazyDynamicImports supports at most ${LAZY_BRIDGE_LIMIT} static JavaScript modules`);
+      shared.add(file);
+      // Real ESM entries expose live bindings. CommonJS named exports cannot be
+      // approximated with snapshots: a deferred graph sharing one is rejected.
+      if(file.endsWith('.json')||sourceAst(await readFile(file,'utf8'),file).program.sourceType==='module')bridges.set(file,undefined);
+    }
+  }
+  async function targetEntries(){
+    const result={};
+    for(const id of active){
+      if(!modules.has(id))continue;
+      const name='lazy-'+id,file=path.join(stage,'.entries',name+'.mjs');
+      await writeFile(file,`import * as namespace from ${JSON.stringify('prnext-lazy-entry:'+id)};export {namespace as __prnextLazyModule};`);
+      entries.set(file,{kind:'target',id});result[name]=file;
+    }
+    return result;
+  }
+  function bridgeEntries(){
+    const result=Object.fromEntries([...bridges].filter(([,url])=>!url).map(([file])=>{entries.set(file,{kind:'bridge',file});return ['lazy-bridge-'+digest(file),file];}));
+    for(const file of targetFiles.values())if(!bridges.has(file)&&bridgeable(file)){
+      entries.set(file,{kind:'native',file});result['lazy-native-'+digest(file)]=file;
+    }
+    return result;
+  }
+  function plugin(){return {name:'prnext-lazy-dynamic-boundaries',setup(builder){
+    builder.onResolve({filter:/^prnext-lazy-entry:/},async args=>{
+      const item=modules.get(args.path.slice('prnext-lazy-entry:'.length));
+      if(!item)return {errors:[{text:'Unknown deferred module entry'}]};
+      const result=await builder.resolve(item.request,{resolveDir:path.dirname(path.resolve(root,item.importer)),kind:'dynamic-import',pluginData:{prnextLazyEntry:true}});
+      if(!result.errors.length&&result.suffix)return suffixError();
+      const file=path.resolve(result.path||root),url=bridges.get(file);
+      if(!result.errors.length&&result.namespace==='file')targetFiles.set(item.id,file);
+      if(existingShared.has(file)&&!url)return {errors:[{text:`lazyDynamicImports cannot safely reuse the shared CommonJS module ${path.relative(root,file)}. Convert it to ESM or disable experimental.lazyDynamicImports.`}]};
+      return url?{path:url,external:true}:result;
+    });
+    if(request)builder.onResolve({filter:/.*/},async args=>{
+      if(args.pluginData?.prnextLazyResolving||args.pluginData?.prnextLazyEntry||args.kind==='entry-point'||args.namespace&&args.namespace!=='file')return;
+      const result=await builder.resolve(args.path,{resolveDir:args.resolveDir,importer:args.importer,kind:args.kind,with:args.with,pluginData:{...args.pluginData,prnextLazyResolving:true}});
+      // Aliases and transitive imports may introduce a suffix even when the
+      // registered literal had none. Reject it before looking up a bare bridge.
+      if(!result.errors.length&&result.suffix)return suffixError();
+      if(result.errors.length||result.external||result.namespace!=='file')return;
+      const file=path.resolve(result.path);
+      if(bridges.get(file))return {path:bridges.get(file),external:true};
+      if(existingShared.has(file))return {errors:[{text:`lazyDynamicImports cannot safely reuse the shared CommonJS module ${path.relative(root,file)}. Convert it to ESM or disable experimental.lazyDynamicImports.`}]};
+    });
+  }};}
+  function record(metadata,output){
+    const entry=entries.get(path.resolve(root,metadata.entryPoint||''));
+    if(!entry||!output.endsWith('.js'))return false;
+    const url=manifest.config.assetBase+'/'+path.basename(output);
+    if(entry.kind==='bridge'||entry.kind==='native'){
+      if(entry.kind==='bridge')bridges.set(entry.file,url);
+      nativeOutputs.set(entry.file,{url,css:metadata.cssBundle?[manifest.config.assetBase+'/'+path.basename(metadata.cssBundle)]:[]});
+    }
+    else outputs[entry.id]={url,css:metadata.cssBundle?[manifest.config.assetBase+'/'+path.basename(metadata.cssBundle)]:[]};
+    return true;
+  }
+  function finish(){
+    for(const [id,file]of targetFiles){
+      const native=nativeOutputs.get(file),url=native?.url||bridges.get(file);
+      if(url&&outputs[id])outputs[id]={url,native:true,css:[...new Set([...outputs[id].css,...(native?.css||[])])]};
+    }
+    manifest.devLazy={modules:[...modules.values()],bridges:[...bridges].filter(([,url])=>url).map(([file,url])=>({file:path.relative(root,file).split(path.sep).join('/'),url})),shared:[...shared].map(file=>path.relative(root,file).split(path.sep).join('/')),outputs};
+  }
+  return {transform,discover,targetEntries,bridgeEntries,plugin,record,finish};
+}

package/build/migrate.mjs

@@ -19,18 +19,18 @@ export function parseMigrationArgs(args) {
     const arg = args[index];
     if (arg === '--dry-run') options.dryRun = true;
     else if (arg === '--check') options.check = true;
-    else if (['--against', '--candidate', '--routes', '--timeout'].includes(arg)) {
+    else if (['--against', '--candidate', '--routes', '--timeout', '--browser-scenarios'].includes(arg)) {
       const value = args[++index];
       if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value.`);
-      options[arg.slice(2)] = arg === '--timeout' ? Number(value) : value;
+      options[arg === '--browser-scenarios' ? 'browserScenarios' : arg.slice(2)] = arg === '--timeout' ? Number(value) : value;
     }
     else if (arg === '--no-install') options.install = false;
     else if (arg === '--json') options.json = true;
-    else if (arg.startsWith('-')) throw new Error(`Unknown migrate option: ${arg}. Use --check, --dry-run, --no-install or --json.`);
+    else if (arg.startsWith('-')) throw new Error(`Unknown migrate option: ${arg}. Use --check, --dry-run, --no-install, --browser-scenarios or --json.`);
     else if (directory === undefined) directory = arg;
     else throw new Error('migrate accepts a single project directory.');
   }
-  if ((options.against || options.candidate || options.routes || options.timeout !== undefined) && (!options.check || !options.against || !options.candidate)) throw new Error('Server comparison requires --check, --against and --candidate.');
+  if ((options.against || options.candidate || options.routes || options.timeout !== undefined || options.browserScenarios) && (!options.check || !options.against || !options.candidate)) throw new Error('Server comparison or browser execution requires --check, --against and --candidate.');
   return { directory: path.resolve(directory || '.'), options };
 }