@wular/pnext 0.0.24 → 0.1.0

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) 1.3.6 or newer - make sure it is installed first.
+> pnext requires [Bun](https://bun.sh/get) 1.3.10 or newer (1.4.0 recommended) - make sure it is installed first.
 
 <!-- tabs:start -->
 

package/src/api/client-navigation.ts

@@ -176,15 +176,17 @@ function useLocation() {
         return previous === next ? previous : next
       })
     locationListeners().add(listener)
-    window.addEventListener('popstate', listener)
     // Re-read once the listener is attached: the URL can move between the
     // render that captured it and this effect (a history traversal landing
     // while a swapped-in tree mounts), and nothing was listening for that one.
+    // Raw popstate is deliberately NOT a subscription source: on a full
+    // traversal the address bar moves before the cached document commits, so
+    // rendering that URL into the departing island can consume the only route
+    // change before the persistent island is grafted into the committed tree.
+    // The router broadcasts shallow traversals immediately and full traversals
+    // after their DOM commit.
     listener()
-    return () => {
-      locationListeners().delete(listener)
-      window.removeEventListener('popstate', listener)
-    }
+    return () => locationListeners().delete(listener)
   }, [])
 
   return location

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

@@ -1,10 +1,14 @@
 /**
- * Module warm-up for the vercel adapter - run in its own process.
+ * Module warm-up for a production build - run in its own process.
  *
- * Request time on Vercel is read-only, so everything a production start would compile or vendor
- * lazily has to be on disk already: this step compiles every module the production server can need
- * into the build cache and imports the app's route handlers once so their on-demand vendor bundles
- * get written now.
+ * Every build compiles the modules its production server can need (`compile` mode): a built app that
+ * still compiles on its first request pays a whole cold pipeline - esbuild service included - inside
+ * the response, which is neither a build output nor something a served request should do.
+ *
+ * The vercel adapter needs strictly more (`full` mode). Request time on Vercel is read-only, so
+ * everything a production start would compile or *vendor* lazily has to be on disk already: that
+ * mode also imports the app's route handlers and page modules once, so their on-demand vendor
+ * bundles get written now.
  *
  * Importing handlers runs the app's own server code, which can crash the runtime rather than throw,
  * so the whole pass runs in a child that writes into the same on-disk build cache the parent reads
@@ -35,7 +39,13 @@ import {
 import { getCompatModeExtensions } from '../../extensions'
 import { getFontExtensions } from '../../render/hooks'
 import { findConventionFiles, findLayouts } from '../../routing/routes'
-import { registerServerRuntime, serverBundleTargetForRuntime } from '../../runtime/loader'
+import {
+  prewarmServerTransforms,
+  registerServerRuntime,
+  serverBundleTargetForRuntime,
+} from '../../runtime/loader'
+import { cacheRoot } from '../../runtime/module-cache'
+import { listFiles } from '../../utils/fs'
 import { namedBunBinary } from '../boot/named-bin'
 import type { VerboseLogger } from '../../utils/verbose'
 import type { BuildManifest } from '../../types'
@@ -73,6 +83,15 @@ const ATTEMPT_TIMEOUT_MS = 10 * 60_000
 // before concluding the app cannot be warmed.
 const MAX_ATTEMPTS = 3
 
+/**
+ * `compile` writes every artifact the production server would otherwise build inside a request;
+ * `full` additionally imports the app's own modules so their vendor bundles land too (see above).
+ */
+export type WarmMode = 'compile' | 'full'
+
+/** argv flag rather than a stdin message: the child picks its mode before the first prewarm batch. */
+const FULL_MODE_FLAG = '--full'
+
 export interface WarmChild {
   /**
    * Hand the child the page sources from the route scan so it compiles them
@@ -87,17 +106,38 @@ export interface WarmChild {
    * child runs handlers concurrently.
    */
   finish(log: VerboseLogger, onCompiled?: (modules: string[]) => void): Promise<string[]>
+  /** Stop every attempt owned by this build. Safe to call after `finish` or more than once. */
+  kill(): void
 }
 
-type WarmProcess = Bun.Subprocess<'pipe', 'pipe', 'inherit'>
+type WarmProcess = Bun.Subprocess<'pipe', 'pipe', 'pipe'>
 
 /**
  * Spawn the warm child. Call as early in the build as possible: it boots while the build runs and
  * does no work until `finish`, which must be called only after the build manifest is on disk. Never
  * throws - a warm-up that cannot start degrades to "no warmed modules", which `finish` reports.
  */
-export function startWarmChild(config: ResolvedConfig): WarmChild {
-  const spawn = () => spawnWarmProcess(config)
+export function startWarmChild(config: ResolvedConfig, mode: WarmMode = 'full'): WarmChild {
+  const children = new Set<WarmProcess>()
+  let disposed = false
+  const spawn = () => {
+    if (disposed) return undefined
+    const child = spawnWarmProcess(config, mode)
+    if (!child) return undefined
+    children.add(child)
+    void child.exited.finally(() => children.delete(child))
+    void forwardWarmStderr(child)
+    return child
+  }
+  const killOnExit = () => kill()
+  const kill = () => {
+    if (disposed) return
+    disposed = true
+    process.off('exit', killOnExit)
+    for (const child of children) child.kill()
+    children.clear()
+  }
+  process.once('exit', killOnExit)
   const first = spawn()
   return {
     prewarm(files) {
@@ -109,17 +149,37 @@ export function startWarmChild(config: ResolvedConfig): WarmChild {
         // broken pipe: the child is gone; `finish` reports why
       }
     },
-    finish: (log, onCompiled) => warmWithRestarts(first, spawn, log, onCompiled),
+    finish: (log, onCompiled) =>
+      warmWithRestarts(first, spawn, mode, log, onCompiled).finally(kill),
+    kill,
   }
 }
 
-function spawnWarmProcess(config: ResolvedConfig): WarmProcess | undefined {
+/** Forward diagnostics without giving the warm child the caller's stderr descriptor. */
+async function forwardWarmStderr(child: WarmProcess) {
+  try {
+    const reader = child.stderr.getReader()
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) return
+      process.stderr.write(value)
+    }
+  } catch {
+    // The build shutting the child down also closes this pipe.
+  }
+}
+
+function spawnWarmProcess(config: ResolvedConfig, mode: WarmMode): WarmProcess | undefined {
   const entry = fileURLToPath(new URL(import.meta.url))
+  const argv = mode === 'full' ? [config.root, FULL_MODE_FLAG] : [config.root]
   try {
-    return Bun.spawn(
-      [namedBunBinary('pnext-warm'), '--conditions=react-server', entry, config.root],
-      { cwd: config.root, stdin: 'pipe', stdout: 'pipe', stderr: 'inherit', env: process.env },
-    )
+    return Bun.spawn([namedBunBinary('pnext-warm'), '--conditions=react-server', entry, ...argv], {
+      cwd: config.root,
+      stdin: 'pipe',
+      stdout: 'pipe',
+      stderr: 'pipe',
+      env: process.env,
+    })
   } catch {
     return undefined // no child (fork limit, unsupported platform)
   }
@@ -128,6 +188,7 @@ function spawnWarmProcess(config: ResolvedConfig): WarmProcess | undefined {
 async function warmWithRestarts(
   first: WarmProcess | undefined,
   spawn: () => WarmProcess | undefined,
+  mode: WarmMode,
   log: VerboseLogger,
   onCompiled?: (modules: string[]) => void,
 ) {
@@ -162,7 +223,7 @@ async function warmWithRestarts(
     // thing it would redo is what killed it.
     child = finished.size > before && attempt < MAX_ATTEMPTS ? spawn() : undefined
     if (child) log.log(`warm-up ${failure} after ${finished.size} files; restarting past them`)
-    else warmIncomplete(failure, finished.size)
+    else warmIncomplete(failure, finished.size, mode)
   }
   fireOnCompiled?.()
   return compiled()
@@ -222,11 +283,13 @@ async function runAttempt(
   return child.signalCode ? `was killed by ${child.signalCode}` : `exited with code ${code}`
 }
 
-function warmIncomplete(failure: string, done: number) {
+function warmIncomplete(failure: string, done: number, mode: WarmMode) {
   console.warn(
-    `vercel adapter: module warm-up ${failure} after warming ${done} file(s). The function ships ` +
-      'without the rest of its module cache and may fail to render those routes at request time, ' +
-      "where Vercel's filesystem is read-only.",
+    `pnext build: module warm-up ${failure} after warming ${done} file(s). ` +
+      (mode === 'full'
+        ? 'The function ships without the rest of its module cache and may fail to render those ' +
+          "routes at request time, where Vercel's filesystem is read-only."
+        : 'The production server compiles the rest on the first request that needs them.'),
   )
 }
 
@@ -279,6 +342,7 @@ export async function warmRouteModules(
   config: ResolvedConfig,
   manifest: BuildManifest,
   skip: ReadonlySet<string> = new Set(),
+  mode: WarmMode = 'full',
 ) {
   const clientFiles = new Set<string>()
   const handlers: BuildManifest['routes'] = []
@@ -313,9 +377,31 @@ export async function warmRouteModules(
             report(file, fileURLToPath(href)),
           ),
         ),
+      // Handler artifacts are otherwise only written by the import below, which
+      // `compile` mode does not run: compiling them here is what keeps a handler
+      // route's first served request off the compile pipeline too.
+      ...(mode === 'compile'
+        ? handlers.map(async route => {
+            registerServerRuntime(config, route.sourceFiles)
+            report(route.file, fileURLToPath(await handlerModuleHref(config, route)))
+          })
+        : []),
     ])
   }
   console.log(COMPILED_MARKER)
+  if (mode === 'compile') {
+    // Transform is the tail of the compile pipeline: an artifact is transformed when it is first
+    // imported, so a server that skipped every compile would still start esbuild for this alone.
+    // The import pass below covers it in `full` mode; here it runs standalone, without app code.
+    for (const route of [...pages, ...handlers]) registerServerRuntime(config, route.sourceFiles)
+    const modules = cacheRoot(config.outPath)
+    await prewarmServerTransforms(modules, await listFiles(modules))
+    return
+  }
+  // Everything below runs the app's own code to capture what only an import
+  // writes (vendor bundles, next/font bytes). A normal build serves from a
+  // writable disk and creates those on demand; only a read-only deployment
+  // target needs them now.
 
   // Handlers come last, and only once nothing else is in flight. Importing them runs the app's own
   // server code (auth, db pools, telemetry), and that code running *concurrently* with the compile
@@ -447,18 +533,24 @@ async function readWarmRequests(config: ResolvedConfig): Promise<Partial<WarmReq
 
 if (import.meta.main) {
   const root = process.argv[2]
-  const config = await loadConfig(root)
+  const mode: WarmMode = process.argv.includes(FULL_MODE_FLAG) ? 'full' : 'compile'
+  // This helper's stderr is forwarded to the user-facing build. The parent
+  // already validated and printed next.config warnings, so avoid duplicates.
+  const config = await loadConfig(root, { warnings: false })
   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.
-  setEmitCompiledSpecifiersManifest(true)
+  // Only the vercel adapter reads the specifier manifests back (its trace step);
+  // a plain build would write them for nothing.
+  setEmitCompiledSpecifiersManifest(mode === 'full')
   // Blocks until the parent sends the go-ahead, i.e. until the manifest is
   // written; a prewarm batch may arrive and run before that.
   const request = await readWarmRequests(config)
-  const manifest = JSON.parse(
-    await readFile(path.join(config.outPath, 'manifest.json'), 'utf8'),
-  ) as BuildManifest
-  await warmRouteModules(config, manifest, new Set(request.skip ?? []))
+  // A build that fails closes stdin without a go-ahead and never writes the manifest. There is
+  // nothing to warm and nothing to report: exiting quietly keeps the failed build's own error the
+  // only thing on stderr.
+  const manifestFile = path.join(config.outPath, 'manifest.json')
+  if (!request.skip || !existsSync(manifestFile)) process.exit(0)
+  const manifest = JSON.parse(await readFile(manifestFile, 'utf8')) as BuildManifest
+  await warmRouteModules(config, manifest, new Set(request.skip ?? []), mode)
   // App code reached through a route handler can leave the loop alive (a db
   // pool, a stray interval); the warm pass is done either way.
   process.exit(0)

package/src/cli/build.ts

@@ -4,7 +4,7 @@ import { createRequire } from 'node:module'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { writeVercelOutput } from './adapters/vercel'
-import { startWarmChild } from './adapters/vercel-warm'
+import { startWarmChild, type WarmChild } from './adapters/vercel-warm'
 import { devOutSegment, loadConfig, pathToFileHref } from '../config'
 import { bootstrapCompat } from '../compat-bootstrap'
 import {
@@ -67,7 +67,12 @@ import {
 } from '../render/ppr'
 import { handleRouteModule, staticRouteParams, type RouteHandlerModule } from '../routing/handler'
 import { runWithCacheScope } from '../request/cache'
-import { devServerModuleHref, setEmitCompiledSpecifiersManifest } from '../runtime/modules'
+import {
+  devServerModuleHref,
+  resetModuleGraphFailure,
+  setEmitCompiledSpecifiersManifest,
+  throwIfModuleGraphFailed,
+} from '../runtime/modules'
 import {
   beginDynamicBailoutProbe,
   endDynamicBailoutProbe,
@@ -151,34 +156,39 @@ interface BuildOptions {
 
 export async function buildProject(root?: string, options: BuildOptions = {}) {
   clearBuildParallelPhases()
+  resetModuleGraphFailure()
   // One read per source for the whole build (route-fact walk, action discovery,
   // client loader), released here so nothing survives the build.
   beginSourceScope()
   // 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 lifecycle: { warm?: WarmChild } = {}
   try {
-    return await runBuild(root, options)
+    return await runBuild(root, options, lifecycle)
   } catch (error) {
     // A parallel phase that already failed (a type error) is the root cause of
     // whatever broke downstream; report it instead of the symptom.
     const phaseError = buildParallelPhaseError()
     throw phaseError ?? error
   } finally {
+    lifecycle.warm?.kill()
     endSourceScope()
     restoreSpecifiersManifest()
     flushDevModuleCaches()
   }
 }
 
-async function runBuild(root: string | undefined, options: BuildOptions) {
+async function runBuild(
+  root: string | undefined,
+  options: BuildOptions,
+  lifecycle: { warm?: WarmChild },
+) {
   const verbose = options.verbose ?? false
   const log = createVerboseLogger(verbose, 'build')
   const startedAt = performance.now()
 
-  console.log(
-    `${cyan('▲')} ${bold('pnext')} ${dim('— Creating an optimized production build ...\n')}`,
-  )
+  console.log(`⚡ ${bold('pnext')} ${dim('— Creating an optimized production build ...\n')}`)
   const config = await loadConfig(root)
   const buildCache = lookupBuildCache(config, options)
   // Compat plugin loader: the single gated seam that populates the core
@@ -206,10 +216,13 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
   // Load Tailwind on the CSS worker while the steps below run, so the first
   // stylesheet doesn't pay its cold boot.
   warmCssPipeline(config)
-  // The vercel adapter's warm pass runs in its own process; start it here so
-  // its boot overlaps the build and only the warming itself lands on the
-  // adapter step.
-  const warm = options.adapter === 'vercel' ? startWarmChild(config) : undefined
+  // The warm pass runs in its own process; start it here so its boot overlaps the build and only the
+  // warming itself lands on its own step. Every build compiles what the production server would
+  // otherwise compile inside its first request; the vercel adapter additionally imports app modules
+  // for the bundles only an import writes (see adapters/vercel-warm).
+  const warmMode = options.adapter === 'vercel' ? 'full' : 'compile'
+  const warm = startWarmChild(config, warmMode)
+  lifecycle.warm = warm
   await log.step('prepare output directory', async () => {
     // Build-owned outputs only: `<outRoot>/dev` belongs to a possibly-running
     // dev server and must survive.
@@ -252,10 +265,10 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
       `--debug-build-paths ${options.debugBuildPaths} — ${routes.length} route${routes.length === 1 ? '' : 's'} kept`,
     )
   }
-  // The page routes' server modules are the bulk of the adapter's warm pass and
-  // depend on nothing but the scan; hand them over now so the child compiles
-  // them under the client stage instead of after it.
-  warm?.prewarm(routes.filter(route => route.kind === 'page').map(route => route.file))
+  // The page routes' server modules are the bulk of the warm pass and depend on
+  // nothing but the scan; hand them over now so the child compiles them under
+  // the client stage instead of after it.
+  warm.prewarm(routes.filter(route => route.kind === 'page').map(route => route.file))
   // Compat build steps (action discovery/bundling + server-reference manifest)
   // populate their output onto this accumulator. Pure-core registers no steps.
   const buildState: BuildStepState = { actions: [] }
@@ -842,6 +855,12 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
     for (const line of generateRouteLines) console.log(line)
   }
 
+  // A render may intentionally turn an exception into a 500 response so the
+  // dev server can stay alive. During a production build, however, an emitted
+  // module that cannot resolve one of its content-addressed dependencies makes
+  // the output unusable and must remain fatal even after that recovery path.
+  throwIfModuleGraphFailed()
+
   // Fail the build after every route has been given the chance to log its
   // prerender error (matching `prerenderEarlyExit: false`).
   if (hadAfterPrerenderError) {
@@ -926,6 +945,13 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
     await log.step('vercel adapter output', () =>
       writeVercelOutput(config, manifest, { verbose, warm }),
     )
+  // 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))
+
+  // Also cover module loads performed by completion hooks or the warm pass.
+  throwIfModuleGraphFailed()
 
   // Bundling is done; the build metric stops here. Phases that ran alongside it
   // (typecheck) are awaited next and reported on their own lines.
@@ -1068,6 +1094,7 @@ function printBuildSummary(
   // Route table: ○ static, ● SSG (params), ◐ partial prerender, ƒ dynamic.
   console.log('')
   console.log('Route (app)')
+  const usedMarkers = new Set<string>()
   for (const route of routes) {
     const intercepted = interceptionPrerenders.get(route.id)
     const marker =
@@ -1089,15 +1116,29 @@ function printBuildSummary(
     const label = route.interception ? interceptionDisplayRoute(route) : route.route || '/'
     // Next names a dynamic route by its source pattern (`/[dyn]`), not pnext's
     // `:param` form; compat apps' e2e output is matched against Next's.
+    usedMarkers.add(marker)
     console.log(`  ${marker} ${nextCompatEnabled(config) ? toNextRoutePattern(label) : label}`)
   }
   for (const file of staticMetadataSummaryFiles(staticFiles)) {
+    usedMarkers.add('○')
     console.log(`  ${dim('○')} /${file}`)
   }
   if (hasMiddleware) {
+    usedMarkers.add('ƒ')
     console.log('')
     console.log(`  ${dim('ƒ')} Middleware`)
   }
+  const legend: [string, string][] = [
+    ['○', 'static'],
+    ['●', 'SSG'],
+    ['◐', 'partial prerender'],
+    ['ƒ', 'dynamic'],
+  ]
+  const legendLine = legend
+    .filter(([marker]) => usedMarkers.has(marker))
+    .map(([marker, meaning]) => `${marker} ${meaning}`)
+    .join('   ')
+  if (legendLine) console.log(`\n  ${dim(legendLine)}`)
   console.log('')
   console.log(
     `${green('✓')} ${bold('Build complete')} ${dim(`in ${formatBuildDuration(durationMs)}`)}`,

package/src/cli/create.ts

@@ -25,7 +25,7 @@ export async function createApp(dir: string | undefined, options: CreateAppOptio
   }
 
   const name = sanitizePackageName(path.basename(target))
-  console.log(`${cyan('▲')} ${bold('pnext create')} ${dim(`— scaffolding ${name}`)}\n`)
+  console.log(`⚡ ${bold('pnext create')} ${dim(`— scaffolding ${name}`)}\n`)
 
   const files = await scaffoldFiles(name, await latestPnextVersionRange('create'))
   await Promise.all(

package/src/cli/dev.ts

@@ -44,7 +44,8 @@ export async function dev(options: DevOptions = {}) {
   markBoot('dev:config')
   warnDuplicateSass(config.root, Boolean(config.compat?.next))
   const port = options.port ?? 3000
-  const hostname = options.hostname ?? 'localhost'
+  // Next's documented default. Bun resolves 'localhost' to ::1 only, refusing IPv4 clients.
+  const hostname = options.hostname ?? '0.0.0.0'
   // A memory-triggered restart can briefly race the previous listener's
   // shutdown, so give the port a moment to free before failing.
   await ensurePortFree(port, hostname, { attempts: 10 })