@wular/pnext 0.0.16 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wular/pnext",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "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

@@ -26,15 +26,16 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { loadConfig, pathToFileHref, type ResolvedConfig } from '../../config'
 import { bootstrapCompat } from '../../compat-bootstrap'
-import { ssrClientReference } from '../../client/reference'
+import { compiledClientReferenceFiles, ssrClientReference } from '../../client/reference'
 import {
   devClientModuleHref,
   devServerModuleHref,
   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'
@@ -281,6 +282,7 @@ export async function warmRouteModules(
 ) {
   const clientFiles = new Set<string>()
   const handlers: BuildManifest['routes'] = []
+  const pages: BuildManifest['routes'] = []
   const pageRoutes: string[] = []
 
   for (const route of manifest.routes) {
@@ -288,6 +290,7 @@ export async function warmRouteModules(
       if (!skip.has(route.file)) handlers.push(route)
       continue
     }
+    pages.push(route)
     pageRoutes.push(route.file)
     for (const reference of route.clientReferences) {
       if (ssrClientReference(reference) && existsSync(reference.file)) {
@@ -327,11 +330,93 @@ export async function warmRouteModules(
     // process' lifetime anyway, so a retry could not succeed either).
     report(route.file)
     try {
-      await import(pathToFileHref(route.file))
+      await import(await handlerModuleHref(config, route))
     } catch (error) {
       console.warn(`vercel adapter: importing ${route.file} failed during warmup:`, error)
     }
   }
+
+  // Pages last, one at a time: a module's vendor bundles are written when it is IMPORTED, not when
+  // it compiles, and a bundle this pass misses is one the read-only function cannot create later.
+  await importPageModules(config, pages, skip)
+
+  // Client modules for the same reason, plus the references only the compile saw - a 'use client'
+  // module inside a dependency is reached from a server component, so no route owns it. Vendoring
+  // one late is worse than failing: it is a second copy, whose React context the render never holds.
+  await importClientModules(
+    config,
+    new Set([...clientFiles, ...compiledClientReferenceFiles()]),
+    skip,
+  )
+
+  // Fonts resolve during a render, so a fully dynamic app emits none at build. The imports above ran
+  // the module-scope loader calls that declare them; flush to disk while it is still writable.
+  try {
+    await getFontExtensions().prewarmFontAssets(config, {})
+  } catch (error) {
+    console.warn('vercel adapter: emitting next/font assets failed during warmup:', error)
+  }
+}
+
+/** Import each SSR-eligible client module through its compiled href, the way the render does. */
+async function importClientModules(
+  config: ResolvedConfig,
+  clientFiles: ReadonlySet<string>,
+  skip: ReadonlySet<string>,
+) {
+  if (!getCompatModeExtensions().reactEnabled(config)) return
+  for (const file of clientFiles) {
+    if (skip.has(file)) continue
+    const href = await devClientModuleHref(config, file, 'build')
+    report(file, fileURLToPath(href))
+    try {
+      await import(href)
+    } catch (error) {
+      console.warn(`vercel adapter: importing ${file} failed during warmup:`, error)
+    }
+  }
+}
+
+/**
+ * Where the serve pipeline imports a route handler's module from — mirrors `moduleHrefForRoute` in
+ * cli/serve/pipeline.ts, guard included. Warming through the raw source instead leaves the compiled
+ * artifact unwritten, and the function then tries to compile it on the first request, against a
+ * read-only filesystem.
+ */
+function handlerModuleHref(config: ResolvedConfig, route: BuildManifest['routes'][number]) {
+  return config.compat?.next || config.compat?.react || config.compat?.reactCompiler
+    ? devServerModuleHref(config, route.file, 'build', {
+        conditionTarget: serverBundleTargetForRuntime(route.segmentConfig?.runtime),
+      })
+    : Promise.resolve(pathToFileHref(route.file))
+}
+
+/**
+ * Import every server module the page routes reach, deduped across routes so a shared layout is
+ * evaluated once. Reported with its artifact before the import, exactly like the handler loop: one
+ * that takes the process down is unambiguous and must not run again on the restart.
+ */
+async function importPageModules(
+  config: ResolvedConfig,
+  pages: BuildManifest['routes'],
+  skip: ReadonlySet<string>,
+) {
+  if (!getCompatModeExtensions().reactEnabled(config)) return
+  const imported = new Set<string>()
+  for (const route of pages) {
+    registerServerRuntime(config, route.sourceFiles)
+    for (const file of pageServerFiles(config, [route.file])) {
+      if (skip.has(file) || imported.has(file)) continue
+      imported.add(file)
+      const href = await devServerModuleHref(config, file, 'build')
+      report(file, fileURLToPath(href))
+      try {
+        await import(href)
+      } catch (error) {
+        console.warn(`vercel adapter: importing ${file} failed during warmup:`, error)
+      }
+    }
+  }
 }
 
 /**

package/src/cli/adapters/vercel.ts

@@ -116,8 +116,29 @@ function packRules(config: ResolvedConfig): PackRules {
   }
 }
 
-function shipsDir(pack: PackRules, name: string, source: string) {
-  return !pack.prunedDirs.has(name) || pack.keepPaths.has(path.resolve(source))
+/**
+ * A keep path and everything under it. Prefix, not equality: the compiled module cache mirrors the
+ * source layout, so a dependency's artifacts land in `<outDir>/cache/server/<profile>/node_modules/
+ * ...`. That segment names a source tree, not a package store, and pruning it by name ships the
+ * importer without the module it imports — the function then 500s on the first request that reaches
+ * it. Only the app's own build output is exempt; a real `node_modules` beside it still prunes.
+ */
+function withinKeepPath(pack: PackRules, source: string) {
+  const resolved = path.resolve(source)
+  for (const keep of pack.keepPaths) {
+    if (resolved === keep || resolved.startsWith(`${keep}${path.sep}`)) return true
+  }
+  return false
+}
+
+/**
+ * `isLink` is load-bearing, not a detail: the exemption covers real directories the build output
+ * owns, never a link out of it. The proxy shim links `node_modules` into `.pnext`, and following
+ * that would pull the whole store into the function.
+ */
+function shipsDir(pack: PackRules, name: string, source: string, isLink = false) {
+  if (!pack.prunedDirs.has(name)) return true
+  return !isLink && withinKeepPath(pack, source)
 }
 
 function shipsFile(pack: PackRules, name: string) {
@@ -146,15 +167,6 @@ export async function writeVercelOutput(
   const warm = options.warm ?? startWarmChild(config)
   await log.step('prepare output directory', () => emptyDir(outputPath))
 
-  await log.step('copy static files', () =>
-    copyStaticFiles(
-      path.join(config.outPath, 'public'),
-      path.join(outputPath, 'static'),
-      relative => !staticFiles[relative] || canServeStaticOnVercel(staticFiles[relative]),
-    ),
-  )
-  const overrides = await staticOverrides(path.join(config.outPath, 'public'), staticFiles)
-
   // The compiled set is already final once the child reaches its handler
   // phase, so `onCompiled` resolves this ahead of full completion and
   // writeServerFunction starts tracing while the child's handler imports
@@ -175,6 +187,17 @@ export async function writeVercelOutput(
   const functionPath = path.join(outputPath, 'functions', `${SERVER_FUNCTION}.func`)
   await writeServerFunction(config, manifest, functionPath, warmedModules, warmSettled, log)
 
+  // After the warm pass, never before: it is what emits next/font bytes under public/, and a fully
+  // dynamic app renders nothing at build, so copying earlier ships a CDN with no fonts.
+  await log.step('copy static files', () =>
+    copyStaticFiles(
+      path.join(config.outPath, 'public'),
+      path.join(outputPath, 'static'),
+      relative => !staticFiles[relative] || canServeStaticOnVercel(staticFiles[relative]),
+    ),
+  )
+  const overrides = await staticOverrides(path.join(config.outPath, 'public'), staticFiles)
+
   const routes: NonNullable<VercelConfig['routes']> = [
     // Chunk and font filenames are content-hashed; serve them immutable.
     {
@@ -466,7 +489,7 @@ async function copyTree(
   // 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, from, pack, visited)
   }
   // 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
@@ -480,7 +503,8 @@ 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, entry.isSymbolicLink()))
+        return
       if (entry.isSymbolicLink()) {
         const link = resolveLinkTarget(source)
         if (!link) return
@@ -494,7 +518,7 @@ async function copyTree(
       // 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, source, pack, visited)
       }
       if (entry.isDirectory()) return copyTree(source, target, pack, [], visited)
       if (entry.isFile() && shipsFile(pack, entry.name)) return linkOrCopyFile(source, target)
@@ -555,18 +579,25 @@ 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,
+  // Where `dir` was cloned from. Carried so the keep-path exemption reads the same here as in the
+  // walk: the clone's own paths are inside the function and would never match a source keep path.
+  from: string,
+  pack: PackRules,
+  visited: Set<string>,
+) {
+  const stack: [string, string][] = [[dir, from]]
   const pending: Promise<unknown>[] = []
   while (stack.length > 0) {
-    const current = stack.pop()!
+    const [current, currentFrom] = stack.pop()!
     for (const entry of readdirSync(current, { withFileTypes: true })) {
       const full = path.join(current, entry.name)
+      const source = path.join(currentFrom, 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
-      // function, so the walk's keep-path exemption cannot apply here.
-      if (pack.prunedDirs.has(entry.name)) {
+      // whole store into the function.
+      if (!shipsDir(pack, entry.name, source, entry.isSymbolicLink())) {
         rmSync(full, { recursive: true, force: true })
       } else if (entry.isSymbolicLink()) {
         const link = resolveLinkTarget(full)
@@ -580,7 +611,7 @@ async function normalizeClone(dir: string, pack: PackRules, visited: Set<string>
           pending.push(linkOrCopyFile(link.path, full))
         }
       } else if (entry.isDirectory()) {
-        stack.push(full)
+        stack.push([full, source])
       } else if (!shipsFile(pack, entry.name)) {
         rmSync(full, { force: true })
       }

package/src/cli/migrate/package-json.ts

@@ -3,7 +3,7 @@
 
 import { readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import { pnextVersionRange } from '../../utils/fs'
+import { pnextOptionalDependencyRange, pnextVersionRange } from '../../utils/fs'
 import type { MigrationResult } from './report'
 
 const SEPARATORS = new Set(['&&', '||', ';', '|', '&'])
@@ -132,6 +132,26 @@ export async function migratePackageJson(
       details: [`devDependencies: @wular/pnext ${versionRange}`],
     })
   }
+  // next/font/google resolves its metadata from `next-font`, one of pnext's optional dependencies.
+  // A hoisted store makes it resolve locally whether or not the app declares it, so an undeclared
+  // one only shows up as a 500 from a deployed function, where the closure ships what the app asks
+  // for. Declare it here, where the migration already knows the app uses the loader.
+  const fontRange = pnextOptionalDependencyRange('next-font')
+  if (
+    result.googleFontImports.length > 0 &&
+    fontRange &&
+    !('next-font' in dependencies) &&
+    !('next-font' in devDependencies)
+  ) {
+    dependencies['next-font'] = fontRange
+    result.edits.push({
+      file: 'package.json',
+      description: 'next-font added',
+      details: [
+        `dependencies: next-font ${fontRange} (next/font/google metadata, used by ${result.googleFontImports.length} file${result.googleFontImports.length === 1 ? '' : 's'})`,
+      ],
+    })
+  }
   if (!('preact' in dependencies) && !('preact' in devDependencies)) {
     dependencies.preact = '^10'
     result.edits.push({

package/src/cli/migrate/report.ts

@@ -27,10 +27,12 @@ export interface MigrationResult {
   reports: ReportItem[]
   /** Files reading cookies()/headers()/draftMode() synchronously (Next 14 style). */
   syncRequestApis: string[]
+  /** Files importing next/font/google, which needs the `next-font` metadata package. */
+  googleFontImports: string[]
 }
 
 export function emptyResult(): MigrationResult {
-  return { edits: [], reports: [], syncRequestApis: [] }
+  return { edits: [], reports: [], syncRequestApis: [], googleFontImports: [] }
 }
 
 export function printHeader(root: string, dryRun: boolean) {

package/src/cli/migrate/run.ts

@@ -36,9 +36,10 @@ export async function migrateApp(directory: string | undefined, options: { dryRu
 
   printHeader(root, options.dryRun)
   const result = emptyResult()
-  if (pkg) await migratePackageJson(root, pkg, result, options.dryRun)
-  // The scan runs first: what it finds (sync request APIs) decides what the config enables.
+  // The scan runs first: what it finds decides what the config enables (sync request APIs) and
+  // which dependencies the app needs (next/font/google → next-font).
   await withSpinner('Scanning sources ...', () => scanSources(root, result))
+  if (pkg) await migratePackageJson(root, pkg, result, options.dryRun)
   await createPnextConfig(root, result, options.dryRun)
   await migrateTsconfig(root, result, options.dryRun)
   await removeNextEnv(root, result, options.dryRun)

package/src/cli/migrate/scan.ts

@@ -53,6 +53,9 @@ export async function scanSources(root: string, result: MigrationResult) {
         streaming.push(relative)
       }
       if (specifier === 'next/head') headImports.push(relative)
+      // next/font/local reads the app's own files; only the Google loader needs the metadata
+      // package, so only it earns the dependency.
+      if (specifier === 'next/font/google') result.googleFontImports.push(relative)
     }
     if (readsRequestApiSynchronously(text)) result.syncRequestApis.push(relative)
   }

package/src/client/reference.ts

@@ -1,4 +1,22 @@
 import { createHash } from 'node:crypto'
+import path from 'node:path'
+
+/**
+ * Every file this process stubbed as a client reference. The route manifest only records what the
+ * scan attributes to a route, so a `'use client'` module inside a dependency - which only the vendor
+ * pass sees, the package entry carrying no directive - is missing from it.
+ */
+const compiledClientReferences = new Set<string>()
+
+/** @internal */
+export function noteCompiledClientReference(file: string) {
+  compiledClientReferences.add(path.resolve(file))
+}
+
+/** @internal Read by the vercel adapter's warm pass, so it compiles these before the deploy. */
+export function compiledClientReferenceFiles(): ReadonlySet<string> {
+  return compiledClientReferences
+}
 
 export interface ClientReference {
   id: string

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

@@ -98,15 +98,28 @@ interface NormalizedLocalSource {
   weight?: string
 }
 
-const fontStorageKey = Symbol.for('pnext.compat.font.storage')
-const fontRuntimeGlobal = globalThis as typeof globalThis &
-  Record<symbol, AsyncLocalStorage<FontScope> | undefined>
-const fontStorage = (fontRuntimeGlobal[fontStorageKey] ??= new AsyncLocalStorage<FontScope>())
+/**
+ * State every copy of this module must agree on: the app reaches next/font through the COMPILED
+ * runtime, the framework through node_modules, so a plain module-level value exists once per copy.
+ */
+const fontRuntimeGlobal = globalThis as typeof globalThis & Record<symbol, unknown>
+const sharedAcrossInstances = <T>(key: symbol, create: () => T) =>
+  (fontRuntimeGlobal[key] ??= create()) as T
+
+const fontStorage = sharedAcrossInstances(
+  Symbol.for('pnext.compat.font.storage'),
+  () => new AsyncLocalStorage<FontScope>(),
+)
 const allowedDisplayValues = new Set(['auto', 'block', 'swap', 'fallback', 'optional'])
 const require = createRequire(import.meta.url)
 const googleCssCache = new Map<string, Promise<string>>()
 const googleFontFileCache = new Map<string, Promise<Uint8Array>>()
-const resolvedFontCache = new Map<string, Promise<ResolvedFont>>()
+// Shared for the same reason as declaredFonts below, and so a request-time render reuses the
+// build's resolution instead of re-fetching the Google stylesheet on every cold start.
+const resolvedFontCache = sharedAcrossInstances(
+  Symbol.for('pnext.compat.font.resolved'),
+  () => new Map<string, Promise<ResolvedFont>>(),
+)
 let googleMetadataCache: Record<string, GoogleFontMetadata> | undefined
 
 /**
@@ -114,7 +127,10 @@ let googleMetadataCache: Record<string, GoogleFontMetadata> | undefined
  * Definitions are created when the app's font module evaluates - well before the render that registers
  * them - which is what makes the resolve prewarmable.
  */
-const declaredFonts = new Map<string, FontDefinition>()
+const declaredFonts = sharedAcrossInstances(
+  Symbol.for('pnext.compat.font.declared'),
+  () => new Map<string, FontDefinition>(),
+)
 
 /**
  * Resolve the declared fonts ahead of the render that will ask for them. Fire-and-forget: this only
@@ -751,12 +767,19 @@ 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)) {
-    if (sourceFile) await copyFile(sourceFile, file)
-    else await writeFile(file, bytes)
+  const asset = {
+    ext,
+    file,
+    type: fontMimeType(ext),
+    url: `/${mediaSegments.join('/')}/${filename}`,
   }
-  return { ext, file, type: fontMimeType(ext), url: `/${mediaSegments.join('/')}/${filename}` }
+  // Existence first, mkdir second: at request time the filesystem is read-only, and an
+  // unconditional mkdir throws EROFS just to discover the build already emitted these bytes.
+  if (existsSync(file)) return asset
+  await mkdir(outDir, { recursive: true })
+  if (sourceFile) await copyFile(sourceFile, file)
+  else await writeFile(file, bytes)
+  return asset
 }
 
 function normalizeLocalSources(

package/src/runtime/modules.ts

@@ -12,6 +12,7 @@ import {
   clientReferenceModuleSource,
   hasUseClientDirective,
 } from '../client/reference-stub'
+import { noteCompiledClientReference } from '../client/reference'
 import { getClientActionBundler } from '../dev/client-actions'
 import { deferredDynamicImportSpecifiers, devDynamicSplitEnabled } from '../resolve/dynamic'
 import { noteModuleGeneration, noteModuleImported } from './module-generations'
@@ -2190,6 +2191,7 @@ async function writeClientReferenceModules(
       await writeClientReferenceModule(stub, reference.file, [...reference.exports].sort())
       specifiers.set(specifier, stub)
       files.add(path.resolve(reference.file))
+      noteCompiledClientReference(reference.file)
     }),
   )
 

package/src/runtime/vendor-build.ts

@@ -26,7 +26,7 @@ import {
   type ServerEsbuildPluginOptions,
 } from '../extensions'
 import { pathToFileHref, type CompatAliasTarget, type ResolvedConfig } from '../config'
-import { devArtifactUsable, noteDevArtifactWritten } from './module-cache'
+import { devArtifactUsable, devSourceIdentity, noteDevArtifactWritten } from './module-cache'
 import {
   getExternalPackagePolicy,
   isEsmModuleEntry,
@@ -47,6 +47,7 @@ import {
   clientReferenceModuleSource,
   hasUseClientDirective,
 } from '../client/reference-stub'
+import { noteCompiledClientReference } from '../client/reference'
 import { reactCompatEnabled } from '../render/hooks'
 import { writeFileAtomic } from '../utils/fs'
 import { formatDuration } from '../utils/verbose'
@@ -156,6 +157,11 @@ export async function externalServerPackageHref(
  * Artifact identity: what the bundle is compiled FROM, never who asked. Keying on the importer's
  * directory (what `require.resolve` fell back to when a package publishes no `require` condition)
  * split one package into one build per importing directory.
+ *
+ * Every path in it is workspace-relative, never absolute — for the same reason the module graph
+ * names artifacts that way (see `portableSourcePath`). This key names the file, and a deployed
+ * function replays the same workspace from a different root: an absolute key misses the whole
+ * shipped vendor cache and re-vendors onto a read-only filesystem.
  */
 function vendorArtifactKey(
   config: ResolvedConfig,
@@ -163,9 +169,12 @@ function vendorArtifactKey(
   conditionTarget: ServerBundleTarget,
   source: string,
 ) {
-  return `${config.outPath}\0${target}\0${conditionTarget}\0${source}`
+  return `${vendorPortablePath(config, config.outPath)}\0${target}\0${conditionTarget}\0${source}`
 }
 
+const vendorPortablePath = (config: ResolvedConfig, file: string) =>
+  devSourceIdentity(file, config.workspaceRoot)
+
 function vendorArtifactFile(config: ResolvedConfig, key: string) {
   return path.join(config.outPath, 'cache', 'server', 'vendor', `${hashBundleSpecifier(key)}.mjs`)
 }
@@ -214,7 +223,9 @@ function vendorBuildPlan(
     config,
     target,
     conditionTarget,
-    entry ?? `${path.resolve(resolveDir)}\0${specifier}`,
+    entry
+      ? vendorPortablePath(config, entry)
+      : `${vendorPortablePath(config, path.resolve(resolveDir))}\0${specifier}`,
   )
   const file = vendorArtifactFile(config, key)
   return {
@@ -1290,6 +1301,10 @@ function vendorClientBoundaryLoad(config: ResolvedConfig) {
   const scan = async (file: string): Promise<OnLoadResult | undefined> => {
     const source = await readFile(file, 'utf8').catch(() => undefined)
     if (source === undefined || !hasUseClientDirective(source)) return undefined
+    // A 'use client' file the vendor pass found inside a package — the render will import it as a
+    // client module, and nothing else records it (the server-source scan only sees the package
+    // entry, which carries no directive). The vercel warm pass reads this to compile it at build.
+    noteCompiledClientReference(file)
     return {
       contents: clientReferenceModuleSource(
         file,

package/src/utils/fs.ts

@@ -137,3 +137,16 @@ export function pnextVersionRange() {
   const { version } = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version: string }
   return `^${version}`
 }
+
+/**
+ * The range pnext declares for one of its optional dependencies. An app that uses the feature has to
+ * declare the package itself — the vercel adapter ships pnext's optional deps only where the app
+ * depends on them too — so the range has to come from here rather than being written down twice.
+ */
+export function pnextOptionalDependencyRange(name: string) {
+  const pkgPath = fileURLToPath(new URL('../../package.json', import.meta.url))
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as {
+    optionalDependencies?: Record<string, string>
+  }
+  return pkg.optionalDependencies?.[name]
+}