@wular/pnext 0.1.5 → 0.1.7

package/src/cli/build.ts

@@ -25,13 +25,15 @@ import { beginSourceScope, endSourceScope, sourceCacheStats } from '../resolve/s
 import { flushDevModuleCaches } from '../runtime/module-cache'
 import { scanFactsStats } from '../resolve/scan-facts'
 import { clientEntryName } from '../client/chunk-name'
+import { compiledClientReferenceFiles } from '../client/reference'
+import { buildIndexFile } from '../runtime/production'
 import { registerServerRuntime, serverBundleTargetForRuntime } from '../runtime/loader'
 import {
-  buildClientReferenceCss,
   buildGlobalCss,
   buildNotFoundCss,
-  buildRouteCss,
+  buildRouteStylesheets,
   emittedAssetNames,
+  globalCssSources,
   prepareRouteCssChunks,
   registerCssRuntime,
   warmCssPipeline,
@@ -72,6 +74,7 @@ import {
   devServerModuleHref,
   resetModuleGraphFailure,
   setEmitCompiledSpecifiersManifest,
+  setReleaseCompile,
   throwIfModuleGraphFailed,
 } from '../runtime/modules'
 import {
@@ -91,6 +94,8 @@ import {
 import { interceptionMarkerLevels } from '../routing/slots'
 import { writeTypegen } from './typegen'
 import { lookupBuildCache, writeBuildCache } from './build/cache'
+import { emitServerEntry } from './serve/entry'
+import { immutableAssetPath } from './serve/immutable'
 import { createVerboseLogger, type VerboseLogger } from '../utils/verbose'
 import { bold, cyan, dim, green } from '../utils/ansi'
 import type {
@@ -164,6 +169,7 @@ export async function buildProject(root?: string, options: BuildOptions = {}) {
   // Only the vercel adapter's trace step reads the per-artifact specifier
   // sidecars; every other build path pays nothing for them.
   const restoreSpecifiersManifest = setEmitCompiledSpecifiersManifest(options.adapter === 'vercel')
+  const restoreReleaseCompile = setReleaseCompile(true)
   const lifecycle: { warm?: WarmChild } = {}
   try {
     return await runBuild(root, options, lifecycle)
@@ -176,6 +182,7 @@ export async function buildProject(root?: string, options: BuildOptions = {}) {
     lifecycle.warm?.kill()
     endSourceScope()
     restoreSpecifiersManifest()
+    restoreReleaseCompile()
     flushDevModuleCaches()
   }
 }
@@ -224,21 +231,13 @@ async function runBuild(
   const warmMode = options.adapter === 'vercel' ? 'full' : 'compile'
   const warm = startWarmChild(config, warmMode)
   lifecycle.warm = warm
-  await log.step('prepare output directory', async () => {
+  const publicFiles = await log.step('prepare output directory', async () => {
     // Build-owned outputs only: `<outRoot>/dev` belongs to a possibly-running
     // dev server and must survive.
-    await ensureEmptyDir(config.outPath, [devOutSegment])
-    await copyPublicDir(config.publicPath, path.join(config.outPath, 'public'))
+    // Materialized pages sources too: this build's config already resolved into them.
+    await ensureEmptyDir(config.outPath, [devOutSegment, 'pnext-pages-compat'])
+    return copyPublicDir(config.publicPath, path.join(config.outPath, 'public'))
   })
-  // Prebundled server entry for `pnext start`: framework-only, independent of the
-  // app build, so it runs in a child process for the whole build — its bundling
-  // heap never stacks on the build's peak RSS and its wall hides under the build.
-  // Best-effort — a failure only costs start time. Awaited before the summary.
-  const serverEntryDone = import('./serve/entry')
-    .then(entry => entry.emitServerEntryChild(config.outPath))
-    .catch((error: Error) => {
-      console.warn(`pnext build: server entry bundling skipped — ${error.message}`)
-    })
   // The document-level stylesheets run their postcss/Tailwind pass on the CSS
   // worker, so they overlap with the route scan below instead of serializing
   // ahead of it. Awaited before prepareRouteCssChunks — route CSS still builds
@@ -313,6 +312,14 @@ async function runBuild(
   // - those are awaited just before the first route stylesheet is emitted, which lets a Tailwind
   // pass run under the build steps and the client bundles instead of ahead of them.
   prepareRouteCssChunks(routes)
+  // Route stylesheets bundle all at once under the client stage; the loop below publishes each
+  // route's names right before its prerender, after the document ones.
+  const routeStylesheets = buildRouteStylesheets(
+    config,
+    routes.filter(route => route.kind !== 'handler' && !route.dynamicErrorApi),
+    documentCss,
+    { verbose },
+  )
   // output:'export' with trailingSlash:false lays prerendered pages out flat
   // (`/a.html` rather than `/a/index.html`). Only meaningful under compat (the
   // Next config carries `output`); pure-core apps always use the dir layout.
@@ -361,9 +368,11 @@ async function runBuild(
       )
     : undefined
   metadataWarnings?.catch(() => undefined)
-  const staticModuleMetadata = await log.step('core module metadata', () =>
+  // Imports the route modules; the client stage needs none of it, so both run at once.
+  const moduleMetadata = log.step('core module metadata', () =>
     collectStaticModuleMetadata(config, routes),
   )
+  moduleMetadata.catch(() => undefined)
 
   const actionSources = buildState.actionSources ?? buildState.actions.map(a => a.sourceKey)
   // realpath, not resolve: a hybrid app's routes are scanned through the pages-compat mirror, whose
@@ -374,13 +383,18 @@ async function runBuild(
   // A node_modules action module never lands in route.sourceFiles itself (that walk stops at the
   // package boundary), so a route reaching one only through a first-party importer is matched here.
   const actionImporters = new Set((buildState.actionImporters ?? []).map(realFilePath))
+  // Routes share most of their files; resolve each once.
+  const realFiles = new Map<string, string>()
+  const reachesAction = (file: string) => {
+    let real = realFiles.get(file)
+    if (real === undefined) realFiles.set(file, (real = realFilePath(file)))
+    return actionFiles.has(real) || actionImporters.has(real)
+  }
   for (const route of routes) {
     if (
       route.kind === 'page' &&
-      route.sourceFiles.some(file => {
-        const real = realFilePath(file)
-        return actionFiles.has(real) || actionImporters.has(real)
-      })
+      (actionFiles.size > 0 || actionImporters.size > 0) &&
+      route.sourceFiles.some(reachesAction)
     ) {
       addClientEntryReason(route, 'actions')
     }
@@ -408,14 +422,14 @@ async function runBuild(
   // other document does, and those names are only final once the client stage has
   // fingerprinted them — so this render follows the bundle rather than racing it.
   // Result is consumed after the prerender pass, where it always was.
-  const notFoundDocuments = clientBundles.then(() =>
+  const notFoundDocuments = clientBundles.then(async () =>
     renderNotFoundDocuments({
       config,
       log,
       skip: options.buildMode === 'compile',
       documentCss,
       staticMetadataFiles,
-      staticModuleMetadata,
+      staticModuleMetadata: await moduleMetadata,
     }),
   )
   notFoundDocuments.catch(() => undefined)
@@ -428,6 +442,7 @@ async function runBuild(
   ).then(() => log.step('typegen', () => writeTypegen(config, routes)))
   remainingSteps.catch(() => undefined)
   await remainingSteps
+  const staticModuleMetadata = await moduleMetadata
   await clientBundles
   const proxyModule = await proxyBuild
   await partytownLib
@@ -480,8 +495,7 @@ async function runBuild(
   const generateFailures: { route: string; omitErrorLine: boolean }[] = []
   if (isGenerate) console.log('   Collecting page data ...')
 
-  // Route stylesheets build strictly after the document ones; this is the first
-  // point that needs them, so everything above ran alongside the CSS worker.
+  // The first point that needs the stylesheets, so everything above ran alongside them.
   await documentCss
 
   for (const route of routes) {
@@ -523,10 +537,7 @@ async function runBuild(
       continue
     }
 
-    await buildRouteCss(config, route, { verbose })
-    for (const reference of route.clientReferences) {
-      await buildClientReferenceCss(config, reference, { verbose })
-    }
+    await routeStylesheets.get(route)?.()
 
     // Compile mode bundles only — every prerender/export step is generate's.
     if (isCompile) continue
@@ -914,6 +925,7 @@ async function runBuild(
   // carries its entries, so this is where it has to have landed.
   await deferredSteps
   const actions = buildState.actions
+  const publicAssets = publicFiles.filter(relative => immutableAssetPath(relative))
   const manifest: BuildManifest = {
     version: 0,
     root: config.root,
@@ -924,6 +936,7 @@ async function runBuild(
     // The serving process re-publishes these so a render resolves the same
     // content-hashed names the build emitted.
     assetNames: emittedAssetNames(config.outPath),
+    ...(publicAssets.length > 0 ? { publicAssets } : {}),
     staticMetadataFiles,
     ...(Object.keys(staticModuleMetadata).length > 0 ? { staticModuleMetadata } : {}),
     ...(!config.compat?.next
@@ -938,7 +951,7 @@ async function runBuild(
   }
   await writeBuildManifest(config.outPath, manifest)
   log.log(`wrote manifest.json (${routes.length} route${routes.length === 1 ? '' : 's'})`)
-  await log.step('server entry', () => serverEntryDone)
+  await log.step('server entry', () => emitServerEntry(config.outPath))
   for (const hook of getBuildExtensions().completeHooks) {
     await hook({ config, manifest, log })
   }
@@ -949,7 +962,19 @@ async function runBuild(
   // Plain build: the adapter owns the child in the branch above. Compiling the
   // rest of the app's modules is build work, so it counts toward the build's own
   // duration rather than hiding after it.
-  else await log.step('warm module cache', () => warm.finish(log))
+  else {
+    await log.step('warm module cache', () =>
+      warm.finish(log, undefined, {
+        globalCss: globalCssSources(config),
+        clientReferences: [...compiledClientReferenceFiles()],
+      }),
+    )
+  }
+  // The release names every module production imports; a server compile that did not finish
+  // fails the build here rather than a request later.
+  if (!existsSync(buildIndexFile(config.outPath))) {
+    throw new Error('pnext build: the server compile did not complete (see the error above).')
+  }
 
   // Also cover module loads performed by completion hooks or the warm pass.
   throwIfModuleGraphFailed()
@@ -3202,11 +3227,11 @@ function resolvePartytownLibDir(root: string): string | null {
 }
 
 async function copyPublicDir(from: string, to: string) {
-  const files = await listFiles(from)
-  for (const file of files) {
-    const relative = toPosixPath(path.relative(from, file))
+  const files = (await listFiles(from)).map(file => toPosixPath(path.relative(from, file)))
+  for (const relative of files) {
     const target = path.join(to, relative)
     await mkdir(path.dirname(target), { recursive: true })
-    await copyFile(file, target)
+    await copyFile(path.join(from, relative), target)
   }
+  return files
 }

package/src/cli/index.ts

@@ -50,8 +50,8 @@ markBoot('cli:entry')
 namedBunBinary(commandBinaryName(command))
 
 // Before any command lazily imports esbuild, which captures the binary path on
-// module load.
-nameEsbuildProcess()
+// module load. `start` serves a finished build and never loads it.
+if (command !== 'start') nameEsbuildProcess()
 markBoot('cli:naming')
 
 try {
@@ -90,14 +90,10 @@ try {
   } else if (command === 'start') {
     warnUnknownFlags(command, args)
     const root = positionalRoot(args)
-    // The build emits src/cli/start.ts prebundled into one file; parsing that
-    // instead of walking the framework's source graph is most of `start`'s
-    // spawn→first-200. Absent (no build yet, custom outDir) → source path.
-    const { prebuiltServerEntry } = await import('./serve/entry')
-    const prebuilt = prebuiltServerEntry(root)
-    const { start } = prebuilt
-      ? ((await import(prebuilt)) as typeof import('./start'))
-      : await import('./start')
+    // A build of other source than this prebundle's is served from that source.
+    const { start } = (await prebundleServes(root))
+      ? await import('./start')
+      : ((await import(new URL('./start.ts', import.meta.url).href)) as typeof import('./start'))
     await start({
       root,
       port: optionNumber(args, '--port'),
@@ -167,6 +163,23 @@ function formatCliError(error: unknown) {
   }
 }
 
+declare const PNEXT_PREBUNDLE: { version: string; fingerprint: string } | undefined
+
+/** Whether this process's prebundle may serve `root`'s build: one made from its source and version. */
+async function prebundleServes(root = process.cwd()) {
+  if (typeof PNEXT_PREBUNDLE !== 'object') return true
+  const [{ DEFAULT_OUT_DIR }, { locateRelease, readBuildIndex }] = await Promise.all([
+    import('../config'),
+    import('../runtime/production'),
+  ])
+  const outPath = locateRelease(path.resolve(root), DEFAULT_OUT_DIR)
+  return (
+    !outPath ||
+    (readBuildIndex(outPath).framework === PNEXT_PREBUNDLE.fingerprint &&
+      VERSION === PNEXT_PREBUNDLE.version)
+  )
+}
+
 function positionalRoot(args: string[]) {
   return positionals(args)[0]
 }

package/src/cli/serve/entry.ts

@@ -1,13 +1,13 @@
 /**
- * Prebundled production server entry: `pnext build` bundles the framework's server graph into one JS
- * file (entry point IS src/cli/start.ts, so the identical `start()` runs) and `pnext start` parses
- * that instead of walking hundreds of source modules - the dominant share of spawn->first-200.
+ * Server entry for hosts that serve a build through `createRequestHandler`: a thin loader that
+ * resolves `@wular/pnext` from the output's own location (as `.next/server` loads `next`), so the
+ * output carries no framework code and no build-machine paths.
  */
-import { existsSync, readFileSync } from 'node:fs'
+import { readFileSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import { pathToFileURL } from 'node:url'
-import type { Plugin as EsbuildPlugin } from 'esbuild'
 import { frameworkFingerprint } from '../../runtime/fingerprint'
+import { readPrebundleStamp } from '../../runtime/prebundle'
 
 const frameworkRoot = path.resolve(import.meta.dirname, '..', '..', '..')
 
@@ -28,163 +28,25 @@ function frameworkVersion(): string {
  * cache-root record so a restart pays one stat per file rather than re-reading the tree.
  */
 export function serverEntryDir(outPath: string): string {
-  // Cache root spelled inline, not imported: this module is parsed before anything else on the
-  // start path, and pulling in the module cache for one path.join would drag its whole graph along.
   const generation = frameworkFingerprint(path.join(outPath, 'cache', 'server'))
   return path.join(outPath, 'server', `bundle-${frameworkVersion()}-${generation}`)
 }
 
-function serverEntryFile(outPath: string): string {
-  return path.join(serverEntryDir(outPath), 'entry.js')
-}
-
-/**
- * The prebuilt entry for a project root, or undefined when there is none to
- * use (no build, a custom `outDir`, a version or source-generation mismatch, or the opt-out). The
- * caller then falls back to importing src/cli/start.ts directly, so a miss only
- * costs speed. Deliberately cheap: one existsSync and one package.json read,
- * because it runs before anything else on the start path.
- */
-export function prebuiltServerEntry(root = process.cwd()): string | undefined {
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  if (process.env.PNEXT_NO_SERVER_BUNDLE === '1') return undefined
-  const file = serverEntryFile(path.resolve(root, '.pnext'))
-  return existsSync(file) ? pathToFileURL(file).href : undefined
-}
-
-/**
- * Bundle src/cli/start.ts under `<outPath>/server/bundle-<version>-<fingerprint>/`. Bare
- * specifiers stay external (the framework's deps are already plain JS), so only
- * the framework's own source is inlined. Splitting is on so the graph behind a
- * dynamic import (compat, dev, build) stays in its own chunk — folding it into
- * the entry would evaluate eagerly what the source graph never even reads.
- * Returns the emitted entry, or undefined when bundling failed — the build must
- * not fail over a start-time optimization.
- */
-export async function emitServerEntry(outPath: string): Promise<string | undefined> {
-  const { build } = await import('../../utils/esbuild')
-  try {
-    await build({
-      entryPoints: [path.join(import.meta.dirname, '..', 'start.ts')],
-      outdir: serverEntryDir(outPath),
-      entryNames: 'entry',
-      chunkNames: '[name]-[hash]',
-      bundle: true,
-      splitting: true,
-      format: 'esm',
-      platform: 'node',
-      target: 'esnext',
-      sourcemap: false,
-      tsconfig: path.join(frameworkRoot, 'tsconfig.json'),
-      logLevel: 'silent',
-      // esbuild's ESM `require` shim throws for anything it did not bundle; the
-      // framework's lazy `require('esbuild' | 'oxc-*')` facades need a real one,
-      // anchored at the framework so they load ITS copy, not the app's.
-      banner: {
-        js:
-          'import { createRequire as __pnextCreateRequire } from "node:module";\n' +
-          `const require = __pnextCreateRequire(${JSON.stringify(
-            pathToFileURL(path.join(frameworkRoot, 'package.json')).href,
-          )});`,
-      },
-      plugins: [await serverEntryPlugin(outPath)],
-    })
-    return serverEntryFile(outPath)
-  } catch (error) {
-    console.warn(`pnext build: server entry bundling skipped — ${(error as Error).message}`)
-    return undefined
-  }
-}
-
 /**
- * Emit in a short-lived child process: the bundle's source strings and parse
- * allocations land in the child's heap (well under the build's own peak), not
- * on top of it. Falls back to in-process emission if the spawn fails.
+ * Write `<outPath>/server/bundle-<version>-<fingerprint>/entry.js`, re-exporting the published
+ * prebundle's cli/start.js when it was built from this source, else src/cli/start.ts.
  */
-export async function emitServerEntryChild(outPath: string): Promise<void> {
-  try {
-    const child = Bun.spawn([process.execPath, import.meta.filename, outPath], {
-      stdout: 'ignore',
-      stderr: 'inherit',
-    })
-    if ((await child.exited) === 0) return
-  } catch {
-    // fall through to in-process emission
-  }
-  await emitServerEntry(outPath)
-}
-
-async function serverEntryPlugin(outPath: string): Promise<EsbuildPlugin> {
-  const { rewriteFacts } = await import('../../resolve/scan-facts')
-  const { spliceSource } = await import('../../runtime/module-transform')
-  return {
-    name: 'pnext-server-entry',
-    setup(build) {
-      // Bare specifiers (and node builtins) stay out of the bundle. They must
-      // still resolve to the SAME file the framework's own source graph would
-      // reach: keep the specifier bare when the output directory resolves it
-      // identically (portable), otherwise pin the absolute path.
-      build.onResolve({ filter: /^[^./]/ }, args => {
-        if (args.path.startsWith('node:')) return { path: args.path, external: true }
-        const target = resolveFrom(args.path, frameworkRoot)
-        if (!target) return { path: args.path, external: true }
-        const fromOutput = resolveFrom(args.path, serverEntryDir(outPath))
-        return { path: fromOutput === target ? args.path : target, external: true }
-      })
-      // `import.meta` in a bundled module still means the ORIGINAL source file
-      // (the framework locates its own runtime shims that way). oxc's exact
-      // spans keep occurrences in strings and comments untouched.
-      build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async args => {
-        const source = await Bun.file(args.path).text()
-        if (!source.includes('import.meta')) return undefined
-        const facts = rewriteFacts(args.path, source)
-        if (facts.unreliable) return undefined
-        const edits = facts.importMetas.flatMap(meta => {
-          const value = importMetaValue(source.slice(meta.end, meta.end + 16), args.path)
-          return value
-            ? [{ start: meta.start, end: meta.end + value.length, value: value.code }]
-            : []
-        })
-        if (edits.length === 0) return undefined
-        return { contents: spliceSource(source, edits), loader: loaderFor(args.path) }
-      })
-    },
-  }
-}
-
-const importMetaProperties = ['dirname', 'filename', 'resolve', 'url', 'dir'] as const
-
-/** The literal a bundled `import.meta.<prop>` must become, given the tail after `import.meta`. */
-function importMetaValue(tail: string, file: string): { code: string; length: number } | undefined {
-  const property = importMetaProperties.find(name => new RegExp(`^\\.${name}\\b`).test(tail))
-  if (!property) return undefined
-  const length = property.length + 1
-  const dir = path.dirname(file)
-  if (property === 'dirname' || property === 'dir') return { code: JSON.stringify(dir), length }
-  if (property === 'filename') return { code: JSON.stringify(file), length }
-  if (property === 'url') return { code: JSON.stringify(pathToFileURL(file).href), length }
-  return {
-    code: `(specifier => Bun.pathToFileURL(Bun.resolveSync(specifier, ${JSON.stringify(dir)})).href)`,
-    length,
-  }
-}
-
-function loaderFor(file: string): 'ts' | 'tsx' | 'js' | 'jsx' {
-  if (file.endsWith('.tsx')) return 'tsx'
-  if (file.endsWith('.jsx')) return 'jsx'
-  return /\.[cm]?ts$/.test(file) ? 'ts' : 'js'
-}
-
-function resolveFrom(specifier: string, dir: string): string | undefined {
-  try {
-    return Bun.resolveSync(specifier, dir)
-  } catch {
-    return undefined
-  }
-}
-
-// Child-process entry for emitServerEntryChild; last so every binding above is initialized.
-if (import.meta.main && process.argv[2]) {
-  const emitted = await emitServerEntry(process.argv[2])
-  process.exit(emitted ? 0 : 1)
+export async function emitServerEntry(outPath: string): Promise<void> {
+  const start = await Bun.file(path.join(import.meta.dirname, '..', 'start.ts')).text()
+  const names = new Bun.Transpiler({ loader: 'ts' }).scan(start).exports
+  const dir = serverEntryDir(outPath)
+  const target = readPrebundleStamp(frameworkRoot, frameworkFingerprint())
+    ? '../dist/server/cli/start.js'
+    : './cli/start.ts'
+  await mkdir(dir, { recursive: true })
+  await writeFile(
+    path.join(dir, 'entry.js'),
+    `const pnext = await import(new URL('${target}', import.meta.resolve('@wular/pnext')).href)\n` +
+      `export const { ${names.join(', ')} } = pnext\n`,
+  )
 }

package/src/cli/serve/immutable.ts

@@ -0,0 +1,31 @@
+import { getAssetExtensions } from '../../extensions'
+
+export const immutableCacheControl = 'public, max-age=31536000, immutable'
+
+/**
+ * Everything the build emits under `assets/` (served at `/_next/static/*` in
+ * compat) is immutable, which is the promise Next makes for that whole
+ * namespace. It holds because every one of those names carries a content hash:
+ * esbuild's for chunks and fonts, assetContentHash for the route entries and the
+ * stylesheets (see fingerprintClientEntries / fingerprintAsset), and a build id
+ * for `_next/static/<id>/_*Manifest.js`. An UNHASHED name must never reach here —
+ * the same URL would answer different bytes after a deploy, and every browser
+ * that saw the old ones would keep them for a year.
+ *
+ * Route outputs (prerendered html, handler bodies) live outside both prefixes
+ * and stay revalidating; so do the app's own public/ files (manifest.publicAssets).
+ */
+export function immutableAssetPath(relativePath: string) {
+  return immutableAssetPrefixes().some(prefix => relativePath.startsWith(prefix))
+}
+
+/** The public-relative prefixes `immutableAssetPath` covers. */
+export function immutableAssetPrefixes() {
+  return [
+    'assets/',
+    '_next/static/',
+    ...getAssetExtensions()
+      .staticAssetPublicPrefixes()
+      .map(prefix => prefix.replace(/^\/+/, '')),
+  ]
+}