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

package/README.md

@@ -93,6 +93,8 @@ npm run dev -- examples/app
 
 Source builds require Rust 1.98 and native build tools: Visual Studio C++ tools and a Windows SDK on Windows, Xcode command line tools on macOS, or a C/C++ toolchain and pkg-config on Linux. Install NASM on macOS, Linux and Windows x64.
 
+For a larger integration example, see the [SaaS reference](https://github.com/Lorkydey/PRNext/tree/main/examples/saas-reference): Better Auth, PostgreSQL/Drizzle, French/English routing and a portable standalone build. It has its own dependency lockfile and database setup.
+
 </details>
 
 ## Documentation

package/build/actions.mjs

@@ -9,28 +9,39 @@ import path from 'node:path';
 
 const traverse = traverseModule.default || traverseModule;
 const generate = generateModule.default || generateModule;
+// Kept inside the compiler process. The development session is public metadata
+// and must never be usable by itself to derive an action encryption key.
+const processDevelopmentSecret = randomBytes(32);
 function hasDirective(node,value) { return node?.directives?.some(item=>item.value.value===value); }
 function removeDirective(node,value) { if(node?.directives) node.directives=node.directives.filter(item=>item.value.value!==value); }
 
-export function createServerActions({ projectRoot }) {
-  const salt = randomBytes(32);
+export function createServerActions({ projectRoot, developmentSession, developmentSecret }) {
+  if (developmentSession !== undefined && (typeof developmentSession !== 'string' || !developmentSession || developmentSession.length > 1024)) throw new TypeError('A development action session must be a non-empty string of at most 1024 characters');
+  if (developmentSecret !== undefined && (typeof developmentSecret !== 'string' || !/^[A-Za-z0-9+/]{43}=$/.test(developmentSecret))) throw new TypeError('A development action secret must encode 32 random bytes');
+  const privateSecret = developmentSecret ? Buffer.from(developmentSecret,'base64') : processDevelopmentSecret;
+  const derive = purpose => createHmac('sha256', privateSecret).update(JSON.stringify([purpose, path.resolve(projectRoot), developmentSession])).digest();
+  const salt = developmentSession ? derive('action-identities') : randomBytes(32);
   const modules = new Map();
   const actions = new Map();
   const configured = process.env.NEXT_SERVER_ACTIONS_ENCRYPTION_KEY;
   if (configured && (!/^[A-Za-z0-9+/]+={0,2}$/.test(configured) || ![16,24,32].includes(Buffer.from(configured,'base64').length))) throw new Error('NEXT_SERVER_ACTIONS_ENCRYPTION_KEY must be a base64-encoded 16, 24, or 32 byte AES key.');
-  const actionKey = configured ? Buffer.from(configured,'base64').toString('base64') : randomBytes(32).toString('base64');
-  function identity(file,name) { return createHmac('sha256',salt).update(path.relative(projectRoot,file).replaceAll(path.sep,'/')+'\0'+name).digest('hex'); }
-  function register(file,name,binding) {
-    const id=identity(file,name);
+  const actionKey = configured ? Buffer.from(configured,'base64').toString('base64') : (developmentSession ? derive('action-encryption') : randomBytes(32)).toString('base64');
+  function identity(file,name,revision) { return createHmac('sha256',salt).update(path.relative(projectRoot,file).replaceAll(path.sep,'/')+'\0'+name+(revision?'\0'+revision:'')).digest('hex'); }
+  function register(file,name,binding,revision) {
+    const id=identity(file,name,revision);
     if(!actions.has(id)) actions.set(id,{id,file,binding});
     return id;
   }
 
-  function analyze(source,file) {
-    const key=file+'\0'+createHash('sha256').update(source).digest('hex');
+  function analyze(source,file,{revisionSource=source}={}) {
+    const sourceHash=createHash('sha256').update(source).digest('hex');
+    // Cache transforms embed a generation ID. IDs for an unchanged action must
+    // follow its original source revision, not those ephemeral emitted bytes.
+    const revision=developmentSession?createHash('sha256').update(revisionSource).digest('hex'):sourceHash;
+    const key=file+'\0'+sourceHash+(developmentSession?'\0'+revision:'');
     if(modules.has(key))return modules.get(key);
     const template=JSON.parse(cachedTransform('server-action-analysis',source,[projectRoot,file],()=>JSON.stringify(analyzeTemplate(source,file))));
-    const ids=new Map(template.registrations.map(item=>[item.id,register(file,item.name,item.binding)]));
+    const ids=new Map(template.registrations.map(item=>[item.id,register(file,item.name,item.binding,developmentSession?revision:undefined)]));
     let server=template.server;
     for(const [previous,current]of ids)server=server.replaceAll(previous,current);
     const result={...template,server,declared:template.declared.map(item=>({...item,id:ids.get(item.id)}))};
@@ -203,13 +214,14 @@ export function createServerActions({ projectRoot }) {
   return {
     actions, actionKey,
     // Only compiler-generated module-level action proxies bypass React Refresh.
-    // Their random reference IDs change each build; they are not component exports.
-    isServerModule(source,file) {
-      return source.includes('use server') && analyze(source,file).moduleServer === true;
+    // Their opaque IDs are not component exports. Development keeps unchanged
+    // modules valid within one session; production IDs still change each build.
+    isServerModule(source,file,options) {
+      return source.includes('use server') && analyze(source,file,options).moduleServer === true;
     },
-    transform(source,file,mode) {
+    transform(source,file,mode,options) {
       if(!source.includes('use server')) return source;
-      const result=analyze(source,file);
+      const result=analyze(source,file,options);
       // A Route Handler invokes the implementation as ordinary server code.
       // It does not serialize functions through Flight or manufacture proxies.
       // Analyze first to preserve validation and the shared action registry.

package/build/app.mjs

@@ -6,9 +6,9 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { createRequire, builtinModules } from 'node:module';
 import { fileURLToPath } from 'node:url';
-import { parse } from '@babel/parser';
 import * as t from '@babel/types';
-import { rewriteServerChunks } from './transform.mjs';
+import {analyzeSource} from './source-analysis.mjs';
+import { rewriteServerChunkOutputFiles } from './transform.mjs';
 import { transformDynamicImports } from './dynamic.mjs';
 import { createServerActions } from './actions.mjs';
 import { expandActionExports } from './action-exports.mjs';
@@ -21,6 +21,9 @@ import {createReactCompilerTransform} from './react-compiler.mjs';
 import {createAppStyleGraph, appStyleScopes, planAppStyleEntries} from './app-styles.mjs';
 import {selectHtmlOnlyRoutes} from './html-only-config.mjs';
 import {createHtmlOnlyGraph} from './html-only-graph.mjs';
+import {createLazyDynamicImports} from './lazy-dynamic-imports.mjs';
+import {developmentActionMetadata} from './dev-action-graph.mjs';
+import {immutableStylePlan, executeStylePlan, createStyleOutputWriter} from './parallel-plan.mjs';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const extensions = { '.js': 'jsx', '.jsx': 'jsx', '.mjs': 'jsx', '.cjs': 'jsx', '.ts': 'ts', '.tsx': 'tsx', '.mts': 'ts', '.cts': 'ts' };
@@ -42,77 +45,28 @@ export async function validateReactVersions(resolveFromProject) {
   }
 }
 
-function sourceAst(source, filename) {
-  return parse(source, { sourceType: 'unambiguous', sourceFilename: filename, plugins: ['jsx', ...(/\.[cm]?tsx?$/.test(filename) ? ['typescript'] : [])] });
-}
 function clientDirective(source, filename) {
   if (!source.includes('use client')) return false;
-  return sourceAst(source, filename).program.directives.some(directive => directive.value.value === 'use client');
+  return analyzeSource(source,filename).directives.includes('use client');
 }
 
 function frameworkDirective(source, filename) {
   if (clientDirective(source, filename)) return true;
   if (!source.includes('use server')) return false;
-  function contains(node) {
-    if (!node || typeof node !== 'object') return false;
-    if (t.isDirective(node) && node.value.value === 'use server') return true;
-    return (t.VISITOR_KEYS[node.type] || []).some(key => Array.isArray(node[key]) ? node[key].some(contains) : contains(node[key]));
-  }
-  return contains(sourceAst(source, filename));
+  return analyzeSource(source,filename).hasServerDirective;
 }
 
 /** Enumerate runtime ESM exports without evaluating client code in the server build. */
-async function exportedNames(file, esbuild, seen = new Set()) {
+export async function exportedNames(file, esbuild, seen = new Set()) {
   if (seen.has(file)) return new Set();
   seen.add(file);
   const source = await compilerSource(file);
-  const ast = sourceAst(source, file);
-  const names = new Set();
-  for (const node of ast.program.body) {
-    if (t.isExportDefaultDeclaration(node)) { names.add('default'); continue; }
-    if (node.exportKind === 'type') continue;
-    if (t.isExportNamedDeclaration(node)) {
-      if (node.declaration && !t.isTSInterfaceDeclaration(node.declaration) && !t.isTSTypeAliasDeclaration(node.declaration) && !node.declaration.declare) {
-        for (const name of Object.keys(t.getOuterBindingIdentifiers(node.declaration))) names.add(name);
-      }
-      for (const specifier of node.specifiers) if (specifier.exportKind !== 'type') names.add(specifier.exported.name ?? specifier.exported.value);
-    }
-    if (t.isExportAllDeclaration(node)) {
-      const resolved = await esbuild.resolve(node.source.value, { resolveDir: path.dirname(file), kind: 'import-statement', pluginData: { prnextExportScan: true } });
-      if (resolved.errors.length || !resolved.path || resolved.external) throw new Error(`Cannot enumerate client boundary exports from ${node.source.value} in ${file}. Use explicit named re-exports.`);
+  const analysis=analyzeSource(source,file),names=new Set(analysis.runtimeExports);
+  for (const specifier of analysis.exportStars) {
+      const resolved = await esbuild.resolve(specifier, { resolveDir: path.dirname(file), kind: 'import-statement', pluginData: { prnextExportScan: true } });
+      if (resolved.errors.length || !resolved.path || resolved.external) throw new Error(`Cannot enumerate client boundary exports from ${specifier} in ${file}. Use explicit named re-exports.`);
       for (const name of await exportedNames(resolved.path, esbuild, seen)) if (name !== 'default') names.add(name);
-    }
-  }
-  // CommonJS is supported for npm and PRNext compatibility components. The default
-  // is module.exports; statically assigned properties are named exports as in Node.
-  function visit(node) {
-    if (!node || typeof node !== 'object') return;
-    if (t.isCallExpression(node) && t.isMemberExpression(node.callee) && t.isIdentifier(node.callee.object, { name: 'Object' }) && t.isIdentifier(node.callee.property, { name: 'defineProperty' }) && t.isIdentifier(node.arguments[0], { name: 'exports' }) && t.isStringLiteral(node.arguments[1]) && node.arguments[1].value !== '__esModule') {
-      names.add('default');
-      names.add(node.arguments[1].value);
-    }
-    if (t.isAssignmentExpression(node) && t.isMemberExpression(node.left)) {
-      const left = node.left;
-      const property = left.computed ? left.property.value : left.property.name;
-      if (t.isIdentifier(left.object, { name: 'module' }) && property === 'exports') {
-        names.add('default');
-        if (t.isObjectExpression(node.right)) for (const item of node.right.properties) {
-          const key = item.computed ? item.key?.value : item.key?.name ?? item.key?.value;
-          if (typeof key === 'string') names.add(key);
-        }
-      }
-      if (t.isIdentifier(left.object, { name: 'exports' }) || (t.isMemberExpression(left.object) && t.isIdentifier(left.object.object, { name: 'module' }) && left.object.property.name === 'exports')) {
-        names.add('default');
-        if (typeof property === 'string') names.add(property);
-      }
-    }
-    for (const key of t.VISITOR_KEYS[node.type] || []) {
-      const child = node[key];
-      if (Array.isArray(child)) child.forEach(visit); else visit(child);
-    }
   }
-  visit(ast.program);
-  names.delete('__esModule');
   return names;
 }
 
@@ -177,16 +131,18 @@ function routeEntry(route, globalError, dev) {
 }
 
 /** Compile independent React Server and client graphs. The RSC graph contains only references to client boundaries. */
-export async function compileApp({ project, stage, manifest, cssModules, fonts, images, dev, reactCompiler = false, defineEnvironment = {}, productionBrowserSourceMaps = false, serverExternalPackages = [], moduleResolution = {} }) {
+export async function compileApp({ project, stage, manifest, cssModules, fonts, images, dev, devActionSecret, reactCompiler = false, defineEnvironment = {}, productionBrowserSourceMaps = false, serverExternalPackages = [], moduleResolution = {},lazyDynamicImports=false,devLazyRequest,devLazyOnly=false,devLazyActivated=[], parallelBuilds=false }) {
+  if(devLazyOnly&&(!dev||!lazyDynamicImports||!devLazyRequest))throw Error('Deferred-only compilation requires a registered development import');
   const refresh = dev ? createRefreshTransform(project.root, {generation:manifest.cacheId,forceGeneration:manifest.devForceRefresh,forceFiles:manifest.devAffectedModules}) : undefined;
   const locations = dev ? createSourceLocationTransform(project.root) : undefined;
   const compileReact = reactCompiler ? createReactCompilerTransform(project.root, reactCompiler, {dev}) : undefined;
   const { basePath = '', assetPrefix = '', assetBase = '/_prnext/assets', trailingSlash = false, skipTrailingSlashRedirect = false } = manifest.config || {};
   const publicPath = assetBase + '/';
-  const routes = project.routes.filter(route => route.router === 'app');
+  const lazy=dev&&lazyDynamicImports?createLazyDynamicImports({root:project.root,stage,manifest,request:devLazyRequest,activated:devLazyActivated}):undefined;
+  const routes = devLazyOnly?[]:project.routes.filter(route => route.router === 'app');
   const htmlOnly = dev ? new Set() : selectHtmlOnlyRoutes(project.routes, manifest.config.htmlOnly, manifest.config);
   const htmlGraph = !dev && htmlOnly.size ? createHtmlOnlyGraph(project.root) : undefined;
-  if (project.appNotFound) {
+  if (project.appNotFound&&!devLazyOnly) {
     const file = path.join(stage, '.entries', 'app-not-found.jsx');
     await writeFile(file, `import {notFound} from 'next/navigation';export default function MissingRoute(){notFound()}`);
     const segments = project.appNotFound.segments.map(segment => ({ ...segment }));
@@ -199,12 +155,12 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
     routes.push({ ...project.appNotFound, segments, id, file, pattern: '/_not-found', kind: 'page', router: 'app', internal: true });
     manifest.appNotFound = id;
   }
-  if (!routes.length) return;
+  if (!routes.length&&!devLazyOnly) return;
   if (!manifest.config.cacheComponents && routes.some(route => route.cacheConfig?.instant !== undefined || route.pageConfig?.instant !== undefined || route.segments?.some(segment => segment.staticConfig?.instant !== undefined))) throw new Error('instant requires cacheComponents: true.');
   if (!manifest.config.cacheComponents && routes.some(route => route.cacheConfig?.ensureStatic !== undefined || route.pageConfig?.ensureStatic !== undefined || route.segments?.some(segment => segment.staticConfig?.ensureStatic !== undefined))) throw new Error('ensureStatic requires cacheComponents: true.');
-  const actions = createServerActions({ projectRoot: project.root });
-  function actionTransform(source, file, mode, runtime = 'nodejs') {
-    const result = actions.transform(source, file, mode);
+  const actions = createServerActions({ projectRoot: project.root,developmentSession:dev?manifest.devSession:undefined,developmentSecret:dev?devActionSecret:undefined });
+  function actionTransform(source, file, mode, runtime = 'nodejs', revisionSource = source) {
+    const result = actions.transform(source, file, mode, {revisionSource});
     if (mode !== 'browser') for (const action of actions.actions.values()) if (action.file === file) {
       (action.runtimes ||= new Set()).add(runtime);
     }
@@ -226,6 +182,7 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
     for (const segment of route.segments || []) if (segment.layout) cacheSegments.set(await canonicalFile(segment.layout), 'layout');
   }
   let browserStyleRevision;
+  const writeParallelStyles = parallelBuilds ? createStyleOutputWriter(path.join(stage, 'assets')) : undefined;
   const resolveFromProject = createRequire(path.join(project.root, 'package.json'));
   await validateReactVersions(resolveFromProject);
   const nativePackages = createNativePackages(project.root, { isClientSource: frameworkDirective });
@@ -314,14 +271,17 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
           htmlGraph?.source(args.path, original);
           // Only Client Component graphs use React's memo-cache runtime. Server
           // Components, route handlers and Server Action graphs remain untouched.
-          const compiled=compileReact && (browser || mode==='ssr') ? await compileReact(original,args.path,{loaderOutput:args.prnextSource!==undefined}) : original;
-          const source = await fonts.transform(await expandActionExports(locations?await locations(compiled,args.path):compiled, args.path, async (specifier, importer) => {
+          const compile = compileReact && (browser || mode==='ssr');
+          const locateFirst = !!(compile && reactCompiler.backend==='oxc' && locations);
+          const input = locateFirst ? await locations(original,args.path) : original;
+          const compiled = compile ? await compileReact(input,args.path,{loaderOutput:args.prnextSource!==undefined}) : input;
+          const source = await fonts.transform(await expandActionExports(locations && !locateFirst ? await locations(compiled,args.path) : compiled, args.path, async (specifier, importer) => {
             const resolved = await esbuild.resolve(specifier, { resolveDir: path.dirname(importer), kind: 'import-statement', pluginData: { prnextExportScan: true } });
             return resolved.errors.length || resolved.external || resolved.namespace !== 'file' ? undefined : resolved.path;
           }), args.path);
           const cacheSegment = cacheSegments.get(await canonicalFile(args.path)) || '';
           const cachedSource = transformCacheComponents(source, args.path, { enabled: manifest.config.cacheComponents, handlers: manifest.config.cacheHandlers, projectRoot: project.root, mode, buildId: manifest.cacheId, segment: cacheSegment });
-          const actionSource = actionTransform(cachedSource, args.path, mode);
+          const actionSource = actionTransform(cachedSource, args.path, mode, 'nodejs', original);
           const builtin = path.dirname(args.path) === path.join(packageRoot, 'compat') && forcedClient.has(path.basename(args.path));
           if (rsc && (builtin || clientDirective(source, args.path))) {
             htmlGraph?.issue(args.path, 'a Client Component or interactive framework component');
@@ -334,8 +294,9 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
             const references = boundary.exports.map((name, index) => builtin && path.basename(args.path) === 'image.cjs' && name === 'getImageProps' ? `export {getImageProps} from ${JSON.stringify(path.join(packageRoot, 'compat/image-shared.cjs'))};` : `const ref${index}=registerClientReference(function(){throw new Error(${JSON.stringify(`Cannot call client export ${name} from a Server Component (${path.relative(project.root, args.path)}).`)});},${JSON.stringify(boundary.id)},${JSON.stringify(name)});export {ref${index} as ${JSON.stringify(name)}};`);
             return { contents: `import {registerClientReference} from 'react-server-dom-webpack/server';\n${references.join('\n')}`, loader: 'js', resolveDir: path.dirname(args.path) };
           }
-          let contents = transformDynamicImports(actionSource, args.path, { projectRoot: project.root, mode: rsc ? 'rsc' : browser ? 'browser' : 'server' });
-          if (browser && refresh && !actions.isServerModule(cachedSource,args.path)) contents = await refresh(contents, args.path);
+          let contents = transformDynamicImports(actionSource, args.path, { projectRoot: project.root, mode: rsc ? 'rsc' : browser ? 'browser' : 'server',dev });
+          if(browser&&lazy)contents=lazy.transform(contents,args.path);
+          if (browser && refresh && !actions.isServerModule(cachedSource,args.path,{revisionSource:original})) contents = await refresh(contents, args.path);
           return { contents, loader: extensions[path.extname(args.path)] || 'jsx', resolveDir: path.dirname(args.path) };
         });
       },
@@ -397,11 +358,14 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
     const result = await compileEdge({ file, outfile, projectRoot: project.root, dev, defineEnvironment, reactMode: mode, defaultExport, transformTypedHelpers:!!compileReact && mode==='ssr',
       plugins: [moduleResolutionPlugin(moduleResolution, project.root), edgeGraphPlugin(mode), images.plugin(), fonts.plugin(), cssModules.plugin(false)],
       transformSource: async (source, file, builder, {loaderOutput=false}={}) => {
-        const compiled=compileReact && mode==='ssr' ? await compileReact(source,file,{loaderOutput}) : source;
-        return actionTransform(await fonts.transform(await expandActionExports(locations?await locations(compiled,file):compiled, file, async (specifier, importer) => {
+        const compile = compileReact && mode==='ssr';
+        const locateFirst = !!(compile && reactCompiler.backend==='oxc' && locations);
+        const input = locateFirst ? await locations(source,file) : source;
+        const compiled = compile ? await compileReact(input,file,{loaderOutput}) : input;
+        return actionTransform(await fonts.transform(await expandActionExports(locations && !locateFirst ? await locations(compiled,file) : compiled, file, async (specifier, importer) => {
           const resolved = await builder.resolve(specifier, {resolveDir:path.dirname(importer),kind:'import-statement',pluginData:{prnextExportScan:true}});
           return resolved.errors.length || resolved.external || resolved.namespace !== 'file' ? undefined : resolved.path;
-        }), file), file, mode, 'edge');
+        }), file), file, mode, 'edge', source);
       } });
     fonts.record(result.metafile);
     styleGraph.record(result.metafile);
@@ -435,35 +399,39 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
     fonts.record(output.metafile);
     styleGraph.record(output.metafile);
     htmlGraph?.record(output.metafile);
+    const chunks = new Set(Object.keys(output.metafile.outputs).filter(file => file.endsWith('.mjs')).map(file => path.basename(file)));
+    const importers = new Set(Object.entries(output.metafile.outputs).filter(([file,metadata])=>file.endsWith('.mjs')&&metadata.imports.some(item=>!item.external)).map(([file])=>path.resolve(project.root,file)));
+    output={...output,outputFiles:rewriteServerChunkOutputFiles(output.outputFiles,chunks,assetBase,importers)};
     for (const file of output.outputFiles) {
       await mkdir(path.dirname(file.path), { recursive: true });
       await writeFile(file.path, file.contents);
     }
-    const chunks = new Set(Object.keys(output.metafile.outputs).filter(file => file.endsWith('.mjs')).map(file => path.basename(file)));
     for (const [file, metadata] of Object.entries(output.metafile.outputs)) {
       const absolute = path.resolve(project.root, file);
-      if (file.endsWith('.mjs') && metadata.imports.some(item => !item.external)) await rewriteServerChunks(absolute, chunks, assetBase);
       if (!metadata.entryPoint && !file.endsWith('.map') && !file.endsWith('.mjs')) await cp(absolute, path.join(stage, 'assets', path.basename(file)));
     }
     return output;
   }
 
-  async function collectBrowserStyles(browserEntries) {
+  async function collectBrowserStyles(browserEntries,force=false) {
     const revision = `${boundaries.size}:${actions.actions.size}:${nativePackages.version}`;
-    if (browserStyleRevision === revision) return;
+    if (!force&&browserStyleRevision === revision) return;
     // SSR intentionally erases ssr:false loaders. Discover their dependencies
     // in one browser graph, then classify styles by reachability from each root.
     const discovery = await bundle({ ...common, write: false, entryPoints: browserEntries, outdir: path.join(stage, '.browser-styles'),
       platform: 'browser', format: 'esm', target: ['es2022'], splitting: true,
       define: { 'process.env': '{}', ...common.define },
-      plugins: [moduleResolutionPlugin(moduleResolution, project.root), ...(dev ? [devSingletonsPlugin()] : []), images.plugin(), fonts.plugin(), graphPlugin('browser', { omitGlobalStyles: false }), nativePackages.plugin('browser'), cssModules.plugin(true)] });
+      plugins: [...(lazy?[lazy.plugin()]:[]),moduleResolutionPlugin(moduleResolution, project.root), ...(dev ? [devSingletonsPlugin()] : []), images.plugin(), fonts.plugin(), graphPlugin('browser', { omitGlobalStyles: false }), nativePackages.plugin('browser'), cssModules.plugin(true)] });
+    await lazy?.discover(discovery.metafile);
     fonts.record(discovery.metafile);
     styleGraph.record(discovery.metafile);
-    const entryIds = new Map(await Promise.all(Object.entries(browserEntries).map(async ([id, file]) => [await canonicalFile(file), id])));
+    const entryIds = new Map((await Promise.all(Object.entries(browserEntries).map(async ([id, file]) => [[path.resolve(file), id], [await canonicalFile(file), id]]))).flat());
     const globalRoots = [], normalRoots = [];
     for (const output of Object.values(discovery.metafile.outputs)) {
       if (!output.entryPoint) continue;
-      const id = entryIds.get(await canonicalFile(path.resolve(project.root, output.entryPoint)));
+      // Dynamic entry points can contain a query/fragment identity rather
+      // than a physical filename. Only configured roots need classification.
+      const id = entryIds.get(path.resolve(project.root, output.entryPoint));
       if (id) (id === globalErrorId ? globalRoots : normalRoots).push(output.entryPoint);
     }
     async function collect(roots, target) {
@@ -514,12 +482,13 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
   const browserRevision = () => `${boundaryRevision()}:${cssFiles.size}:${globalErrorCssFiles.size}:${nativePackages.version}`;
   // Route Handlers have a Node React environment and must not share RSC chunks
   // that import registerServerReference or client-reference registration.
-  await serverBuild(handlerEntries, 'server', 'route');
+  if (!devLazyOnly) await serverBuild(handlerEntries, 'server', 'route');
   for (;;) {
     // Each graph consumes discoveries from the preceding one. Discovering a
     // client boundary in RSC is normal: SSR and browser below already include
     // it. Only discoveries made too late for a graph require another pass.
     const emittedActions = actionRevision();
+    if (!devLazyOnly) {
     for (const action of actions.actions.values()) {
       const entry = path.join(stage, '.entries', 'action-' + action.id + '.mjs');
       await writeFile(entry, `export {${JSON.stringify(action.binding)} as invoke} from ${JSON.stringify(action.file)};`);
@@ -527,8 +496,10 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
       if (!action.runtimes?.size || action.runtimes.has('nodejs')) entries['action-' + action.id] = entry;
     }
     await serverBuild(entries, 'server', 'rsc');
+    }
     const serverNativeVersion = nativePackages.version;
     const emittedBoundaries = boundaryRevision();
+    if (!devLazyOnly) {
     const ssrEntries = {};
     const globalSsrEntries = {};
     for (const boundary of boundaries.values()) {
@@ -539,63 +510,78 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
     await serverBuild(ssrEntries, 'app-ssr', 'ssr');
     for (const boundary of boundaries.values()) if (boundary.edge) await edgeAppBuild(path.join(stage, '.entries', boundary.id + '.ssr.mjs'), path.join(stage, 'app-ssr-edge', boundary.id + '.mjs'), 'ssr', boundary.exports.includes('default'));
     await serverBuild(globalSsrEntries, 'app-ssr', 'ssr', globalErrorCssFiles);
+    }
     const browserEntries = {};
     for (const boundary of boundaries.values()) {
       const entry = path.join(stage, '.entries', boundary.id + '.browser.mjs');
       await writeFile(entry, boundaryEntry(boundary));
       browserEntries[boundary.id] = entry;
     }
-    await collectBrowserStyles(browserEntries);
+    if(!devLazyRequest)await collectBrowserStyles(browserEntries);
+    let lazyEntries={};
+    if(lazy)for(;;){
+      const next=await lazy.targetEntries();
+      if(Object.keys(next).join(',')===Object.keys(lazyEntries).join(','))break;
+      lazyEntries=next;
+      await collectBrowserStyles(devLazyRequest?lazyEntries:{...browserEntries,...lazyEntries},true);
+    }
     globalErrorOnlyCss.clear();
     for (const file of globalErrorCssFiles) if (!cssFiles.has(file)) globalErrorOnlyCss.add(file);
     const emittedBrowserInputs = browserRevision();
-    if (routes.some(route => route.kind === 'page')) {
+    if (devLazyOnly||routes.some(route => route.kind === 'page')) {
     let globalErrorCss = [];
     if (globalErrorCssFiles.size) {
       const styleEntry = path.join(stage, '.entries', 'app-global-error-style.mjs');
       await writeFile(styleEntry, [...globalErrorCssFiles].map(file => `import ${JSON.stringify(file)};`).join('\n'));
       const styles = await bundle({ ...common, entryPoints: { 'app-global-error-style': styleEntry }, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]',
         platform: 'browser', format: 'esm', target: ['es2022'], minify: !dev, sourcemap: dev || productionBrowserSourceMaps,
-        plugins: [moduleResolutionPlugin(moduleResolution, project.root), images.plugin(), fonts.plugin(), graphPlugin('browser', { omitGlobalStyles: false }), cssModules.plugin(true)] });
+        plugins: [moduleResolutionPlugin(moduleResolution, project.root), images.plugin(), fonts.plugin(), graphPlugin('browser', { omitGlobalStyles: false }), cssModules.plugin(true)] }, { role: 'styles' });
       globalErrorCss = Object.values(styles.metafile.outputs).filter(output => output.cssBundle).map(output => publicPath + path.basename(output.cssBundle));
     }
     if (globalErrorId) manifest.app.globalError = { id: globalErrorId, name: 'default', css: globalErrorCss };
     const runtimeEntry = path.join(stage, '.entries', 'app-runtime.mjs');
     const htmlOnlyRoutes = !dev && htmlOnly.size ? routes.filter(route => route.kind === 'page' && !route.internal).map(route => ({pattern:route.pattern,...(htmlOnly.has(route.id)?{htmlOnly:true}:{})})) : undefined;
     const importers = Object.entries(browserEntries).map(([id, file]) => `${JSON.stringify(id)}:()=>import(${JSON.stringify(file)})`);
-    await writeFile(runtimeEntry, `${dev ? `import ${JSON.stringify(devClientFile)};\n` : ''}\nimport {bootstrapApp} from ${JSON.stringify(path.join(packageRoot, 'runtime/app-client.mjs'))};\nbootstrapApp({clientModules:{${importers.join(',')}},...${JSON.stringify({ basePath, assetPrefix, assetBase, htmlOnlyRoutes, trailingSlash, skipTrailingSlashRedirect, deploymentId: dev ? undefined : manifest.cacheId, strictMode: manifest.config.reactStrictMode !== false, cacheComponents: manifest.config.cacheComponents === true, partialPrefetching: manifest.config.partialPrefetching === true, navigationCache: manifest.config.navigationCache, ...(globalErrorId ? { globalErrorId, globalErrorCss } : {}), ...(dev ? { dev: { buildId: manifest.buildId, clientManifest: manifest.devClient, onDemand:manifest.devOnDemand===true, sequence:manifest.devSequence, session:manifest.devSession, indicator:manifest.devIndicators, ...(manifest.devTools ? {tools:manifest.devTools} : {}) } } : {}) })}});\n`);
-    const clientEntries = { 'app-runtime': runtimeEntry, ...browserEntries };
+    if(!devLazyRequest)await writeFile(runtimeEntry, `${dev ? `import ${JSON.stringify(devClientFile)};\n` : ''}\nimport {bootstrapApp} from ${JSON.stringify(path.join(packageRoot, 'runtime/app-client.mjs'))};\nbootstrapApp({clientModules:{${importers.join(',')}},...${JSON.stringify({ basePath, assetPrefix, assetBase, htmlOnlyRoutes, trailingSlash, skipTrailingSlashRedirect, deploymentId: dev ? undefined : manifest.cacheId, strictMode: manifest.config.reactStrictMode !== false, cacheComponents: manifest.config.cacheComponents === true, partialPrefetching: manifest.config.partialPrefetching === true, navigationCache: manifest.config.navigationCache, ...(globalErrorId ? { globalErrorId, globalErrorCss } : {}), ...(dev ? { dev: { buildId: manifest.buildId, clientManifest: manifest.devClient, onDemand:manifest.devOnDemand===true, sequence:manifest.devSequence, session:manifest.devSession, indicator:manifest.devIndicators, ...(manifest.devTools ? {tools:manifest.devTools} : {}) } } : {}) })}});\n`);
+    const clientEntries = devLazyRequest?{...lazyEntries,...lazy.bridgeEntries()}:{ 'app-runtime': runtimeEntry, ...browserEntries,...lazyEntries,...(lazy?lazy.bridgeEntries():{}) };
     const browser = await bundle({ ...common, entryPoints: clientEntries, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', chunkNames: 'app-chunk-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], splitting: true, minify: !dev, sourcemap: dev || productionBrowserSourceMaps,
-      define: { 'process.env': '{}', ...common.define, __PRNEXT_CACHE_COMPONENTS__: JSON.stringify(manifest.config.cacheComponents === true) }, plugins: [moduleResolutionPlugin(moduleResolution, project.root), ...(dev ? [devSingletonsPlugin()] : []), images.plugin(), fonts.plugin(), graphPlugin('browser', { omitAllStyles: true }), nativePackages.plugin('browser'), cssModules.plugin(true, { emitStyles: () => false })] });
+      define: { 'process.env': '{}', ...common.define, __PRNEXT_CACHE_COMPONENTS__: JSON.stringify(manifest.config.cacheComponents === true) }, plugins: [...(lazy?[lazy.plugin()]:[]),moduleResolutionPlugin(moduleResolution, project.root), ...(dev ? [devSingletonsPlugin()] : []), images.plugin(), fonts.plugin(), graphPlugin('browser', { omitAllStyles: !lazy }), nativePackages.plugin('browser'), cssModules.plugin(true, { emitStyles: () => !!lazy })] });
     fonts.record(browser.metafile);
     const entryIds = new Map(Object.entries(clientEntries).map(([id, file]) => [file, id]));
     const edgeBoundaries = new Set([...boundaries.values()].filter(boundary => boundary.edge).map(boundary => boundary.id));
     let client;
     for (const [output, metadata] of Object.entries(browser.metafile.outputs)) {
       if (!metadata.entryPoint || !output.endsWith('.js')) continue;
+      if(lazy?.record(metadata,output))continue;
       const id = entryIds.get(path.resolve(project.root, metadata.entryPoint));
       if (id === 'app-runtime') { client = publicPath + path.basename(output); continue; }
       if (!id) continue;
       manifest.app.clientModules[id] = { id, chunks: [id, publicPath + path.basename(output)], name: '*', ssrModule: `app-ssr/${id}.mjs`, ...(edgeBoundaries.has(id) ? { edgeSsrModule: `app-ssr-edge/${id}.mjs` } : {}), browserModule: publicPath + path.basename(output) };
     }
-    const styleBundles = new Map();
-    for (const route of routes.filter(route => route.kind === 'page')) {
+    const styledRoutes = routes.filter(route => route.kind === 'page');
+    for (const route of styledRoutes) {
       // All esbuild graphs canonicalize their inputs, including symlinked
       // convention files. Match those identities before querying reachability.
       for (const files of appStyleScopes(route)) for (const file of files) styleGraph.alias(file, await canonicalFile(file));
-      const plan = planAppStyleEntries(route, styleGraph);
+    }
+    // Freeze discovery before any independent emission starts. Deduplication
+    // owns each output path once, and linking follows source order even when
+    // builds complete out of order. Failure drains all started jobs first.
+    const plan = immutableStylePlan(styledRoutes, route => planAppStyleEntries(route, styleGraph));
+    const {outputs: styleBundles, concurrency} = await executeStylePlan(plan, async ({styles: files}) => {
+      const id = 'app-style-' + createHash('sha256').update(files.map(file => path.relative(project.root, file).replaceAll(path.sep, '/')).join('\0')).digest('hex').slice(0, 16);
+      const styleEntry = path.join(stage, '.entries', id + '.mjs');
+      await writeFile(styleEntry, files.map(file => `import ${JSON.stringify(file)};`).join('\n'));
+      const output = await bundle({ ...common, ...(writeParallelStyles ? {write: false} : {}), entryPoints: { [id]: styleEntry }, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], minify: !dev, sourcemap: dev || productionBrowserSourceMaps,
+        plugins: [moduleResolutionPlugin(moduleResolution, project.root), images.plugin(), fonts.plugin(), graphPlugin('browser', { omitGlobalStyles: false }), cssModules.plugin(true)] }, { role: 'styles' });
+      if (writeParallelStyles) await writeParallelStyles(output.outputFiles);
+      return Object.values(output.metafile.outputs).filter(output => output.cssBundle).map(output => publicPath + path.basename(output.cssBundle));
+    }, dev ? false : parallelBuilds);
+    if (!dev && parallelBuilds) manifest.buildParallelism = {version: 1, phase: 'app-styles', jobs: plan.jobs.length, concurrency};
+    for (const route of plan.routes) {
       const styles = [];
       const cssScopes = [];
-      for (const { styles:files, path:scopePath, kind } of plan) {
-        const signature = JSON.stringify(files);
-        if (!styleBundles.has(signature)) {
-          const id = 'app-style-' + createHash('sha256').update(files.map(file => path.relative(project.root, file).replaceAll(path.sep, '/')).join('\0')).digest('hex').slice(0, 16);
-          const styleEntry = path.join(stage, '.entries', id + '.mjs');
-          await writeFile(styleEntry, files.map(file => `import ${JSON.stringify(file)};`).join('\n'));
-          const output = await bundle({ ...common, entryPoints: { [id]: styleEntry }, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], minify: !dev, sourcemap: dev || productionBrowserSourceMaps,
-            plugins: [moduleResolutionPlugin(moduleResolution, project.root), images.plugin(), fonts.plugin(), graphPlugin('browser', { omitGlobalStyles: false }), cssModules.plugin(true)] });
-          styleBundles.set(signature, Object.values(output.metafile.outputs).filter(output => output.cssBundle).map(output => publicPath + path.basename(output.cssBundle)));
-        }
+      for (const { signature, path:scopePath, kind } of route.scopes) {
         const css = styleBundles.get(signature);
         styles.push(...css);
         if (route.parallel) cssScopes.push({ path:scopePath, kind, css });
@@ -610,10 +596,13 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
       module: `server/action-${action.runtimes?.has('nodejs')?'':'edge-'}${action.id}.mjs`, export: 'invoke',
       ...(action.runtimes?.has('edge') ? {edgeModule:`server/action-edge-${action.id}.mjs`} : {}),
     }]));
-    if (emittedActions === actionRevision() && emittedBoundaries === boundaryRevision() &&
+    if ((devLazyOnly || emittedActions === actionRevision() && emittedBoundaries === boundaryRevision()) &&
         serverNativeVersion === nativePackages.version && emittedBrowserInputs === browserRevision()) break;
   }
 
+  lazy?.finish();
+  if (dev) manifest.devActions = developmentActionMetadata(project.root, actions.actions.values());
+
   if (htmlGraph) for (const route of routes) if (htmlOnly.has(route.id)) {
     for (const file of [...appStyleScopes(route).flat(), ...(route.metadataFiles || []).map(item=>item.file)].filter(Boolean)) htmlGraph.alias(file, await canonicalFile(file));
     htmlGraph.validate(route);

package/build/build-lock.mjs

@@ -1,71 +1,2 @@
-import { mkdir, writeFile, rename, rm, realpath, lstat, open } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
-import { hostname } from 'node:os';
-import path from 'node:path';
-
-const LOCK = '.prnext-build.lock';
-const busy = message => Object.assign(new Error(message), { code: 'PRNEXT_BUILD_LOCKED' });
-function alive(pid) {
-  try { process.kill(pid, 0); return true; }
-  catch (error) { return error.code !== 'ESRCH'; }
-}
-async function owner(directory) {
-  const info = await lstat(directory);
-  if (!info.isDirectory() || info.isSymbolicLink()) throw busy(`The project lock is not a real directory. Check ${path.basename(directory)} before retrying.`);
-  const file = await open(path.join(directory, 'owner.json'), 'r');
-  try {
-    if ((await file.stat()).size > 4096) throw new Error('oversized owner');
-    const value = JSON.parse(await file.readFile('utf8'));
-    if (!Number.isSafeInteger(value.pid) || value.pid < 1 || typeof value.host !== 'string' || !/^[a-f0-9-]{36}$/.test(value.token)) throw new Error('invalid owner');
-    return value;
-  } finally { await file.close(); }
-}
-
-/** One publisher per canonical project, covering React and direct static imports. */
-export async function withBuildLock(directory, action, {development = false} = {}) {
-  const root = await realpath(directory), lock = path.join(root, development ? '.prnext-dev.lock' : LOCK);
-  const identity = { pid: process.pid, host: hostname(), token: randomUUID(), createdAt: new Date().toISOString() };
-  const prepared = path.join(root, `.prnext-lock-${identity.token}`);
-  await mkdir(prepared, { mode: 0o700 });
-  try {
-    await writeFile(path.join(prepared, 'owner.json'), JSON.stringify(identity), { flag: 'wx', mode: 0o600 });
-    for (let attempt = 0; ; attempt++) {
-      try { await rename(prepared, lock); break; }
-      catch (error) {
-        if (!['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES'].includes(error.code)) throw error;
-        let previous;
-        try { previous = await owner(lock); }
-        catch (cause) {
-          if (cause.code === 'ENOENT' && attempt < 8) continue;
-          throw busy(`Cannot verify the project lock. Check ${path.basename(lock)} before retrying.`);
-        }
-        if (previous.host !== identity.host || alive(previous.pid)) throw busy(development ? `A development server is already running for this project (PID ${previous.pid}). Stop it before starting another.` : `A build is already running for this project (PID ${previous.pid}). Wait for it to finish.`);
-        // Exactly one contender can recover this generation. Never delete a lock
-        // merely because it is old: long builds and suspended processes are valid.
-        let claim;
-        try { claim = await open(path.join(lock, 'recovery'), 'wx', 0o600); }
-        catch (cause) {
-          if (cause.code === 'ENOENT' && attempt < 8) continue;
-          throw busy(`Project lock recovery is in progress. Retry shortly; if recovery was interrupted, check ${path.basename(lock)} manually.`);
-        }
-        const retired = path.join(root, `.prnext-lock-retired-${identity.token}`);
-        try {
-          await claim.writeFile(JSON.stringify(identity)); await claim.close(); claim = null;
-          const current = await owner(lock);
-          if (current.token !== previous.token) {
-            // Do not unlink through this path: the new owner can release and
-            // another generation can appear between our read and the unlink.
-            throw busy('The build lock changed during recovery. Retry the build.');
-          }
-          await rename(lock, retired);
-          await rm(retired, { recursive: true });
-        } finally { await claim?.close(); }
-      }
-    }
-    try { return await action(root); }
-    finally {
-      // Ownership must still match before releasing a lock.
-      if ((await owner(lock)).token === identity.token) await rm(lock, { recursive: true });
-    }
-  } finally { await rm(prepared, { recursive: true, force: true }); }
-}
+// Compiler entry point for the shared publisher and maintenance lock protocol.
+export {withBuildLock} from '../runtime/project-lock.mjs';