@wular/pnext 0.0.2 → 0.0.4

package/reference/performance.md

@@ -1,12 +1,35 @@
 # Performance
 
-Auto-generated by `bun bench` — do not edit by hand.
-
-- Date: 2026-08-17
-- Machine: Darwin 25.6.0 (arm64), Apple M1 x8
-- Bun: 1.3.6
+Measured against Next.js: the same fixture source runs under both frameworks and `bun bench` measures them side by side, on a Blacksmith 4-vCPU CI runner (full machine details below). The ranges below span the fixtures — hello-world, an SSR site, and a mid-size admin dashboard (30 routes, 18 client islands):
+
+|                             |                   pnext vs Next.js |
+| --------------------------- | ---------------------------------: |
+| Dev server ready            |                  **3.8–4.3× faster** |
+| First page, cold            |                    **10–12× faster** |
+| Warm request (dev)          |                  **1.6–4.7× faster** |
+| HMR save → visible          |                       **0.3–2×** ¹ |
+| Production build            |                  **7.2–8.8× faster** |
+| Warm request (prod)         |                    **2–3.4× faster** |
+| Prod server ready           |                  **1.8–2.3× faster** |
+| Dev server memory           |                    **3.4–4.1× less** |
+| Build peak memory           |                      **3–3.7× less** |
+| Framework install size      |   **59× smaller** (7.1 MB vs 421 MB) |
+| First-page client JS (gzip) |                      **9.5–65× less** |
+
+¹ pnext live-reloads (no client HMR runtime; state doesn't survive a save) — the metric
+is save → fresh HTML, which both models support. Scoped invalidation fixed the small
+fixture (21.9 ms, ahead of Next); the larger fixtures still trail on this runner
+(264/300 ms vs 68/98 ms) and the remaining cost is under investigation.
+
+Nothing is prebundled — the dev server compiles what a request needs and caches it content-addressed, which is why readiness doesn't scale with app size. The production server idles at parity with Next (~85–87 MB) while answering warm requests 2–3.4× faster.
+
+The tables below are one full run's absolute numbers, pasted from `bun bench` output (the CI run's `bench-output` artifact carries the same data as `bench.json`).
+
+- Date: 2026-08-20 (actions run 32364720143)
+- Machine: CI — Blacksmith 4 vCPU (Intel Xeon), 16 GB RAM, Ubuntu 22.04 x64
+- Bun: 1.3.10
 - Next.js: 16.2.12
-- Runs per metric: 3 (first discarded), medians reported
+- Runs per metric: 5 (first discarded), medians reported
 
 Every fixture under `bench/fixtures/` runs unmodified on both frameworks, so the
 two columns render the same app from the same source.
@@ -15,19 +38,19 @@ two columns render the same app from the same source.
 
 | Metric | pnext | Next.js | Ratio |
 | --- | --- | --- | --- |
-| Dev cold start (ready) | 98.9 ms | 269.1 ms | 2.72x |
-| Dev first page HTML | 81.7 ms | 1053.6 ms | 12.89x |
-| Dev warm request (p50 of 7) | 2.9 ms | 13.0 ms | 4.54x |
-| Dev server RSS (ready + 7 warm) | 140.4 MB | 585.7 MB | 4.17x |
-| HMR save → visible | 12.4 ms | 40.2 ms | 3.24x |
-| Prod build (wall) | 329.6 ms | 3008.5 ms | 9.13x |
-| Prod build peak RSS | 130.2 MB | 497.1 MB | 3.82x |
-| Prod start (ready) | 122.3 ms | 137.5 ms | 1.12x |
-| Prod warm request (p50 of 7) | 0.6 ms | 1.0 ms | 1.71x |
-| Prod server RSS (ready + 7 warm) | 112.7 MB | 100.6 MB | 0.89x |
-| Framework install size | 6.7 MB | 285.6 MB | 42.43x |
+| Dev cold start (ready) | 56.4 ms | 212.3 ms | 3.76x |
+| Dev first page HTML | 79.9 ms | 993.5 ms | 12.44x |
+| Dev warm request (p50 of 7) | 3.0 ms | 14.0 ms | 4.69x |
+| Dev server RSS (ready + 7 warm) | 130.8 MB | 536.4 MB | 4.10x |
+| HMR save → visible | 21.9 ms | 44.8 ms | 2.04x |
+| Prod build (wall) | 291.3 ms | 2569.4 ms | 8.82x |
+| Prod build peak RSS | 124.2 MB | 455.8 MB | 3.67x |
+| Prod start (ready) | 60.7 ms | 110.9 ms | 1.83x |
+| Prod warm request (p50 of 7) | 0.6 ms | 1.2 ms | 2.05x |
+| Prod server RSS (ready + 7 warm) | 85.2 MB | 85.7 MB | 1.01x |
+| Framework install size | 7.1 MB | 420.7 MB | 59.14x |
 | First-page client JS (raw) | 4.43 KB | 502.47 KB | 113.36x |
-| First-page client JS (gzip) | 2.19 KB | 141.78 KB | 64.73x |
+| First-page client JS (gzip) | 2.19 KB | 141.78 KB | 64.67x |
 | First-page JS files | 3 | 5 | 1.67x |
 | Zero-island route client JS | 4.43 KB | 502.47 KB | 113.36x |
 
@@ -37,19 +60,19 @@ Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
 
 | Metric | pnext | Next.js | Ratio |
 | --- | --- | --- | --- |
-| Dev cold start (ready) | 97.6 ms | 265.3 ms | 2.72x |
-| Dev first page HTML | 105.1 ms | 1179.0 ms | 11.22x |
-| Dev warm request (p50 of 7) | 4.6 ms | 28.2 ms | 6.18x |
-| Dev server RSS (ready + 7 warm) | 164.7 MB | 639.8 MB | 3.89x |
-| HMR save → visible | 22.8 ms | 66.1 ms | 2.90x |
-| Prod build (wall) | 360.0 ms | 3192.1 ms | 8.87x |
-| Prod build peak RSS | 136.1 MB | 511.4 MB | 3.76x |
-| Prod start (ready) | 112.7 ms | 137.7 ms | 1.22x |
-| Prod warm request (p50 of 7) | 0.5 ms | 1.2 ms | 2.24x |
-| Prod server RSS (ready + 7 warm) | 114.0 MB | 100.8 MB | 0.88x |
-| Framework install size | 6.7 MB | 285.6 MB | 42.43x |
-| First-page client JS (raw) | 40.37 KB | 502.78 KB | 12.45x |
-| First-page client JS (gzip) | 16.13 KB | 142.03 KB | 8.80x |
+| Dev cold start (ready) | 56.0 ms | 212.8 ms | 3.80x |
+| Dev first page HTML | 93.5 ms | 1043.3 ms | 11.16x |
+| Dev warm request (p50 of 7) | 16.5 ms | 26.4 ms | 1.60x |
+| Dev server RSS (ready + 7 warm) | 151.3 MB | 553.6 MB | 3.66x |
+| HMR save → visible | 264.3 ms | 68.3 ms | 0.26x |
+| Prod build (wall) | 310.5 ms | 2738.8 ms | 8.82x |
+| Prod build peak RSS | 136.8 MB | 456.6 MB | 3.34x |
+| Prod start (ready) | 57.1 ms | 105.5 ms | 1.85x |
+| Prod warm request (p50 of 7) | 0.5 ms | 1.3 ms | 2.50x |
+| Prod server RSS (ready + 7 warm) | 86.0 MB | 85.9 MB | 1.00x |
+| Framework install size | 7.1 MB | 420.7 MB | 59.14x |
+| First-page client JS (raw) | 27.36 KB | 502.78 KB | 18.37x |
+| First-page client JS (gzip) | 11.39 KB | 142.03 KB | 12.47x |
 | First-page JS files | 4 | 6 | 1.50x |
 | Zero-island route client JS | 4.46 KB | 502.47 KB | 112.56x |
 
@@ -59,20 +82,20 @@ Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
 
 | Metric | pnext | Next.js | Ratio |
 | --- | --- | --- | --- |
-| Dev cold start (ready) | 105.8 ms | 304.9 ms | 2.88x |
-| Dev first page HTML | 170.8 ms | 1323.9 ms | 7.75x |
-| Dev warm request (p50 of 7) | 10.7 ms | 30.7 ms | 2.86x |
-| Dev server RSS (ready + 7 warm) | 186.4 MB | 665.7 MB | 3.57x |
-| HMR save → visible | 71.9 ms | 78.9 ms | 1.10x |
-| Prod build (wall) | 947.2 ms | 4246.6 ms | 4.48x |
-| Prod build peak RSS | 189.0 MB | 608.5 MB | 3.22x |
-| Prod start (ready) | 149.1 ms | 138.7 ms | 0.93x |
-| Prod warm request (p50 of 7) | 1.4 ms | 1.4 ms | 0.96x |
-| Prod server RSS (ready + 7 warm) | 114.8 MB | 105.7 MB | 0.92x |
-| Framework install size | 6.7 MB | 285.6 MB | 42.43x |
-| First-page client JS (raw) | 63.26 KB | 507.42 KB | 8.02x |
-| First-page client JS (gzip) | 23.63 KB | 144.85 KB | 6.13x |
-| First-page JS files | 5 | 9 | 1.80x |
+| Dev cold start (ready) | 57.1 ms | 246.4 ms | 4.31x |
+| Dev first page HTML | 127.0 ms | 1285.8 ms | 10.12x |
+| Dev warm request (p50 of 7) | 21.6 ms | 34.1 ms | 1.58x |
+| Dev server RSS (ready + 7 warm) | 168.6 MB | 577.1 MB | 3.42x |
+| HMR save → visible | 300.4 ms | 97.6 ms | 0.32x |
+| Prod build (wall) | 637.5 ms | 4566.3 ms | 7.16x |
+| Prod build peak RSS | 188.0 MB | 569.0 MB | 3.03x |
+| Prod start (ready) | 55.6 ms | 128.8 ms | 2.32x |
+| Prod warm request (p50 of 7) | 0.5 ms | 1.7 ms | 3.41x |
+| Prod server RSS (ready + 7 warm) | 87.3 MB | 90.6 MB | 1.04x |
+| Framework install size | 7.1 MB | 420.7 MB | 59.14x |
+| First-page client JS (raw) | 38.51 KB | 507.42 KB | 13.18x |
+| First-page client JS (gzip) | 15.26 KB | 144.85 KB | 9.50x |
+| First-page JS files | 6 | 9 | 1.50x |
 
 Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
 
@@ -87,7 +110,7 @@ Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
 
 | Target | Limit | Measured | Status |
 | --- | --- | --- | --- |
-| Dev cold start, ssr fixture (pnext) | <= 150 ms | 97.6 ms | PASS |
+| Dev cold start, ssr fixture (pnext) | <= 100 ms | 56.0 ms | PASS |
 | Router runtime | <= 1.00 KB gzip | 348 B gzip | PASS |
 | Hydrated-route framework tax | <= 5.00 KB gzip | 4.47 KB gzip | PASS |
 | Zero-island route client JS (ssr `/about`) | 0 B (core pnext) | 4.46 KB (compat.next) | not exercised |
@@ -101,7 +124,9 @@ Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
   stops at the readiness banner; first page HTML is the GET that follows it, so it
   includes on-demand compilation.
 - HMR appends a marker to a rendered string in a page component and polls until the
-  page serves it back. A 200 with stale HTML does not count.
+  page serves it back. A 200 with stale HTML does not count. pnext applies the save via
+  live-reload (full document refresh, no client HMR runtime); Next applies it via Fast
+  Refresh. The metric is model-agnostic: time until fresh content is served.
 - Fixtures enable `compat.next` so one source tree runs on both frameworks. That ships
   pnext's Next-compat navigation client, which a core pnext app does not carry — the
   0 B zero-island budget is a core-pnext invariant this suite does not exercise.
@@ -113,7 +138,9 @@ Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
   It is never sampled at an arbitrary time, since RSS is pressure-sensitive.
 - Build peak RSS comes from `/usr/bin/time` wrapping the build process directly (`-l` on
   macOS, `-v` on Linux), not the tree-sum helper — it is the OS-reported peak over the
-  whole build, not a single snapshot.
+  whole build, not a single snapshot. The framework server-entry prebundle is emitted by
+  a short-lived child whose transient RSS (~15–25 MB, returned at exit) this number
+  excludes.
 - Framework install size is each framework's own package cost, not the fixture's total
   `node_modules`, which both frameworks share: `next` + its platform `@next/swc-*` binary,
   or `@wular/pnext`'s npm-publish footprint (its `package.json` "files" list, since this

package/src/api/router/runtime.ts

@@ -437,11 +437,18 @@ async function warmPageAssets(html: string) {
   for (const link of doc.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"][href]')) {
     preloadStylesheet(link.getAttribute('href') ?? '');
   }
+  warmEntryChunks(doc);
+  const entrySrc = entryScriptSrc(doc);
+  if (entrySrc) await importEntry(entrySrc);
+}
+
+// The destination entry's static chunks, kicked off before the entry itself is imported: without
+// this the browser only discovers them after the entry parses, so every chunk the split put behind
+// the entry costs another serial round trip on the navigation's critical path.
+function warmEntryChunks(doc: Document) {
   for (const link of doc.querySelectorAll<HTMLLinkElement>('link[rel="modulepreload"][href]')) {
     preloadModule(link.getAttribute('href') ?? '');
   }
-  const entrySrc = entryScriptSrc(doc);
-  if (entrySrc) await importEntry(entrySrc);
 }
 
 function preloadStylesheet(href: string) {
@@ -3253,40 +3260,66 @@ async function fetchPage(
     }
     if (segmentPayload) {
       segmentCacheKey = segmentDocumentCacheKey(treeResponse, href, options.prefetch!);
-      if (treeResponse.body && !treeResponse.bodyUsed) {
-        treePayload = parseSegmentTreePayload(await treeResponse.text());
-      }
-      // Remember this route's tree so a SIBLING URL of the same route never
-      // asks for it again (Next keys the route tree by route, not by URL).
-      const treeUrl = new URL(href, location.href);
-      learnRouteTree(
-        treeUrl.pathname,
-        treeUrl.search,
-        treePayload?.route,
-        treeResponse.headers.has('x-nextjs-rewritten-path') ||
-          treeResponse.headers.has('x-nextjs-rewritten-query'),
-      );
+      // The tree PAYLOAD is only bookkeeping (route learning, headFirst): read it
+      // without blocking the segment phase, so the body request goes on the wire in
+      // the same task the tree HEADERS resolve in — before the tree body's own
+      // stream-close task, where a harness batch (router-act) may already drain.
+      const treeText =
+        treeResponse.body && !treeResponse.bodyUsed ? treeResponse.text() : null;
+      const finishTree = async () => {
+        if (treeText) treePayload = parseSegmentTreePayload(await treeText);
+        // Remember this route's tree so a SIBLING URL of the same route never
+        // asks for it again (Next keys the route tree by route, not by URL).
+        const treeUrl = new URL(href, location.href);
+        learnRouteTree(
+          treeUrl.pathname,
+          treeUrl.search,
+          treePayload?.route,
+          treeResponse.headers.has('x-nextjs-rewritten-path') ||
+            treeResponse.headers.has('x-nextjs-rewritten-query'),
+        );
+      };
       releaseSlot();
       const cached = getSegmentDocument(segmentCacheKey, href, options.prefetch!);
-      if (cached) return cached;
+      if (cached) {
+        await finishTree();
+        return cached;
+      }
       // The link left the viewport while the tree was in flight: stop before
       // the segment phase (the in-flight tree request is never aborted, but no
       // follow-up request may be issued — Next's cancellation contract).
-      if (task?.cancelled) return null;
-      if (needsOutlinedHeadFirst(href, treePayload?.headFirst === true)) {
+      if (task?.cancelled) {
+        await finishTree();
+        return null;
+      }
+      // Head-before-body order is preserved: the tree response HEADERS announce
+      // outlining (x-pnext-head-outlined), so no tree-body read is needed here.
+      const treeHeadOutlined = treeResponse.headers.get('x-pnext-head-outlined');
+      if (needsOutlinedHeadFirst(href, treeHeadOutlined === 'first')) {
+        await finishTree();
         outlinedHeadHtml = await fetchOutlinedHead(href, init, headers, rscVariant);
       }
       const covered = segmentBodyCovered(href, options.prefetch);
-      if (covered) return withOutlinedHead(covered, outlinedHeadHtml);
+      if (covered) {
+        await finishTree();
+        return withOutlinedHead(covered, outlinedHeadHtml);
+      }
       bodySegment = prefetchBodySegmentPath(href);
       headers[SEGMENT_PREFETCH_HEADER] = bodySegment;
       requestHref = withRscQuery(href, `${rscVariant}:${bodySegment}`);
-      if (!(await acquireSlot(PREFETCH_PHASE_SEGMENT))) return null;
-      response = await fetchWithRedirectReplay(
+      if (!(await acquireSlot(PREFETCH_PHASE_SEGMENT))) {
+        await finishTree();
+        return null;
+      }
+      const bodyPromise = fetchWithRedirectReplay(
         requestHref,
         init,
         `${rscVariant}:${bodySegment}`,
       );
+      // A rejection before the await below must not surface as unhandled.
+      bodyPromise.catch(() => undefined);
+      await finishTree();
+      response = await bodyPromise;
     } else {
       response = treeResponse;
     }
@@ -4029,6 +4062,11 @@ async function pageForNavigation(
     // prerendered document for the SAME pathname is already cached: a static prerender never
     // rendered search params server-side, so only the client-visible URL differs.
     if (!cached.settled) {
+      // Same principle for a networkFree per-segment hit: it commits with zero
+      // network, so waiting out the in-flight prefetch would be pure latency.
+      if (segmentHit?.networkFree && !slotStateSensitive(departureNavState, segmentHit.html)) {
+        return { html: segmentHit.html, finalUrl: url.href, ok: true };
+      }
       const shared = await samePathnamePrerenderedPage(url, now, departureNavState);
       if (shared) return shared;
     }
@@ -4676,6 +4714,7 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // Warm the new document's assets before touching the current one: the swap
   // then paints styled content immediately instead of flashing unstyled HTML.
   const entrySrc = entryScriptSrc(doc);
+  warmEntryChunks(doc);
   const [entryModule] = await Promise.all([
     entrySrc ? importEntry(entrySrc) : Promise.resolve(null),
     addStylesheets(doc),

package/src/cache/context.ts

@@ -22,7 +22,10 @@ export interface CacheScope {
   controller?: AbortController;
 }
 
-const storage = new AsyncLocalStorage<CacheScope>();
+// globalThis-anchored: the prebundled server entry inlines its own copy of this module.
+const CACHE_SCOPE_STORAGE = Symbol.for('pnext.cacheScopeStorage');
+const storage = ((globalThis as Record<PropertyKey, unknown>)[CACHE_SCOPE_STORAGE] ??=
+  new AsyncLocalStorage<CacheScope>()) as AsyncLocalStorage<CacheScope>;
 
 export function currentCacheScope() {
   return storage.getStore();

package/src/cli/build.ts

@@ -1,11 +1,11 @@
 import { copyFile, mkdir, rename, writeFile } from 'node:fs/promises';
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
 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 { loadConfig, pathToFileHref } from '../config';
+import { devOutSegment, loadConfig, pathToFileHref } from '../config';
 import { bootstrapCompat } from '../compat-bootstrap';
 import {
   buildParallelPhaseError,
@@ -100,6 +100,9 @@ interface BuildStepState {
   /** Root-relative 'use server' module paths — known from discovery, so the
    * client stage keys off this instead of waiting for their compile. */
   actionSources?: string[];
+  /** First-party files that import a node_modules action module (absolute paths) — see
+   * ActionDiscovery.actionImporters; route.sourceFiles never reaches into node_modules itself. */
+  actionImporters?: string[];
   /** Work a step handed back rather than finishing inline; awaited before the
    * build manifest is written, so it lands under the client stage. */
   deferred?: Promise<void>;
@@ -192,9 +195,20 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
   // adapter step.
   const warm = options.adapter === 'vercel' ? startWarmChild(config) : undefined;
   await log.step('prepare output directory', async () => {
-    await ensureEmptyDir(config.outPath);
+    // Build-owned outputs only: `<outRoot>/dev` belongs to a possibly-running
+    // dev server and must survive.
+    await ensureEmptyDir(config.outPath, [devOutSegment]);
     await copyPublicDir(config.publicPath, path.join(config.outPath, 'public'));
   });
+  // Prebundled server entry for `pnext start`: framework-only, independent of the
+  // app build, so it runs in a child process for the whole build — its bundling
+  // heap never stacks on the build's peak RSS and its wall hides under the build.
+  // Best-effort — a failure only costs start time. Awaited before the summary.
+  const serverEntryDone = import('./server-entry')
+    .then(entry => entry.emitServerEntryChild(config.outPath))
+    .catch((error: Error) => {
+      console.warn(`pnext build: server entry bundling skipped — ${error.message}`);
+    });
   // The document-level stylesheets run their postcss/Tailwind pass on the CSS
   // worker, so they overlap with the route scan below instead of serializing
   // ahead of it. Awaited before prepareRouteCssChunks — route CSS still builds
@@ -321,11 +335,19 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
   );
 
   const actionSources = buildState.actionSources ?? buildState.actions.map(a => a.sourceKey);
-  const actionFiles = new Set(actionSources.map(source => path.resolve(config.root, source)));
+  // realpath, not resolve: a hybrid app's routes are scanned through the pages-compat mirror, whose
+  // `source-app` is a symlink to the real app dir - the two spellings of one file must compare equal.
+  const actionFiles = new Set(actionSources.map(source => realFilePath(path.resolve(config.root, source))));
+  // A node_modules action module never lands in route.sourceFiles itself (that walk stops at the
+  // package boundary), so a route reaching one only through a first-party importer is matched here.
+  const actionImporters = new Set((buildState.actionImporters ?? []).map(realFilePath));
   for (const route of routes) {
     if (
       route.kind === 'page' &&
-      route.sourceFiles.some(file => actionFiles.has(path.resolve(file)))
+      route.sourceFiles.some(file => {
+        const real = realFilePath(file);
+        return actionFiles.has(real) || actionImporters.has(real);
+      })
     ) {
       addClientEntryReason(route, 'actions');
     }
@@ -873,6 +895,7 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
   };
   await writeBuildManifest(config.outPath, manifest);
   log.log(`wrote manifest.json (${routes.length} route${routes.length === 1 ? '' : 's'})`);
+  await log.step('server entry', () => serverEntryDone);
   for (const hook of getBuildExtensions().completeHooks) {
     await hook({ config, manifest, log });
   }
@@ -3055,6 +3078,15 @@ function isAfterPrerenderError(error: unknown): boolean {
   );
 }
 
+/** Symlink-resolved path, for comparing two spellings of one file. Missing files keep their path. */
+function realFilePath(file: string): string {
+  try {
+    return realpathSync.native(file);
+  } catch {
+    return path.resolve(file);
+  }
+}
+
 function safePublicPath(outPath: string, ...segments: string[]) {
   const publicPath = path.join(outPath, 'public');
   const file = path.join(publicPath, ...segments);

package/src/cli/dev.ts

@@ -57,6 +57,12 @@ export async function dev(options: DevOptions = {}) {
   const url = `http://${browserHost(hostname)}:${server.port ?? port}`;
   printServerReady({ mode: 'dev', hostname, port: server.port ?? port, elapsedMs });
   printBootTrace();
+  // Boot compiles nothing (config loads natively), so the first compile would pay esbuild's service
+  // spawn. Warm it here, after the banner - readiness must not wait on it. PNEXT_DEV_ESBUILD_WARM=0 opts out.
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  if (process.env.PNEXT_DEV_ESBUILD_WARM !== '0') {
+    void import('../utils/esbuild').then(module => module.warmEsbuildService());
+  }
   registerShutdown(server);
   watchServerMemory(server);
   watchStaleModules(server);

package/src/cli/index.ts

@@ -33,15 +33,26 @@ try {
       buildMode: buildModeOption(args),
       debugPrerender: args.includes('--debug-prerender'),
     });
+    // A live CSS worker thread races Bun's exit teardown (Linux: silent exit 1
+    // after a successful build); stop it before force-exiting.
+    await (await import('../css/build')).stopCssWorker();
     // Nothing here keeps the event loop alive on success, but a project's
     // next.config can (e.g. a stray setInterval) and Next's own `next build`
     // force-exits regardless of such handles. Do the same so `build` always
     // terminates once buildProject resolves.
     process.exit(0);
   } else if (command === 'start') {
-    const { start } = await import('./start');
+    const root = positionalRoot(args);
+    // The build emits src/cli/start.ts prebundled into one file; parsing that
+    // instead of walking the framework's source graph is most of `start`'s
+    // spawn→first-200. Absent (no build yet, custom outDir) → source path.
+    const { prebuiltServerEntry } = await import('./server-entry');
+    const prebuilt = prebuiltServerEntry(root);
+    const { start } = prebuilt
+      ? ((await import(prebuilt)) as typeof import('./start'))
+      : await import('./start');
     await start({
-      root: positionalRoot(args),
+      root,
       port: optionNumber(args, '--port'),
       hostname: optionString(args, '--hostname'),
     });
@@ -81,7 +92,10 @@ try {
   }
 } catch (error) {
   const formatted = formatCliError(error);
-  console.error(formatted.message);
+  // A blank formatted message exits 1 with no explanation; fall back to the
+  // raw error so the failure is never silent.
+  if (formatted.message.trim()) console.error(formatted.message);
+  else console.error(error instanceof Error ? (error.stack ?? `${error.name}: ${error.message}`) : String(error));
   if (formatted.trace) console.log(`\n${formatted.trace}`);
   process.exit(1);
 }