@wular/pnext 0.0.12 → 0.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wular/pnext",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "A fast little framework for server-first React apps, fully compatible with Next.js",
   "type": "module",
   "bin": {

package/src/cli/adapters/vercel-warm.ts

@@ -20,7 +20,7 @@
  * routes' server modules as soon as the route scan hands them over, and blocks on stdin for the
  * go-ahead to finish the rest once the manifest is written.
  */
-import { existsSync } from 'node:fs'
+import { existsSync, readdirSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -33,8 +33,9 @@ import {
   setEmitCompiledSpecifiersManifest,
 } from '../../runtime/modules'
 import { getCompatModeExtensions } from '../../extensions'
+import { getFontExtensions } from '../../render/hooks'
 import { findConventionFiles, findLayouts } from '../../routing/routes'
-import { registerServerRuntime } from '../../runtime/loader'
+import { registerServerRuntime, serverBundleTargetForRuntime } from '../../runtime/loader'
 import { namedBunBinary } from '../boot/named-bin'
 import type { VerboseLogger } from '../../utils/verbose'
 import type { BuildManifest } from '../../types'
@@ -252,8 +253,17 @@ function pageServerFiles(config: ResolvedConfig, routeFiles: Iterable<string>) {
   return files
 }
 
-const compileServer = (config: ResolvedConfig, file: string) =>
-  devServerModuleHref(config, file, 'build').then(href => report(file, fileURLToPath(href)))
+const compileServer = (config: ResolvedConfig, file: string, runtime = '') =>
+  devServerModuleHref(config, file, 'build', {
+    conditionTarget: serverBundleTargetForRuntime(runtime || undefined),
+  }).then(href => report(compileKey(file, runtime), fileURLToPath(href)))
+
+// A finished compile and a finished import are different facts about the same source, and a restart
+// skips by key: reporting a handler's compile under its plain path would mark it imported too, so a
+// crash in ONE handler's import would skip every other handler's import on the next attempt.
+const compileKey = (file: string, runtime: string) => `${runtime}\u0000${file}`
+const splitCompileKey = (key: string) => key.split('\u0000') as [string, string]
+const importKey = (file: string) => `import\u0000${file}`
 
 /**
  * Compile the page routes' server modules from the build's route scan, long before the manifest
@@ -279,19 +289,24 @@ export async function warmRouteModules(
   manifest: BuildManifest,
   skip: ReadonlySet<string> = new Set(),
 ) {
+  // Every compile below is keyed by runtime as well as file. A module reachable from routes with
+  // different `runtime` segments resolves to a different artifact per route, and the renderer asks
+  // for the one its route selects — warming only the default target writes artifacts no request
+  // ever reads, and leaves the real ones to be compiled against a read-only filesystem.
   const clientFiles = new Set<string>()
   const handlers: BuildManifest['routes'] = []
-  const pageRoutes: string[] = []
+  const pageRoutes = new Map<string, string[]>()
 
   for (const route of manifest.routes) {
     if (route.kind === 'handler') {
-      if (!skip.has(route.file)) handlers.push(route)
+      if (!skip.has(importKey(route.file))) handlers.push(route)
       continue
     }
-    pageRoutes.push(route.file)
+    const runtime = route.segmentConfig?.runtime ?? ''
+    pageRoutes.set(runtime, [...(pageRoutes.get(runtime) ?? []), route.file])
     for (const reference of route.clientReferences) {
       if (ssrClientReference(reference) && existsSync(reference.file)) {
-        clientFiles.add(reference.file)
+        clientFiles.add(compileKey(reference.file, runtime))
       }
     }
   }
@@ -300,16 +315,29 @@ export async function warmRouteModules(
   // transforms in memory); the compiled build cache is only used with compat.
   if (getCompatModeExtensions().reactEnabled(config)) {
     await Promise.all([
-      ...[...pageServerFiles(config, pageRoutes)]
-        .filter(file => !skip.has(file))
-        .map(file => compileServer(config, file)),
+      ...[...pageRoutes].flatMap(([runtime, routeFiles]) =>
+        [...pageServerFiles(config, routeFiles)]
+          .filter(file => !skip.has(compileKey(file, runtime)))
+          .map(file => compileServer(config, file, runtime)),
+      ),
+      // Handlers are compiled here, not left to the import below: the import runs the source through
+      // the registered runtime, while a request resolves the route as a compiled module under the
+      // condition target its `runtime` segment selects. Only this pass writes THAT artifact, and
+      // without it the first request compiles the handler against a read-only filesystem.
+      ...handlers.map(route =>
+        compileServer(config, route.file, route.segmentConfig?.runtime ?? ''),
+      ),
       ...[...clientFiles]
-        .filter(file => !skip.has(file))
-        .map(file =>
-          devClientModuleHref(config, file, 'build').then(href =>
-            report(file, fileURLToPath(href)),
-          ),
-        ),
+        .filter(key => !skip.has(key))
+        .map(key => {
+          const [runtime, file] = splitCompileKey(key)
+          return devClientModuleHref(
+            config,
+            file,
+            'build',
+            serverBundleTargetForRuntime(runtime || undefined),
+          ).then(href => report(key, fileURLToPath(href)))
+        }),
     ])
   }
   console.log(COMPILED_MARKER)
@@ -325,15 +353,68 @@ export async function warmRouteModules(
     // time, so a handler that takes the process down is unambiguous and a
     // restart must not run it again (Bun caches a failed import for the
     // process' lifetime anyway, so a retry could not succeed either).
-    report(route.file)
+    report(importKey(route.file))
     try {
       await import(pathToFileHref(route.file))
     } catch (error) {
       console.warn(`vercel adapter: importing ${route.file} failed during warmup:`, error)
     }
   }
+
+  await materializeFonts(config, [...pageRoutes.values()].flat())
+}
+
+/**
+ * `next/font` emits its assets, and records the resolution a render reads, the first time something
+ * asks for a font - which on a deployed server is a request, against a read-only filesystem. Fonts are
+ * declared at module scope, so evaluating the modules that declare them is enough to register them;
+ * the render layer's own prewarm hook then resolves every one while writing still works, leaving the
+ * files under the out dir and the resolution in the build's font index. Only layouts are evaluated,
+ * not the whole page graph: a font belongs to the document shell, and the rest of the graph running
+ * at build time is exactly what this pass avoids.
+ */
+async function materializeFonts(config: ResolvedConfig, pageRoutes: string[]) {
+  // Nothing to register, and evaluating an app's layouts for no reason is a compile it never asked
+  // for: the font runtime is only in the compiled cache when something in the graph imports
+  // `next/font`, which the compile pass above has just settled.
+  if (!compiledFontRuntime(config)) return
+  const layouts = new Set<string>()
+  for (const routeFile of pageRoutes) {
+    for (const layout of findLayouts(config.appPath, routeFile)) {
+      if (existsSync(layout)) layouts.add(layout)
+    }
+  }
+  for (const file of layouts) {
+    try {
+      await import(await devServerModuleHref(config, file, 'build'))
+    } catch (error) {
+      console.warn(`vercel adapter: evaluating ${file} for fonts failed during warmup:`, error)
+    }
+  }
+  await getFontExtensions().prewarmFontAssets(config, { dev: false })
 }
 
+/** Whether the compile pass wrote an artifact for the next/font runtime. */
+function compiledFontRuntime(config: ResolvedConfig): boolean {
+  const stack = [path.join(config.outPath, 'cache', 'server')]
+  while (stack.length > 0) {
+    const current = stack.pop()!
+    let entries
+    try {
+      entries = readdirSync(current, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) stack.push(path.join(current, entry.name))
+      else if (entry.name.startsWith('runtime.') && current.endsWith(FONT_RUNTIME_DIR)) return true
+    }
+  }
+  return false
+}
+
+const FONT_RUNTIME_DIR = path.join('compat', 'next', 'font')
+
 /**
  * Read the parent's line-delimited requests until the `skip` message, running
  * each prewarm batch as it arrives. Returns the final request.
@@ -362,7 +443,9 @@ async function readWarmRequests(config: ResolvedConfig): Promise<Partial<WarmReq
 
 if (import.meta.main) {
   const root = process.argv[2]
-  const config = await loadConfig(root)
+  // serve: the parent already wrote the config bundle this child would otherwise re-emit over the
+  // top of - same content-addressed path, opened with O_TRUNC, while the parent may be importing it.
+  const config = await loadConfig(root, { serve: true })
   await bootstrapCompat(config)
   // This process only ever runs for a vercel-adapter build; record each
   // artifact's specifiers so the parent's trace step can read them back.

package/src/cli/adapters/vercel.ts

@@ -3,7 +3,7 @@ import { existsSync, readFileSync, readdirSync, realpathSync, rmSync, statSync }
 import { builtinModules } from 'node:module'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { pathToFileHref } from '../../config'
+import { DEFAULT_OUT_DIR, devOutSegment, pathToFileHref } from '../../config'
 import type { ResolvedConfig } from '../../config'
 import { globalCssSources } from '../../css/build'
 import { getImportAliasExtensions } from '../../extensions'
@@ -19,7 +19,13 @@ import type { BuildManifest, StaticFileMetadata } from '../../types'
 
 // Vercel unpacks a function's `.func` directory here at runtime. Baked
 // absolute paths in the build output are rewritten to this root.
-const RUNTIME_ROOT = '/var/task'
+//
+// PNEXT_VERCEL_EMULATE points both this and FUNCTION_PLATFORM at a local path and the host's own
+// platform, so the built function can be run on this machine exactly as the deployment does - the
+// only way to reproduce a request-time failure that needs the function's read-only root.
+// eslint-disable-next-line turbo/no-undeclared-env-vars
+const emulateRoot = process.env.PNEXT_VERCEL_EMULATE
+const RUNTIME_ROOT = emulateRoot ? path.resolve(emulateRoot) : '/var/task'
 
 // The single catch-all server function: the same `pnext start` pipeline,
 // running on Vercel's Bun runtime (`"bunVersion": "1.x"` in vercel.json).
@@ -29,12 +35,20 @@ const SERVER_FUNCTION = '_pnext'
 // goes into .vc-config.json and the same target selects the native packages
 // shipped inside it, so the two can never drift. Vercel's default instruction
 // set is x86_64 and its function runtime is glibc-based.
-const FUNCTION_PLATFORM = {
-  architecture: 'x86_64',
-  os: 'linux',
-  cpu: 'x64',
-  libc: 'glibc',
-} as const
+const FUNCTION_PLATFORM = emulateRoot
+  ? {
+      architecture: process.arch === 'arm64' ? 'arm64' : 'x86_64',
+      os: process.platform === 'darwin' ? 'darwin' : 'linux',
+      cpu: process.arch,
+      // No libc constraint off linux: darwin packages declare none.
+      libc: process.platform === 'darwin' ? '' : 'glibc',
+    }
+  : ({
+      architecture: 'x86_64',
+      os: 'linux',
+      cpu: 'x64',
+      libc: 'glibc',
+    } as const)
 
 // Directories that only ever hold build-tool output, pruned at *any* depth. Depth matters: pruning
 // only a package's top level ships every nested one. node_modules and .git are here for the same
@@ -71,6 +85,12 @@ interface PackRules {
   droppedSuffixes: string[]
   /** Absolute sources exempt from the prune list — the app's own build output. */
   keepPaths: Set<string>
+  /** Absolute sources dropped even though they sit inside a kept path. */
+  dropPaths: Set<string>
+  /** Same set as `dropPaths`, by basename — the clone pass walks copies, not sources. */
+  dropNames: Set<string>
+  /** Resolved out root, so a walk can tell when it is standing exactly on it. */
+  outRootPath: string
 }
 
 // Test seam: the packing suite builds one app both ways and diffs the trees,
@@ -86,6 +106,9 @@ export function setPackPruningEnabled(enabled: boolean) {
   }
 }
 
+// Build-time scratch directories at the top level of the out root.
+const outRootScratch = [devOutSegment, 'typecheck', 'types']
+
 function packRules(config: ResolvedConfig): PackRules {
   if (!packPruningEnabled) {
     return {
@@ -94,6 +117,9 @@ function packRules(config: ResolvedConfig): PackRules {
       prunedDirs: new Set(['node_modules', '.git']),
       droppedSuffixes: [],
       keepPaths: new Set([path.resolve(config.outPath)]),
+      dropPaths: new Set(),
+      dropNames: new Set(),
+      outRootPath: path.resolve(config.outRootPath),
     }
   }
   const keep = new Set(config.adapter?.keep ?? [])
@@ -109,15 +135,44 @@ function packRules(config: ResolvedConfig): PackRules {
       suffix => !keep.has(suffix),
     ),
     // The app's outDir shares its name with the prune list; it holds the
-    // compiled module cache the function serves from and must survive.
-    keepPaths: new Set([path.resolve(config.outPath)]),
+    // compiled module cache the function serves from and must survive. The
+    // default out root goes with it: a `distDir` app moved its output away, but
+    // the next.config bundle the function imports at boot still lives there.
+    keepPaths: new Set([path.resolve(config.outPath), path.resolve(config.root, DEFAULT_OUT_DIR)]),
+    // Kept because they sit inside the out dir, shipped because nothing prunes
+    // within a kept path — but a dev server's scratch tree (tens of MB on a
+    // machine that ran `pnext dev`), the typecheck scratch and the generated
+    // types are all build-time only, and the bun1.x function has a 150 MiB cap.
+    // Absolute, not by name: `types` and `dist` are ordinary directory names in
+    // a dependency, and only these exact ones are build scratch.
+    dropPaths: new Set(outRootScratch.map(name => path.resolve(config.outRootPath, name))),
+    dropNames: new Set(outRootScratch),
+    outRootPath: path.resolve(config.outRootPath),
   }
 }
 
-function shipsDir(pack: PackRules, name: string, source: string) {
-  return !pack.prunedDirs.has(name) || pack.keepPaths.has(path.resolve(source))
+// `inOutRoot` marks a walk already inside the app's own build output. Nothing in there is a package
+// store or a build-tool scratch dir the prune list is aimed at: the compiled module cache mirrors
+// SOURCE paths, so every module compiled out of a dependency sits under a literal `node_modules`
+// segment, and pruning by name deletes artifacts the function resolves by exact path at request time.
+function shipsDir(
+  pack: PackRules,
+  name: string,
+  source: string,
+  inOutRoot = false,
+  symlink = false,
+) {
+  const absolute = path.resolve(source)
+  if (pack.dropPaths.has(absolute)) return false
+  // A *link* named node_modules inside the out root points at the real store, and following it
+  // copies the whole thing; a real directory there is the compiled module cache, whose artifacts
+  // mirror source paths — so one of them is literally `<out>/cache/.../node_modules/<pkg>/...`.
+  if (inOutRoot) return !(symlink && pack.prunedDirs.has(name))
+  return !pack.prunedDirs.has(name) || pack.keepPaths.has(absolute)
 }
 
+const isOutRoot = (pack: PackRules, dir: string) => path.resolve(dir) === pack.outRootPath
+
 function shipsFile(pack: PackRules, name: string) {
   return !pack.droppedSuffixes.some(suffix => name.endsWith(suffix))
 }
@@ -137,6 +192,12 @@ export async function writeVercelOutput(
   options: { verbose?: boolean; warm?: WarmChild } = {},
 ) {
   const log = createVerboseLogger(options.verbose ?? false, 'vercel')
+  if (emulateRoot) {
+    console.warn(
+      `pnext: PNEXT_VERCEL_EMULATE is set — this output is built for ${FUNCTION_PLATFORM.os}-` +
+        `${FUNCTION_PLATFORM.cpu} and rooted at ${RUNTIME_ROOT}. It runs locally; do not deploy it.`,
+    )
+  }
   const outputPath = path.join(config.root, '.vercel', 'output')
   const staticFiles = manifest.staticFiles ?? {}
   // Warming runs in its own process (see ./vercel-warm) and normally started
@@ -333,14 +394,26 @@ async function writeServerFunction(
   )
 
   // Baked absolute paths (compiled cache imports, manifest file paths) point
-  // at the build machine's workspace; rewrite them to the runtime root.
+  // at the build machine's workspace; rewrite them to the runtime root. A
+  // `distDir` app moved its output away from the default out root, but the
+  // next.config bundle stays there and bakes paths of its own, so both trees go
+  // through the pass.
+  const bakedRoots = new Set(
+    [config.outPath, path.resolve(config.root, DEFAULT_OUT_DIR)].map(dir =>
+      path.join(functionPath, appRel, path.relative(config.root, dir)),
+    ),
+  )
   await log.step('rewrite baked paths', () =>
-    rewriteBakedPaths(path.join(functionPath, appRel, path.relative(config.root, config.outPath)), [
-      ...(pnextInWorkspace
-        ? []
-        : [[pnextRoot, toPosixPath(path.join(RUNTIME_ROOT, pnextTargetRel))] as const]),
-      [workspaceRoot, RUNTIME_ROOT] as const,
-    ]),
+    Promise.all(
+      [...bakedRoots].map(dir =>
+        rewriteBakedPaths(dir, [
+          ...(pnextInWorkspace
+            ? []
+            : [[pnextRoot, toPosixPath(path.join(RUNTIME_ROOT, pnextTargetRel))] as const]),
+          [workspaceRoot, RUNTIME_ROOT] as const,
+        ]),
+      ),
+    ),
   )
 
   // Bun's runtime onResolve plugins never see bare specifiers, so the compat aliases the dev pipeline
@@ -455,13 +528,16 @@ async function copyTree(
   pack: PackRules,
   excludeNames: string[] = [],
   visited = new Set<string>([realDir(from) ?? path.resolve(from)]),
+  inOutRoot = pack.keepPaths.has(path.resolve(from)),
 ) {
   const exclude = new Set(excludeNames)
   const clone = directoryCloneEnabled ? await directoryCloner() : null
   // Nothing to skip at this level: the whole tree clones in one syscall.
   if (exclude.size === 0 && !existsSync(to)) {
     await mkdir(path.dirname(to), { recursive: true })
-    if (clone?.(from, to)) return normalizeClone(to, pack, visited)
+    if (clone?.(from, to)) {
+      return normalizeClone(to, pack, visited, inOutRoot, isOutRoot(pack, from))
+    }
   }
   // The build output is still live while the walk runs — typegen rewrites
   // `.pnext/types` under it — so a directory can vanish between the parent's
@@ -475,23 +551,29 @@ async function copyTree(
       const target = path.join(to, entry.name)
       // Matched by name before type: a symlinked `node_modules` must be pruned
       // as the directory it points at, not followed.
-      if (exclude.has(entry.name) || !shipsDir(pack, entry.name, source)) return
+      if (
+        exclude.has(entry.name) ||
+        !shipsDir(pack, entry.name, source, inOutRoot, entry.isSymbolicLink())
+      ) {
+        return
+      }
+      const childInOutRoot = inOutRoot || pack.keepPaths.has(path.resolve(source))
       if (entry.isSymbolicLink()) {
         const link = resolveLinkTarget(source)
         if (!link) return
         if (link.isDirectory) {
           if (visited.has(link.path)) return
           visited.add(link.path)
-          return copyTree(link.path, target, pack, [], visited)
+          return copyTree(link.path, target, pack, [], visited, childInOutRoot)
         }
         return shipsFile(pack, entry.name) ? linkOrCopyFile(link.path, target) : undefined
       }
       // One syscall for the whole subtree beats one per file — the excluded
       // names are stripped from the copy afterwards.
       if (entry.isDirectory() && clone?.(source, target)) {
-        return normalizeClone(target, pack, visited)
+        return normalizeClone(target, pack, visited, childInOutRoot, isOutRoot(pack, source))
       }
-      if (entry.isDirectory()) return copyTree(source, target, pack, [], visited)
+      if (entry.isDirectory()) return copyTree(source, target, pack, [], visited, childInOutRoot)
       if (entry.isFile() && shipsFile(pack, entry.name)) return linkOrCopyFile(source, target)
     }),
   )
@@ -550,18 +632,30 @@ async function directoryCloner() {
  * both paths emit the same tree. Reading directory entries costs nothing next
  * to the per-file copies this replaces.
  */
-async function normalizeClone(dir: string, pack: PackRules, visited: Set<string>) {
-  const stack = [dir]
+async function normalizeClone(
+  dir: string,
+  pack: PackRules,
+  visited: Set<string>,
+  inOutRoot = false,
+  atOutRoot = false,
+) {
+  // `atOutRoot` only at the level the walk handed over, mirroring the absolute
+  // paths shipsDir drops: the scratch dirs exist at the out root's top level and
+  // their names (`types`, `dev`) are ordinary ones anywhere else.
+  const stack: [string, boolean, boolean][] = [[dir, inOutRoot, atOutRoot]]
   const pending: Promise<unknown>[] = []
   while (stack.length > 0) {
-    const current = stack.pop()!
+    const [current, inside, atRoot] = stack.pop()!
     for (const entry of readdirSync(current, { withFileTypes: true })) {
       const full = path.join(current, entry.name)
-      // Matched by name before type, as the walk does: the pages-compat shim
-      // links `node_modules` at the app root, and following it would pull the
-      // whole store into the function. The clone is already inside the
+      // Matched by name before type, as the walk does: a `node_modules` symlink
+      // in the app root points at the real store, and following it would pull
+      // the whole thing into the function. The clone is already inside the
       // function, so the walk's keep-path exemption cannot apply here.
-      if (pack.prunedDirs.has(entry.name)) {
+      if (
+        (atRoot && pack.dropNames.has(entry.name)) ||
+        ((!inside || entry.isSymbolicLink()) && pack.prunedDirs.has(entry.name))
+      ) {
         rmSync(full, { recursive: true, force: true })
       } else if (entry.isSymbolicLink()) {
         const link = resolveLinkTarget(full)
@@ -570,12 +664,12 @@ async function normalizeClone(dir: string, pack: PackRules, visited: Set<string>
         if (link.isDirectory) {
           if (visited.has(link.path)) continue
           visited.add(link.path)
-          pending.push(copyTree(link.path, full, pack, [], visited))
+          pending.push(copyTree(link.path, full, pack, [], visited, inside))
         } else if (shipsFile(pack, entry.name)) {
           pending.push(linkOrCopyFile(link.path, full))
         }
       } else if (entry.isDirectory()) {
-        stack.push(full)
+        stack.push([full, inside, false])
       } else if (!shipsFile(pack, entry.name)) {
         rmSync(full, { force: true })
       }

package/src/cli/serve/pipeline.ts

@@ -88,7 +88,7 @@ export async function createRequestHandler(
   // `start` already resolved (and bootstrapped) the config for its output-mode
   // guard; reusing it skips a second loadConfig — env load, pnext.config +
   // next.config imports, app-path resolution — before the ready banner.
-  const config = options.config ?? (await loadConfig(options.root))
+  const config = options.config ?? (await loadConfig(options.root, { serve: true }))
   // Compat plugin loader: the single gated seam that populates the core
   // extension registries when compat is enabled (no-op for pure-core apps).
   // A prod server answers the very next request, so it takes both tiers here.
@@ -578,8 +578,13 @@ export async function createRequestHandler(
         method === 'GET' &&
         handlerResponse.status === 200
       ) {
-        await writeFile(built.file, new Uint8Array(await handlerResponse.clone().arrayBuffer()))
-        handlerResponse.headers.set('x-nextjs-cache', 'MISS')
+        try {
+          await writeFile(built.file, new Uint8Array(await handlerResponse.clone().arrayBuffer()))
+          handlerResponse.headers.set('x-nextjs-cache', 'MISS')
+        } catch {
+          // Best-effort like the page path below: a read-only serving filesystem
+          // (a serverless host) costs the cache write, never the response.
+        }
       }
       if (
         !built &&
@@ -593,7 +598,9 @@ export async function createRequestHandler(
         handlerResponse.status < 500
       ) {
         const file = lazyStaticHandlerPath(config.outPath, url.pathname)
-        if (file) {
+        // Same best-effort contract as the page path below.
+        try {
+          if (!file) throw new Error('unsafe path')
           await mkdir(path.dirname(file), { recursive: true })
           await writeFile(file, new Uint8Array(await handlerResponse.clone().arrayBuffer()))
           const relative = path
@@ -617,6 +624,8 @@ export async function createRequestHandler(
           }
           await persistManifest()
           handlerResponse.headers.set('x-nextjs-cache', 'MISS')
+        } catch {
+          // Lazy caching is best-effort; the response is still served.
         }
       }
       return applyProxyResponse(handlerResponse, proxyResponse)
@@ -831,8 +840,12 @@ export async function createRequestHandler(
       pageResponse.status === 200 &&
       (pageResponse.headers.get('content-type') ?? '').includes('text/html')
     ) {
-      await writeFile(stalePage, await pageResponse.clone().text())
-      pageResponse.headers.set('x-nextjs-cache', 'MISS')
+      try {
+        await writeFile(stalePage, await pageResponse.clone().text())
+        pageResponse.headers.set('x-nextjs-cache', 'MISS')
+      } catch {
+        // Best-effort write-back; the stale copy stays and the fresh render still serves.
+      }
     }
     // On-demand revalidation (valid x-prerender-revalidate): the fresh render
     // replaces any prebuilt copy and is reported as REVALIDATED (Next's
@@ -844,7 +857,12 @@ export async function createRequestHandler(
         pageResponse.status === 200 &&
         (pageResponse.headers.get('content-type') ?? '').includes('text/html')
       ) {
-        await writeFile(built.file, await pageResponse.clone().text())
+        try {
+          await writeFile(built.file, await pageResponse.clone().text())
+        } catch {
+          // Best-effort: an on-demand revalidation still returns the fresh
+          // render when the prebuilt copy cannot be replaced.
+        }
       }
       pageResponse.headers.set('x-nextjs-cache', 'REVALIDATED')
     }

package/src/cli/start.ts

@@ -113,7 +113,7 @@ function installProcessErrorHandlers(): void {
 // `__NEXT_PRIVATE_STANDALONE_CONFIG` set. pnext mirrors that: load the compat config, read the output
 // mode from the build-compat registry, and reproduce Next's exact messages.
 async function guardUnservableOutputMode(root?: string): Promise<ResolvedConfig> {
-  const config = await loadConfig(root)
+  const config = await loadConfig(root, { serve: true })
   await bootstrapCompat(config)
   const mode = getBuildExtensions().compat.nextOutputMode()
   if (mode === 'export') {

package/src/compat/next/config-loader.ts

@@ -13,7 +13,7 @@
 // export / top-level await / dynamic import() and CJS+ESM authoring styles.
 // ---------------------------------------------------------------------------
 
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -130,11 +130,17 @@ function findTsconfig(root: string): string | undefined {
  * Bundle the config with esbuild (external node_modules) and import the result.
  * The emitted file is written next to the config so Node resolves the app's
  * node_modules and relative assets from the original location.
+ *
+ * The bundle is also a BUILD artifact: the build leaves it on disk, deployment adapters ship it with
+ * the app's out dir, and a serve imports that file rather than re-running the pass. Request time is
+ * read-only on a serverless host (Vercel's `/var/task`), where the pass cannot write at all - and
+ * where it could, it would still put an esbuild spawn on every cold start. A serve whose build left
+ * no bundle (the config changed since, matching `next start` re-reading next.config) still bundles.
  */
 async function importConfigModule(
   configPath: string,
   root: string,
-  dev: boolean,
+  options: { dev: boolean; serve: boolean },
 ): Promise<NextConfigExport> {
   const cjs = cjsConfigFormat(configPath, root)
   if (process.env.PNEXT_CONFIG_FAST !== '0' && selfContainedConfig(configPath)) {
@@ -147,66 +153,112 @@ async function importConfigModule(
   }
   // Dev keeps its scratch bundle in its own subtree; a concurrent build wipes
   // only the build-owned `config/`.
-  const outDir = path.join(root, '.pnext', ...(dev ? ['dev'] : []), 'config')
-  mkdirSync(outDir, { recursive: true })
+  const outDir = path.join(root, '.pnext', ...(options.dev ? ['dev'] : []), 'config')
   // Content-addressed, not timestamped: a per-boot name leaked one bundle per
   // dev start and put a path that changes every boot into the module graph,
-  // which renamed every artifact that could reach it.
+  // which renamed every artifact that could reach it. It also makes the name a
+  // pure function of the config source, so a serve recomputes what its build wrote.
   const outfile = path.join(
     outDir,
     `next.config.${configSourceKey(configPath)}.${cjs ? 'cjs' : 'mjs'}`,
   )
+  if (options.serve && existsSync(outfile)) return importConfigBundle(outfile, cjs)
   try {
-    await build({
-      entryPoints: [configPath],
-      outfile,
-      bundle: true,
-      platform: 'node',
-      format: cjs ? 'cjs' : 'esm',
-      target: 'esnext',
-      // Keep bare package imports external so Node resolves them from the app's
-      // node_modules at import time (preserves CJS/ESM interop and identity).
-      packages: 'external',
-      // Fixture/app configs may require() or require.resolve() Next internals
-      // (next/dist/*) that don't exist without a real `next` install. Stub them
-      // so the config still loads; features pointing at the stubs degrade
-      // gracefully instead of crashing config loading.
-      plugins: [nextDistStubPlugin(outDir), nextMdxConfigStubPlugin()],
-      banner: cjs
-        ? {
-            js:
-              'var __pnextNodeRequire = module.require.bind(module);\n' +
-              `var require = __pnextNodeRequire("node:module").createRequire(${JSON.stringify(pathToFileURL(configPath).href)});`,
-          }
-        : {
-            js:
-              'import { createRequire as __pnextCreateRequire } from "node:module";\n' +
-              `const require = __pnextCreateRequire(${JSON.stringify(pathToFileURL(configPath).href)});`,
-          },
-      // Relative/absolute imports (incl. .ts/.cts/.mts/.cjs/.mjs and tsconfig
-      // `paths` aliases) are bundled in. esbuild reads `paths`/`extends` and
-      // `baseUrl` from the app tsconfig.
-      tsconfig: findTsconfig(root),
-      // __dirname / __filename in CJS-authored .ts configs (node-api-cjs) and
-      // import.meta.url in ESM configs (node-api-esm) must point at the config's
-      // original location, not the emitted file under .pnext/config.
-      define: {
-        __dirname: JSON.stringify(path.dirname(configPath)),
-        __filename: JSON.stringify(configPath),
-        'import.meta.url': JSON.stringify(pathToFileURL(configPath).href),
-      },
-      logLevel: 'silent',
-      sourcemap: false,
-      metafile: false,
-    })
-    if (cjs) {
-      const require = createRequire(pathToFileURL(outfile))
-      return require(outfile) as NextConfigExport
+    mkdirSync(outDir, { recursive: true })
+    await bundleConfig({ configPath, root, outDir, outfile, cjs })
+  } catch (error) {
+    // The only way here on a serve is a build that shipped no bundle for this config, and the most
+    // likely reason the rebuild then failed is the read-only request-time filesystem it was meant to
+    // avoid. Name the artifact rather than surfacing an esbuild write error from a boot path.
+    if (!options.serve) throw error
+    throw new Error(
+      `pnext: ${path.relative(root, outfile)} is missing and could not be rebuilt here — run ` +
+        '`pnext build` and deploy its output dir, which carries the config bundle. Cause: ' +
+        (error instanceof Error ? error.message : String(error)),
+      { cause: error },
+    )
+  }
+  pruneStaleConfigBundles(outDir, outfile)
+  return importConfigBundle(outfile, cjs)
+}
+
+function bundleConfig({
+  configPath,
+  root,
+  outDir,
+  outfile,
+  cjs,
+}: {
+  configPath: string
+  root: string
+  outDir: string
+  outfile: string
+  cjs: boolean
+}) {
+  return build({
+    entryPoints: [configPath],
+    outfile,
+    bundle: true,
+    platform: 'node',
+    format: cjs ? 'cjs' : 'esm',
+    target: 'esnext',
+    // Keep bare package imports external so Node resolves them from the app's
+    // node_modules at import time (preserves CJS/ESM interop and identity).
+    packages: 'external',
+    // Fixture/app configs may require() or require.resolve() Next internals
+    // (next/dist/*) that don't exist without a real `next` install. Stub them
+    // so the config still loads; features pointing at the stubs degrade
+    // gracefully instead of crashing config loading.
+    plugins: [nextDistStubPlugin(outDir), nextMdxConfigStubPlugin()],
+    banner: cjs
+      ? {
+          js:
+            'var __pnextNodeRequire = module.require.bind(module);\n' +
+            `var require = __pnextNodeRequire("node:module").createRequire(${JSON.stringify(pathToFileURL(configPath).href)});`,
+        }
+      : {
+          js:
+            'import { createRequire as __pnextCreateRequire } from "node:module";\n' +
+            `const require = __pnextCreateRequire(${JSON.stringify(pathToFileURL(configPath).href)});`,
+        },
+    // Relative/absolute imports (incl. .ts/.cts/.mts/.cjs/.mjs and tsconfig
+    // `paths` aliases) are bundled in. esbuild reads `paths`/`extends` and
+    // `baseUrl` from the app tsconfig.
+    tsconfig: findTsconfig(root),
+    // __dirname / __filename in CJS-authored .ts configs (node-api-cjs) and
+    // import.meta.url in ESM configs (node-api-esm) must point at the config's
+    // original location, not the emitted file under .pnext/config.
+    define: {
+      __dirname: JSON.stringify(path.dirname(configPath)),
+      __filename: JSON.stringify(configPath),
+      'import.meta.url': JSON.stringify(pathToFileURL(configPath).href),
+    },
+    logLevel: 'silent',
+    sourcemap: false,
+    metafile: false,
+  })
+}
+
+async function importConfigBundle(outfile: string, cjs: boolean): Promise<NextConfigExport> {
+  if (cjs) return createRequire(pathToFileURL(outfile))(outfile) as NextConfigExport
+  const module = (await import(pathToFileURL(outfile).href)) as { default?: NextConfigExport }
+  return module.default ?? {}
+}
+
+/**
+ * Drop bundles left by an earlier config source. The emitted file used to be deleted right after it
+ * was imported, which is what made a serve re-bundle; keeping only the current key holds the line
+ * that motivated the delete - one bundle per app, not one per edit.
+ */
+function pruneStaleConfigBundles(outDir: string, outfile: string): void {
+  try {
+    for (const entry of readdirSync(outDir)) {
+      if (!/^next\.config\..+\.[cm]js$/.test(entry)) continue
+      if (path.join(outDir, entry) === outfile) continue
+      rmSync(path.join(outDir, entry), { force: true })
     }
-    const module = (await import(pathToFileURL(outfile).href)) as { default?: NextConfigExport }
-    return module.default ?? {}
-  } finally {
-    rmSync(outfile, { force: true })
+  } catch {
+    // Housekeeping only: a missing or unreadable out dir costs nothing here.
   }
 }
 
@@ -589,7 +641,7 @@ function validateDevIndicatorPosition(config: NextConfigObject): void {
  */
 export async function loadNextConfig(
   root: string,
-  options: { dev?: boolean } = {},
+  options: { dev?: boolean; serve?: boolean } = {},
 ): Promise<LoadNextConfigResult> {
   const configPath = findConfigPath(root)
   if (!configPath) {
@@ -599,7 +651,10 @@ export async function loadNextConfig(
   }
   let exported: NextConfigExport
   try {
-    exported = await importConfigModule(configPath, root, Boolean(options.dev))
+    exported = await importConfigModule(configPath, root, {
+      dev: Boolean(options.dev),
+      serve: Boolean(options.serve),
+    })
   } catch (error) {
     // A next.config that pulls in an optional wrapper dependency not installed
     // in this app (e.g. @next/mdx when deps are declared but not installed)

package/src/compat/next/font/cache.ts

@@ -7,12 +7,11 @@
 //   - every local source file must still match the stat it was read at, so a font swapped while the
 //     server was not running re-resolves and re-emits.
 // Nothing here is used by `pnext build`, which owns the directory it just wiped.
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { mkdir, stat } from 'node:fs/promises'
 import { createHash } from 'node:crypto'
 import path from 'node:path'
 import type { ResolvedConfig } from '../../../config'
-import { restartCacheEnabled } from '../../../dev/restart/enabled'
 import { writeFileAtomic } from '../../../utils/fs'
 import type { MetadataLink } from '../../../types'
 
@@ -61,6 +60,10 @@ function fontIndex(config: ResolvedConfig): FontIndex {
     if (!created.dirty) return
     created.dirty = false
     try {
+      // The debounced write mkdirs; this path can be the FIRST write of the run
+      // (a build's warm child resolves fonts and exits before the timer fires),
+      // and a missing directory would silently cost the deployment its index.
+      mkdirSync(path.dirname(created.file), { recursive: true })
       writeFileSync(created.file, serializeIndex(created.fonts))
     } catch {
       // Best effort: a missing index only costs the next boot a re-resolve.
@@ -74,7 +77,6 @@ export async function persistedFont(
   config: ResolvedConfig,
   key: string,
 ): Promise<PersistableFont | undefined> {
-  if (!restartCacheEnabled()) return undefined
   const entry = fontIndex(config).fonts.get(key)
   if (!entry) return undefined
   if (!entry.files.every(file => existsSync(file))) return undefined

package/src/compat/next/font/runtime.ts

@@ -10,6 +10,7 @@ import { onExtensionHostReset, registerResponseFinalizers } from '../../../exten
 import { getWorkUnit } from '../../../request/context'
 import type { MetadataLink } from '../../../types'
 import { persistFont, persistedFont } from './cache'
+import { restartCacheEnabled } from '../../../dev/restart/enabled'
 import { escapeRegex } from '../../../utils/code'
 import {
   familyStack,
@@ -113,8 +114,16 @@ let googleMetadataCache: Record<string, GoogleFontMetadata> | undefined
  * Every font definition constructed so far, whether or not a render has read its `.className` yet.
  * Definitions are created when the app's font module evaluates - well before the render that registers
  * them - which is what makes the resolve prewarmable.
+ *
+ * Process-global rather than module-local: a compiled artifact imports this module through the build
+ * cache, so the app's font declarations land in a DIFFERENT instance than the one the orchestrator
+ * bootstrapped, and a prewarm reading a module-local map would find it empty.
  */
-const declaredFonts = new Map<string, FontDefinition>()
+const DECLARED_FONTS = Symbol.for('pnext.compat.font.declared')
+const declaredFonts = ((globalThis as Record<symbol, unknown>)[DECLARED_FONTS] ??= new Map<
+  string,
+  FontDefinition
+>()) as Map<string, FontDefinition>
 
 /**
  * Resolve the declared fonts ahead of the render that will ask for them. Fire-and-forget: this only
@@ -360,25 +369,31 @@ async function resolveFont(definition: FontDefinition, context: FontResolveConte
   // A `pnext build` wiping the output directory under a running server must
   // not leave cached font URLs pointing at deleted files; re-emit them.
   // Font bytes stay cached in memory, so this never refetches the network.
-  if (font.files.every(file => existsSync(file))) return font
+  // An empty entry is a font served from its origin because this filesystem
+  // rejects the write; there is nothing on disk to go stale.
+  if (font.files.every(file => !file || existsSync(file))) return font
   const fresh = resolveAndPersist(definition, context, key)
   resolvedFontCache.set(key, fresh)
   return fresh
 }
 
 /**
- * Dev reuses the persisted resolution when it still describes disk: a restart otherwise re-fetches every
- * Google stylesheet and font file to re-derive URLs whose bytes are already emitted. A build always
- * resolves for real - it owns the output directory it just emptied.
+ * Reuse the persisted resolution when it still describes disk. In dev that saves a restart re-fetching
+ * every Google stylesheet and font file to re-derive URLs whose bytes are already emitted. In a
+ * production serve it is what makes fonts work at all: the build resolved and emitted them, and request
+ * time has neither a writable output directory nor any need to reach Google again. A build re-resolves
+ * for real without a special case - it empties the output directory first, so the recorded files are
+ * gone and the entry is rejected.
  */
 async function resolveThroughCache(
   definition: FontDefinition,
   context: FontResolveContext,
   key: string,
 ): Promise<ResolvedFont> {
-  if (!context.dev) return definition.resolve(context)
-  const persisted = await persistedFont(context.config, key)
-  if (persisted) return persisted
+  if (!context.dev || restartCacheEnabled()) {
+    const persisted = await persistedFont(context.config, key)
+    if (persisted) return persisted
+  }
   return resolveAndPersist(definition, context, key)
 }
 
@@ -388,9 +403,8 @@ function resolveAndPersist(
   key: string,
 ): Promise<ResolvedFont> {
   const resolved = definition.resolve(context)
-  if (context.dev) {
-    void resolved.then(font => persistFont(context.config, key, font)).catch(() => undefined)
-  }
+  // Recorded in a build too: that record is what a deployed server reads instead of resolving.
+  void resolved.then(font => persistFont(context.config, key, font)).catch(() => undefined)
   return resolved
 }
 
@@ -717,7 +731,7 @@ async function emitRemoteFontFile(context: FontResolveContext, url: string, emit
     googleFontFileCache.set(url, cached)
   }
   const bytes = await cached
-  return emitFontBytes(context, bytes, fontExt(url), emit)
+  return emitFontBytes(context, bytes, fontExt(url), emit, undefined, url)
 }
 
 async function fetchFontFile(url: string) {
@@ -741,6 +755,7 @@ async function emitFontBytes(
   ext: string,
   emit: EmitFontOptions,
   sourceFile?: string,
+  originUrl?: string,
 ) {
   const hash = createHash('sha256').update(bytes).digest('hex').slice(0, 16)
   // Next's loader names emitted files `[hash]-s.p.[ext]`: `-s` when a
@@ -751,12 +766,39 @@ async function emitFontBytes(
   const mediaSegments = ['_next', 'static', 'media']
   const outDir = path.join(context.config.outPath, 'public', ...mediaSegments)
   const file = path.join(outDir, filename)
-  await mkdir(outDir, { recursive: true })
-  if (!existsSync(file)) {
+  const emitted = {
+    ext,
+    file,
+    type: fontMimeType(ext),
+    url: `/${mediaSegments.join('/')}/${filename}`,
+  }
+  if (existsSync(file)) return emitted
+  try {
+    await mkdir(outDir, { recursive: true })
     if (sourceFile) await copyFile(sourceFile, file)
     else await writeFile(file, bytes)
+    return emitted
+  } catch (error) {
+    // A deployed server's filesystem is read-only, and a font first reached by a request that was
+    // never prerendered lands here. A Google font still renders from its origin; a local font has
+    // no such address, so that one is a real error.
+    if (!originUrl) throw error
+    warnFontSelfHostUnavailable()
+    // `file` empty, not the path that was just proven unwritable: the resolution memo re-runs
+    // whenever a recorded file is missing from disk, so naming one here would re-resolve (and
+    // re-attempt the write) on every render for the life of the process.
+    return { ...emitted, file: '', url: originUrl }
   }
-  return { ext, file, type: fontMimeType(ext), url: `/${mediaSegments.join('/')}/${filename}` }
+}
+
+let warnedFontSelfHost = false
+function warnFontSelfHostUnavailable() {
+  if (warnedFontSelfHost) return
+  warnedFontSelfHost = true
+  console.warn(
+    'pnext: next/font assets cannot be written on this filesystem; serving them from their origin ' +
+      'instead of self-hosting.',
+  )
 }
 
 function normalizeLocalSources(
@@ -833,6 +875,9 @@ function loadGoogleMetadata(): Record<string, GoogleFontMetadata> {
     throw new Error(`Invalid Google font metadata file: ${override}`)
   }
 
+  // Resolved by specifier, never bundled: the data is a megabyte of metadata and the package is
+  // optional. Deployment adapters ship it through `deploymentPackages` instead — the import scan
+  // cannot see a dynamic specifier, and request time has no way to install one.
   const metadata =
     tryLoadGoogleMetadata('next-font/google/font-data.json') ?? tryLoadGoogleMetadata('next-font')
   if (metadata) return metadata

package/src/config.ts

@@ -23,8 +23,15 @@ export type ResolvedConfig = Required<Pick<PNextConfig, 'outDir' | 'basePath'>>
     typesPath: string
   }
 
+/**
+ * The out root before any `outDir`/`distDir` override. Also where a config source keeps the build
+ * artifacts it must emit BEFORE the override it carries is known — the next.config bundle sits here
+ * even for an app whose own output moved elsewhere, so deployment adapters ship it from here.
+ */
+export const DEFAULT_OUT_DIR = '.pnext'
+
 const defaultConfig = {
-  outDir: '.pnext',
+  outDir: DEFAULT_OUT_DIR,
   basePath: '',
 } satisfies Required<Pick<PNextConfig, 'outDir' | 'basePath'>>
 
@@ -48,7 +55,7 @@ export interface ConfigSourceOverrides {
 }
 export type ConfigSource = (
   root: string,
-  options: { dev?: boolean },
+  options: { dev?: boolean; serve?: boolean },
 ) => Promise<ConfigSourceOverrides>
 
 let configSource: ConfigSource | undefined
@@ -60,7 +67,7 @@ export function registerConfigSource(source: ConfigSource): void {
 async function resolveConfigSource(
   config: PNextConfig,
   root: string,
-  options: { dev?: boolean },
+  options: { dev?: boolean; serve?: boolean },
 ): Promise<ConfigSourceOverrides> {
   if (!config.compat?.next) return {}
   if (!configSource) {
@@ -70,9 +77,11 @@ async function resolveConfigSource(
   return configSource(root, options)
 }
 
+// `serve` marks a production start (including a deployment adapter's request handler): config sources
+// then consume what the build emitted instead of regenerating it, since request time can be read-only.
 export async function loadConfig(
   rootInput = process.cwd(),
-  options: { dev?: boolean } = {},
+  options: { dev?: boolean; serve?: boolean } = {},
 ): Promise<ResolvedConfig> {
   const root = canonicalRoot(path.resolve(rootInput))
   await loadEnv(root, options)