@wular/pnext 0.0.15 → 0.0.17

package/bin/pnext

@@ -1,7 +1,9 @@
 #!/bin/sh
 
+# Presence only. The version floor is enforced in src/cli/index.ts, where
+# Bun.version costs nothing — asking `bun --version` here would fork per command.
 if ! command -v bun >/dev/null 2>&1; then
-  echo "pnext requires Bun. Install it from https://bun.sh/get" >&2
+  echo "pnext requires Bun >=1.3.6. Install it from https://bun.sh/get" >&2
   exit 1
 fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wular/pnext",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "A fast little framework for server-first React apps, fully compatible with Next.js",
   "type": "module",
   "bin": {
@@ -33,6 +33,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "bun": ">=1.3.6"
+  },
   "exports": {
     ".": "./src/index.ts",
     "./internal": "./src/internal.ts",

package/reference/getting-started.md

@@ -2,7 +2,7 @@
 
 pnext is a Preact framework for file-routed apps. It renders on the server by default and ships client JavaScript only where a component opts in.
 
-> pnext requires [Bun](https://bun.sh/get) - make sure it is installed first.
+> pnext requires [Bun](https://bun.sh/get) 1.3.6 or newer - make sure it is installed first.
 
 <!-- tabs:start -->
 

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) {
@@ -381,9 +402,12 @@ export default Object.assign(handler, { fetch: handler });
     `${JSON.stringify(
       {
         // The Bun function runtime (project-level `bunVersion` does not apply
-        // to prebuilt Build Output API functions). Note: bun1.x functions have
-        // a 150 MiB uncompressed size limit vs 250 MiB for nodejs.
-        runtime: 'bun1.x',
+        // to prebuilt Build Output API functions, so the version is pinned
+        // here). Not `bun1.x`: that resolves to Bun 1.3.14, which segfaults a
+        // second into serving and takes the whole function down with SIGABRT.
+        // Note: bun functions have a 150 MiB uncompressed size limit vs 250
+        // MiB for nodejs.
+        runtime: 'bun1.4.x',
         handler: 'index.mjs',
         launcherType: 'Nodejs',
         architecture: FUNCTION_PLATFORM.architecture,
@@ -463,7 +487,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
@@ -477,7 +501,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
@@ -491,7 +516,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)
@@ -552,18 +577,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)
@@ -577,7 +609,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/index.ts

@@ -4,9 +4,29 @@ import path from 'node:path'
 import { markBoot } from './boot/trace'
 import { commandBinaryName, nameEsbuildProcess, namedBunBinary } from './boot/named-bin'
 
+const MIN_BUN = '1.3.6'
+// Not a floor but a hole in one: 1.3.14 segfaults about a second into serving,
+// so a pnext server dies before its first response with no error of its own to
+// show. 1.3.13 and 1.4.x are both fine.
+const BROKEN_BUN = new Set(['1.3.14'])
+
 // Reached only if something bypassed bin/pnext (which guards the same way).
 if (typeof Bun === 'undefined') {
-  console.error('pnext requires Bun. Install it from https://bun.sh/get')
+  console.error(`pnext requires Bun >=${MIN_BUN}. Install it from https://bun.sh/get`)
+  process.exit(1)
+}
+// A prerelease sorts below its own release, so compare the release: a 1.4.0-canary is a 1.4.0 here.
+const bunVersion = Bun.version.split('-')[0] ?? Bun.version
+if (BROKEN_BUN.has(bunVersion)) {
+  console.error(
+    `pnext does not support Bun ${Bun.version}: it crashes the process at runtime. ` +
+      'Upgrade to latest Bun with `bun upgrade`.',
+  )
+  process.exit(1)
+} else if (!Bun.semver.satisfies(bunVersion, `>=${MIN_BUN}`)) {
+  console.error(
+    `pnext requires Bun >=${MIN_BUN}, found ${Bun.version}. Upgrade with \`bun upgrade\`.`,
+  )
   process.exit(1)
 }
 

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/cli/serve/pipeline.ts

@@ -14,6 +14,7 @@ import { loadConfig, pathToFileHref } from '../../config'
 import type { ResolvedConfig } from '../../config'
 import { bootstrapCompat } from '../../compat-bootstrap'
 import { registerServerRuntime, serverBundleTargetForRuntime } from '../../runtime/loader'
+import { importModuleOnce } from '../../runtime/modules'
 import { applyProxyResponse, createProxyRunner } from '../../routing/proxy'
 import {
   isPprShellUpgradeEligible,
@@ -146,7 +147,7 @@ export async function createRequestHandler(
           const href = compatModuleMode(config)
             ? await moduleHrefForRoute(config, route)
             : pathToFileHref(route.file)
-          const module = (await import(href)) as Parameters<typeof handleRouteModule>[0]
+          const module = await importModuleOnce<Parameters<typeof handleRouteModule>[0]>(href)
           const rendered = await getRenderExtensions().collectRenderMeta(
             () =>
               withRouteRuntime(route.segmentConfig?.runtime, () =>
@@ -980,8 +981,9 @@ async function handleRoute(
       const href = compatModuleMode(config)
         ? await moduleHrefForRoute(config, route)
         : new URL(`file://${route.file}`).href
-      const imported = (await import(href)) as RouteHandlerModule &
-        Parameters<typeof metadataRouteHandlerModule>[0]
+      const imported = await importModuleOnce<
+        RouteHandlerModule & Parameters<typeof metadataRouteHandlerModule>[0]
+      >(href)
       return (metadataRouteHandlerModule(imported, route) ?? imported) as RouteHandlerModule
     })
     return spans.withRouteHandlerSpan(route.route, () =>

package/src/render/renderer.ts

@@ -26,7 +26,12 @@ import {
 import { clientEntryName } from '../client/chunk-name'
 import { pathToFileHref, type ResolvedConfig } from '../config'
 import { markErrorLogged } from '../utils/error-log'
-import { devClientModuleHref, devServerModuleHref, importDevModule } from '../runtime/modules'
+import {
+  devClientModuleHref,
+  devServerModuleHref,
+  importDevModule,
+  importModuleOnce,
+} from '../runtime/modules'
 import { serverBundleTargetForRuntime } from '../runtime/loader'
 import {
   getActionModuleExtensions,
@@ -663,8 +668,8 @@ function clientModuleHref(file: string, options: ModuleLoadOptions) {
 }
 
 async function importModule(file: string, options: ModuleLoadOptions) {
-  // In dev, re-throw a module's FIRST evaluation error on every later request
-  // rather than the downstream symptom a half-evaluated module produces.
+  // Re-throw a module's FIRST evaluation error on every later request rather
+  // than the downstream symptom a half-evaluated module produces.
   let module: Record<string, unknown>
   if (options.moduleLoader) module = await options.moduleLoader(file)
   else if (options.dev) {
@@ -672,7 +677,7 @@ async function importModule(file: string, options: ModuleLoadOptions) {
   } else {
     const href = await moduleHref(file, options)
     await drainPreplanBuilds()
-    module = (await import(href)) as Record<string, unknown>
+    module = await importModuleOnce<Record<string, unknown>>(href)
   }
   // Tag any 'use server' action module's exports with their wire id so
   // <form action={fn}> can progressively enhance. Compat-owned; a no-op for a
@@ -687,7 +692,7 @@ async function importClientModule(file: string, options: ModuleLoadOptions) {
   const href = await clientModuleHref(file, options)
   if (options.dev) return importDevModule<Record<string, unknown>>(href)
   await drainPreplanBuilds()
-  return import(href) as Promise<Record<string, unknown>>
+  return importModuleOnce<Record<string, unknown>>(href)
 }
 
 function clientScriptPath(route: RouteManifestEntry, dev?: boolean) {

package/src/runtime/modules.ts

@@ -185,21 +185,34 @@ const routeModuleLoaders = new Map<string, Promise<DevRouteModuleLoaders>>()
 // and the entry is never consulted again.
 const moduleEvalErrors = new Map<string, unknown>()
 
-/** Import a compiled dev module, re-throwing its first evaluation error on later imports. */
-export async function importDevModule<T>(href: string): Promise<T> {
+/**
+ * Import a compiled module, re-throwing its first evaluation error on later imports.
+ *
+ * Production needs this as much as dev: a re-import resolves with a half-evaluated namespace whose
+ * `export const` bindings are still in TDZ, so the render's next read (`module.metadata`) throws
+ * `Cannot access 'metadata' before initialization` and that replaces the real error in the response.
+ * Prod hrefs are content-addressed too, so the entry keys the same way dev's does.
+ */
+export async function importModuleOnce<T>(href: string): Promise<T> {
   if (moduleEvalErrors.has(href)) throw moduleEvalErrors.get(href)
-  // Pre-planned vendor builds are enqueued without an awaiter; nothing
-  // evaluates until they all settle (no-op when the pipeline is empty).
-  await drainPreplanBuilds()
   try {
-    const module = (await import(href)) as T
-    noteModuleImported(href)
-    return module
+    return (await import(href)) as T
   } catch (error) {
     moduleEvalErrors.set(href, error)
     throw error
   }
 }
+
+/** `importModuleOnce` plus dev's registry-generation accounting. */
+export async function importDevModule<T>(href: string): Promise<T> {
+  if (moduleEvalErrors.has(href)) throw moduleEvalErrors.get(href)
+  // Pre-planned vendor builds are enqueued without an awaiter; nothing
+  // evaluates until they all settle (no-op when the pipeline is empty).
+  await drainPreplanBuilds()
+  const module = await importModuleOnce<T>(href)
+  noteModuleImported(href)
+  return module
+}
 const extensionlessDynamicImportExtensions = new Set(['.ts', '.tsx', '.js', '.jsx', '.mts', '.cts'])
 const externalLoadNamespaces = {
   server: 'pnext-route-external-server',

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]
+}