@rsc-kit/core 0.17.0 → 0.18.1

package/dist/vite.js

@@ -27,7 +27,9 @@ import { ASSET_BASE, allAppAssets, appAssets, headTags, typeOf, } from "./appAss
 import { reactCacheImports } from "./reactCache.js";
 import { clientEntries, clientScanPlugin, engineClientEntries, } from "./clientEntries.js";
 import { serverImportsOfClientPackages } from "./clientImports.js";
-import { METADATA_ROUTES, ROOT_FILES, rootFileType } from "./metadataRoutes.js";
+import { automaticSitemap, METADATA_ROUTES, ROOT_FILES, rootFileType, } from "./metadataRoutes.js";
+import { ownHosts } from "./hostRouting.js";
+import { unrollBarrelImports } from "./barrelImports.js";
 import { serverRendererMessage, SERVER_RENDERER, ssrProxyModule, UseSsrError, } from "./useSsr.js";
 import { httpHostCalls } from "./hostCalls.js";
 // Resolved once per rscKit() call. One build runs in one process, so these are
@@ -40,6 +42,47 @@ let resolvedConfig = null;
 let clientLibraryImports = [];
 /** Modules a runtime provides and no bundle should try to carry. */
 const RUNTIME_BUILTINS = ["bun", /^bun:/];
+/**
+ * Packages the server bundles import rather than inline, by default.
+ *
+ * Each of these ships a native binary, spawns one, or reads files relative to
+ * its own location - none of which survives being rolled into a bundle. Left
+ * external, Nitro traces them into .output/server/node_modules with their
+ * binaries, and the built server imports them the way the package expects.
+ * Next keeps the same list under serverExternalPackages, for the same reason.
+ * `rscKit({ serverExternalPackages })` adds to it.
+ */
+const DEFAULT_SERVER_EXTERNALS = [
+    "sharp",
+    "canvas",
+    "bcrypt",
+    "argon2",
+    "@node-rs/argon2",
+    "@node-rs/bcrypt",
+    "better-sqlite3",
+    "sqlite3",
+    "libsql",
+    "@libsql/client",
+    "@prisma/client",
+    "prisma",
+    "puppeteer",
+    "puppeteer-core",
+    "playwright",
+    "playwright-core",
+    "jsdom",
+    "node-pty",
+    "onnxruntime-node",
+    "@sentry/profiling-node",
+    "pdfkit",
+    "mongodb",
+    "oslo",
+    "@resvg/resvg-js",
+    "@napi-rs/canvas",
+];
+/** A package name as a rollup external: the package and every subpath of it. */
+function externalPackage(name) {
+    return new RegExp("^" + name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "(?:/|$)");
+}
 function arrayOf(value) {
     return value == null ? [] : Array.isArray(value) ? value : [value];
 }
@@ -108,6 +151,11 @@ let isWatch = false;
 let offline = false;
 let typecheck = true;
 let webManifestOptions = null;
+/** The site's own hosts, from the root layout's metadataBase and rscKit({ hosts }). */
+let siteHosts = [];
+let hostsOption = [];
+let barrelImports = true;
+let identify = true;
 let foundAssets = {
     favicon: null,
     icons: [],
@@ -270,6 +318,9 @@ function resolvePaths(options) {
     prerenderAfterBuild = process.env.RSC_PRERENDER !== "0";
     offline = options.offline === true;
     typecheck = options.typecheck !== false;
+    hostsOption = options.hosts ?? [];
+    barrelImports = options.barrelImports !== false;
+    identify = options.identify !== false;
     inlineStylesheets = options.inlineStylesheets ?? "auto";
     maxActionBody = options.maxActionBody;
     // One place, and it is the file. A plugin option as well would be the same
@@ -323,7 +374,12 @@ function urlSegments(componentName) {
             continue;
         }
         if (part.startsWith("[") && part.endsWith("]")) {
-            segments.push({ type: "param", value: part.slice(1, -1) });
+            // At the top of app/ - the first segment the url has - a parameter is
+            // the host's: bound from acme.example.com, never from example.com/acme.
+            segments.push({
+                type: segments.length === 0 ? "host" : "param",
+                value: part.slice(1, -1),
+            });
             continue;
         }
         // An interception marker says which url this replaces, not what it is
@@ -395,7 +451,11 @@ function routeManifest() {
      * to whoever knows what they mean.
      */
     const middlewareIn = (absDir) => {
-        for (const file of ["route.ts", "route.tsx"]) {
+        // middleware.ts first: it is the file named for what this is. A guard
+        // the engine runs is its default export; the names a host runs are its
+        // `middleware` export, and a file may carry either or both. route.ts is
+        // read too, for the apps written before middleware.ts could.
+        for (const file of ["middleware.ts", "middleware.tsx", "route.ts", "route.tsx"]) {
             const path = join(absDir, file);
             if (!existsSync(path))
                 continue;
@@ -481,7 +541,13 @@ function routeManifest() {
     // writing the site out, and knowing which filename the client will ask for.
     return {
         version: 1,
-        build: { output, exportPath, payloadName: staticPayloads },
+        build: {
+            output,
+            exportPath,
+            payloadName: staticPayloads,
+            hosts: siteHosts,
+            identify,
+        },
         routes,
         intercepts,
         apis: [...apiRoutes.values()].map(({ name, methods, generated }) => ({
@@ -1236,6 +1302,41 @@ async function prerenderAfterBundles(bundle, staticDir, assetsDir, knownActions
     // places to look for one fact.
     const manifest = engine.manifest();
     const apis = await prerenderApiRoutes(engine, manifest, writeTo(staticDir));
+    // A sitemap the build writes itself, when the app wrote none: every url
+    // it stored or was told about, minus the guarded ones. It needs the site's
+    // host, which the root layout's metadataBase is for; without one there is
+    // nothing to write and the report says so once.
+    const writesSitemap = manifest.apis?.some((api) => api.name === "app/sitemap.xml/route");
+    const hasSitemapFile = rootFiles.includes("sitemap.xml");
+    if (!writesSitemap && !hasSitemapFile) {
+        const base = rootMetadataBase(join(sourceDir, "app"));
+        if (base) {
+            const xml = automaticSitemap(results, manifest.routes, base);
+            const stored = JSON.stringify({
+                status: 200,
+                headers: [["content-type", "application/xml; charset=utf-8"]],
+                body: xml,
+                varies: false,
+            });
+            await writeTo(staticDir)("sitemap.xml.api.json", stored);
+            pending.push({
+                line: "  ○  /sitemap.xml",
+                bytes: null,
+                extra: [
+                    `     written by the build: ${xml.split("<url>").length - 1} urls; a sitemap.ts beside the root layout replaces it`,
+                ],
+            });
+        }
+        else {
+            pending.push({
+                line: "  -  /sitemap.xml",
+                bytes: null,
+                extra: [
+                    "     not written: the root layout has no metadataBase to make the urls absolute",
+                ],
+            });
+        }
+    }
     for (const api of apis) {
         pending.push({
             line: `  ${api.type === "frozen" ? "○" : "ƒ"}  ${api.url}`,
@@ -1480,6 +1581,23 @@ function renderRouteTypes(manifest) {
         const target = relative(typesDir, join(sourceDir, route.component)).replace(/\\/g, "/");
         search.set(pattern, target.startsWith(".") ? target : "./" + target);
     }
+    // Section names are read from the source - section('orders', …) - the way
+    // generateStaticParams is detected, because this runs before any bundle
+    // exists. A name computed at runtime is not seen and revalidate() falls
+    // back to refusing it at the renderer, as before.
+    const regions = [
+        ...new Set([
+            ...[...components.values()]
+                .filter((c) => SECTION_FILE.test(c.absPath))
+                .flatMap((c) => [
+                ...readFileSync(c.absPath, "utf-8").matchAll(/\bsection\(\s*['"`]([^'"`]+)['"`]/g),
+            ].map((m) => m[1])),
+            ...[...components.keys()].flatMap((name) => {
+                const slot = name.split("/").find((part) => part.startsWith("@"));
+                return slot ? [slot.slice(1)] : [];
+            }),
+        ]),
+    ].sort();
     return [
         "// @generated — do not edit. Written by the RSC build from the route tree.",
         "//",
@@ -1513,6 +1631,14 @@ function renderRouteTypes(manifest) {
         // Api routes are a separate union, so Link refuses an api url and apiUrl()
         // refuses a page. Linking to an api route navigates the browser away to a
         // json document, which is the mistake worth catching.
+        // Regions: every section('name', …) the build read, and every @slot
+        // directory. This is what types revalidate().
+        "  interface RegisterRegions {",
+        regions.length > 0
+            ? "    regions:\n" +
+                regions.map((r) => "      | " + JSON.stringify(r)).join("\n")
+            : "    // No sections or slots found under the source directory.\n    regions: never",
+        "  }",
         "  interface RegisterApi {",
         apis.length > 0
             ? "    apis:\n" +
@@ -1714,10 +1840,20 @@ function registerApiRoute(absPath) {
     }
     apiRoutes.set(name, { name, absPath, methods });
 }
+/**
+ * Whether a middleware.ts is a guard the engine runs, or only names guards
+ * the host runs. The engine imports a guard's default export; a file with
+ * none - `export const middleware = ['auth']` and nothing else - has nothing
+ * to import, and registering it would make the build fail on an export that
+ * was never meant to exist.
+ */
+function isEngineGuard(absPath) {
+    return /export\s+default\b/.test(readFileSync(absPath, "utf-8"));
+}
 function discover(dir) {
     for (const base of ROUTE_FILES) {
         const p = findRouteFile(dir, base);
-        if (p)
+        if (p && (base !== "middleware" || isEngineGuard(p)))
             register(p);
     }
     // route.ts — an api endpoint, colocated with the pages it sits among. Read
@@ -1748,6 +1884,21 @@ function discover(dir) {
  * pages export only the static object, so referencing both meant that warning
  * for almost every route in an app.
  */
+/**
+ * The root layout's metadataBase, read from the source. Wanted while the
+ * manifest is built, before there is a bundle to execute - the same reason
+ * generateStaticParams is detected by reading. A `new URL('…')` or a string
+ * literal; anything computed is not seen, and rscKit({ hosts }) says it.
+ */
+function rootMetadataBase(appDir) {
+    const layout = ["layout.tsx", "layout.jsx", "layout.ts", "layout.js"]
+        .map((name) => join(appDir, name))
+        .find((file) => existsSync(file));
+    if (!layout)
+        return null;
+    const match = /metadataBase\s*:\s*(?:new\s+URL\(\s*)?["'`](https?:\/\/[^"'`]+)["'`]/.exec(readFileSync(layout, "utf-8"));
+    return match ? match[1] : null;
+}
 function metadataExports(absPath) {
     const src = readFileSync(absPath, "utf-8");
     return {
@@ -1942,7 +2093,36 @@ function installHostCallsOnce(): void {
 }
 
 `;
+/**
+ * The app's process bootstrap, if it has one: `instrumentation.ts` beside
+ * `app/`, the name Next uses so a reader arriving from there knows what it
+ * is.
+ *
+ * Two things make it a framework concern rather than an import the app
+ * adds. Module evaluation order: a page that configures a shared package at
+ * import time runs before any module the app could put first, and only the
+ * generated entry can import something before the pages. And "before the
+ * first request": an async `register()` — connecting, validating env — has
+ * to be awaited by every entry point a host or a prerender can call, which
+ * is a list the app cannot see.
+ */
+function instrumentationFile() {
+    for (const ext of ["ts", "tsx", "mts", "js", "mjs"]) {
+        const file = join(sourceDir, `instrumentation.${ext}`);
+        if (!existsSync(file))
+            continue;
+        // Both halves are optional: a file of imports is a bootstrap, a file
+        // with register() is a hook. The entry must only name `register` when it
+        // exists - a namespace import's missing member is a bundler warning on
+        // every build (IMPORT_IS_UNDEFINED), which is the app being told off for
+        // a file written exactly as documented.
+        const hasRegister = /export\s+(?:async\s+)?(?:function\s+register\b|const\s+register\b|let\s+register\b|\{[^}]*\bregister\b[^}]*\})/.test(readFileSync(file, "utf-8"));
+        return { file, hasRegister };
+    }
+    return null;
+}
 function generateEntryRsc(fallbackOrigin = "") {
+    const instrumentation = instrumentationFile();
     // The 404 page, if the app has one, and the layouts it renders inside.
     // Computed here rather than looked up at runtime: not-found is not a route,
     // so the manifest has no entry to read its chain from.
@@ -1999,12 +2179,23 @@ function generateEntryRsc(fallbackOrigin = "") {
     // from src/ in its own repo and from dist/ once published, and Vite resolves
     // either. Naming .tsx here builds fine from source and fails after publish.
     return `// GENERATED by rscKit() — do not edit.
+${
+    // First, before any page: an import's side effects run in import order,
+    // and a package configured here has to be configured before a page module
+    // that reads it at evaluation time.
+    instrumentation?.hasRegister
+        ? `import * as __instrumentation from ${JSON.stringify(instrumentation.file)}`
+        : instrumentation
+            ? `import ${JSON.stringify(instrumentation.file)}\nconst __instrumentation: { register?: () => unknown } = {}`
+            : "const __instrumentation: { register?: () => unknown } = {}"}
 import { SegmentBoundary } from ${JSON.stringify(join(packageDir, "js/SegmentBoundary"))}
+import { LoadingBoundary } from ${JSON.stringify(join(packageDir, "js/LoadingBoundary"))}
 import { DocumentTitle } from ${JSON.stringify(join(packageDir, "js/DocumentTitle"))}
 import { SlotBoundary } from ${JSON.stringify(join(packageDir, "js/SlotBoundary"))}
 import { RouteErrorBoundary } from ${JSON.stringify(join(packageDir, "js/RouteErrorBoundary"))}
 import { sectionComponent } from ${JSON.stringify(join(packageDir, "js/section"))}
 import { PathnameProvider } from ${JSON.stringify(join(packageDir, "js/PathnameProvider"))}
+import { DefaultRouteError } from ${JSON.stringify(join(packageDir, "js/DefaultRouteError"))}
 import { searchParams as requestSearchParams } from ${JSON.stringify(join(packageDir, "request"))}
 import { parseParams, parseSearchParams, parseBody, isSearchParamsError, isBodyError } from ${JSON.stringify(join(packageDir, "routeSchema"))}
 import { notFoundDigest, isNotFoundSignal } from ${JSON.stringify(join(packageDir, "notFound"))}
@@ -2144,6 +2335,7 @@ export async function handleApiRoute(
   params: Record<string, string>,
   allow: string,
 ): Promise<Response> {
+  await instrumented()
   applyHost()
 
   const mod = apiRoutes[name]
@@ -2251,6 +2443,8 @@ export async function auditActions(ids: string[]): Promise<{ id: string; client:
  * that asked for everything, or the reverse.
  */
 export async function getStaticParams(component: string): Promise<Record<string, string>[] | null> {
+  await instrumented()
+
   const generate = staticParamsMap[component]
 
   if (!generate) return null
@@ -2274,6 +2468,57 @@ const HOST_GLOBAL = ${JSON.stringify(hostGlobal)}
  */
 const HOST_MIDDLEWARE_FN = '__rsc.middleware'
 
+/**
+ * instrumentation.ts's register(), once.
+ *
+ * On a long-lived server it runs at startup: the entry is evaluated when the
+ * process starts, and this begins then, so env that fails validation fails
+ * the boot rather than the first visitor, and the first request does not
+ * pay for it. On a Worker there is no startup — an isolate is created for a
+ * request, and a binding is only readable once one has arrived — so it runs
+ * at the first request of each isolate instead. Every entry point awaits it
+ * either way, which is what makes "before the first render" hold whether the
+ * caller is the built server, the dev server or the prerender.
+ *
+ * A rejection is not memoised. Env that fails validation fails the same way
+ * on every request, which is right; a database that was not up yet gets
+ * asked again rather than leaving the process permanently refusing. In
+ * production a startup failure is reported and the process exits, because a
+ * server that could not bootstrap has nothing correct to serve; the dev
+ * server stays up and reports it on the page instead.
+ */
+let __instrumented: Promise<void> | null = null
+
+function instrumented(): Promise<void> {
+  if (!__instrumented) {
+    __instrumented = Promise.resolve()
+      .then(() => __instrumentation.register?.())
+      .then(
+        () => undefined,
+        (error) => {
+          __instrumented = null
+          throw error
+        },
+      )
+  }
+
+  return __instrumented
+}
+
+// Workers name themselves; nothing else does. Where there is a process to
+// start, start now.
+const isolateRuntime = typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers'
+
+if (__instrumentation.register && !isolateRuntime) {
+  instrumented().catch((error) => {
+    console.error('[rsc-kit] instrumentation.ts register() failed:', error)
+
+    if (!import.meta.env.DEV && typeof process !== 'undefined' && typeof process.exit === 'function') {
+      process.exit(1)
+    }
+  })
+}
+
 let currentHost: HostFn | null = null
 
 export function installHostFn(fn: HostFn) {
@@ -2481,9 +2726,17 @@ function buildElement(
     searchParams: checkedSearchParams(schemas, pageSearchParams()),
   })
 
+  // Through LoadingBoundary when the runtime is shipped, so a server render
+  // can tell the engine's boundary from one the developer wrote by name -
+  // see that file. A page shipping no runtime gets a plain Suspense: a
+  // client component would drag React in for a wrapper nothing can use.
   for (let i = loadings.length - 1; i >= 0; i--) {
     const Loading = components[loadings[i]]
-    element = createElement(Suspense, { fallback: Loading ? createElement(Loading) : null }, element)
+    const fallback = Loading ? createElement(Loading) : null
+
+    element = bootstrap
+      ? createElement(LoadingBoundary, { fallback }, element)
+      : createElement(Suspense, { fallback }, element)
   }
 
   // Outside the Suspense boundary, innermost first — the nearest error.tsx to
@@ -2507,6 +2760,19 @@ function buildElement(
     )
   }
 
+  // Outermost, for a throw no error.tsx covers - including one in a layout,
+  // which the boundary inside that layout cannot see. Without it React
+  // unmounted the document on hydration: a black page with the cause nowhere
+  // near it. Only with the runtime: it is a client component, and a route
+  // shipping none has nothing to catch with.
+  if (bootstrap) {
+    element = createElement(
+      RouteErrorBoundary,
+      { fallback: DefaultRouteError as never, resetKey: pageKey || component },
+      element,
+    )
+  }
+
   // <title>/<meta> go OUTSIDE the Suspense boundaries so they reach the shell
   // immediately — inside, they would be withheld until the page's data
   // resolves, delaying the whole document on a slow page.
@@ -2660,6 +2926,8 @@ async function renderTree(
       if (bootstrap) head.push(createElement(DocumentTitle, { key: '__ts', title: String(md.title) }))
     }
     if (md.description != null) head.push(createElement('meta', { key: '__d', name: 'description', content: String(md.description) }))
+    // The name only, never the version - see the identify option.
+    if (manifest().build?.identify) head.push(createElement('meta', { key: '__g', name: 'generator', content: 'rsc-kit' }))
 
     // robots is a string, or the object Next takes: index and follow as
     // their no- forms, the flags by name, the limits as name:value. googleBot
@@ -2961,6 +3229,7 @@ async function runMiddleware(component: string, props: Record<string, unknown> =
  * throws, exactly as it does mid-render.
  */
 export async function runRouteMiddleware(component: string, props: Record<string, unknown> = {}): Promise<void> {
+  await instrumented()
   applyHost()
 
   return runMiddleware(component, props)
@@ -2976,6 +3245,7 @@ export async function handleRscStream(
   from = 0,
   pageKey = '',
 ): Promise<{ stream: ReadableStream; clientChunks: unknown; segmentDepth: number }> {
+  await instrumented()
   applyHost()
 
   // The host proposes how much the client already has; the engine decides what
@@ -3031,6 +3301,7 @@ export async function handleRscHtmlStream(
   pageKey = '',
   bootstrap = true,
 ): Promise<{ htmlStream: ReadableStream; rscPayloadPromise: Promise<string>; clientChunks: unknown }> {
+  await instrumented()
   applyHost()
   await runMiddleware(component, props)
   const flight = renderToReadableStream(
@@ -3066,6 +3337,7 @@ export async function handleRscResume(
   nonce?: string,
   pageKey = '',
 ): Promise<{ htmlStream: ReadableStream }> {
+  await instrumented()
   applyHost()
   await runMiddleware(component, props)
 
@@ -3216,6 +3488,7 @@ export async function handleQuery(
   | { status: number; message: string; errors?: Record<string, string[]> }
   | null
 > {
+  await instrumented()
   applyHost()
 
   let fn: unknown
@@ -3264,6 +3537,7 @@ export async function handleAction(
   page?: PageContext,
   takeRevalidated?: () => string[],
 ): Promise<{ stream: ReadableStream }> {
+  await instrumented()
   applyHost()
 
   // Every body arrives as bytes on its own socket frame — an upload because it
@@ -3356,6 +3630,8 @@ export async function resolveMetadata(
   props: Record<string, unknown> = {},
   layouts: LayoutEntry[] = [],
 ): Promise<Record<string, unknown> | null> {
+  await instrumented()
+
   const pageEntry = metadataMap[component]
   const page: Record<string, unknown> = pageEntry
     ? (pageEntry.generate
@@ -3425,6 +3701,7 @@ export async function handleRsc(
   bootstrap = true,
   canReachHost = true,
 ): Promise<{ body: string; rscPayload: string; clientChunks: unknown; usedDynamicApis: boolean; dynamicBecause: string[]; clientComponents: string[]; serverReferences: boolean }> {
+  await instrumented()
   applyHost()
 
   // A build renders this with no host installed, so every rpc() has to suspend
@@ -3538,6 +3815,7 @@ export async function handleRscRevalidate(
   target: string,
   page: PageContext,
 ): Promise<{ rscPayload: string }> {
+  await instrumented()
   applyHost()
 
   const flight = renderToReadableStream(await renderRevalidated(target, page))
@@ -3554,6 +3832,7 @@ export async function handleRscPayload(
   from = 0,
   pageKey = '',
 ): Promise<{ rscPayload: string }> {
+  await instrumented()
   applyHost()
 
   const flight = renderToReadableStream(
@@ -3621,6 +3900,7 @@ export async function handleRscPprShell(
   // and make every guarded route dynamic for the wrong reason.
   let usedDynamicApis = false
 
+  await instrumented()
   applyHost()
 
   const probe = (..._args: unknown[]) => {
@@ -3790,6 +4070,17 @@ export default async function handler(request: Request): Promise<Response> {
 }
 
 async function serve(request: Request): Promise<Response> {
+  // The startup plugin's probe. Nitro loads this module at the first request
+  // rather than when the server starts, so a plugin that runs at startup
+  // sends one request to load it; the module's evaluation began register(),
+  // and this waits for it so a failure is reported as the startup failure it
+  // is. No page is rendered and nothing is disclosed.
+  if (request.headers.get('x-rsc-kit-startup') !== null) {
+    await instrumented()
+
+    return new Response(null, { status: 204 })
+  }
+
   installHostCallsOnce()
 
   devHandler ??= createRscHandler({
@@ -3924,35 +4215,7 @@ export async function handleSsr(
   const html = await renderToReadableStream(root as any, {
     bootstrapScriptContent,
     nonce,
-    // The query-string fallback is the designed path for a stored page, and
-    // its digest is what lets the client tell it from a fault on hydration;
-    // returned here so React writes it into the document.
-    onError: onError ?? ((error: unknown, info?: { componentStack?: string }) => {
-      // The consumer cancelled - a browser that left mid-stream, a prefetch
-      // abandoned. React reports it as an error; the page had none.
-      if (cancelledByConsumer(error)) return
-      const digest = (error as { digest?: string } | null)?.digest
-      if (digest === 'rsc-kit:search-params-fallback') {
-        // The component is the first frame of React's stack. Noted on the
-        // request so the build attaches it to the route; printed as one line,
-        // not a stack, so the dev server says which boundary the build wants.
-        const where = /at ([A-Z][\\w$]*)/.exec(info?.componentStack ?? '')?.[1]
-        noteFallback('useSearchParams()' + (where ? ' in ' + where : ''))
-        // Under a boundary the developer wrote, nothing to say. With nothing
-        // closer than a loading.tsx, one line: the whole segment is the
-        // fallback until the query arrives.
-        if (caughtByLoading(info?.componentStack)) {
-          console.error(
-            '[rsc-kit] ' + (where ? where + ': ' : '') +
-            'useSearchParams() was read on the server with nothing closer than a loading.tsx, so the whole ' +
-            'segment shows that fallback until the query arrives. A <Suspense> around the component that reads ' +
-            'keeps the rest of the page painted.',
-          )
-        }
-        return digest
-      }
-      console.error('[rsc-kit:ssr]', error)
-    }),
+    onError: onError ?? reportRenderError('ssr'),
   })
 
   return DEV_ORIGIN ? rewriteViteDevUrlStream(html, DEV_ORIGIN) : html
@@ -4004,6 +4267,46 @@ export async function handleSsrPrerender(
   }
 }
 
+/**
+ * What a server render says about an error, first render and resume alike.
+ *
+ * The query-string fallback is the designed path for a stored page, and its
+ * digest is what lets the client tell it from a fault on hydration; returned
+ * so React writes it into the document. Under a boundary the developer wrote
+ * there is nothing to say; with nothing closer than a loading.tsx, one line.
+ */
+function reportRenderError(phase: 'ssr' | 'resume') {
+  return (error: unknown, info?: { componentStack?: string }) => {
+    // The consumer cancelled - a browser that left mid-stream, a prefetch
+    // abandoned. React reports it as an error; the page had none.
+    if (cancelledByConsumer(error)) return
+
+    const digest = (error as { digest?: string } | null)?.digest
+
+    if (digest === 'rsc-kit:search-params-fallback') {
+      // The component is the first frame of React's stack. Noted on the
+      // request so the build attaches it to the route; printed as one line,
+      // not a stack, so the server says which boundary it wants.
+      const where = /at ([A-Z][\\w$]*)/.exec(info?.componentStack ?? '')?.[1]
+
+      noteFallback('useSearchParams()' + (where ? ' in ' + where : ''))
+
+      if (caughtByLoading(info?.componentStack)) {
+        console.error(
+          '[rsc-kit] ' + (where ? where + ': ' : '') +
+          'useSearchParams() was read on the server with nothing closer than a loading.tsx, so the whole ' +
+          'segment shows that fallback until the query arrives. A <Suspense> around the component that reads ' +
+          'keeps the rest of the page painted.',
+        )
+      }
+
+      return digest
+    }
+
+    console.error('[rsc-kit:' + phase + ']', error)
+  }
+}
+
 /**
  * Pick a build-time render back up, against data that exists now.
  *
@@ -4023,7 +4326,12 @@ export async function handleSsrResume(
 
   const html = await resume(root as any, postponed as any, {
     nonce,
-    onError: (error: unknown) => { console.error('[rsc-kit:resume]', error) },
+    // The same reading of an error the first render has. This used to log
+    // every error raw, so a query read the developer's own boundary caught -
+    // the designed path, on every resume of a shell whose hole holds one -
+    // printed as "[rsc-kit:resume] Error: useSearchParams() was read..." on
+    // every request, with advice the app had already followed.
+    onError: reportRenderError('resume'),
   })
 
   return DEV_ORIGIN ? rewriteViteDevUrlStream(html, DEV_ORIGIN) : html
@@ -4304,6 +4612,46 @@ self.addEventListener('activate', (event) => {
   })())
 })
 `;
+/**
+ * Named imports from a barrel package, unrolled on the server environments.
+ *
+ * The browser gets lucide pre-bundled; the server environments do not, so
+ * `import { ArrowRight } from 'lucide-react'` loaded and transformed every
+ * icon module - 3,700 transforms, twenty-five seconds before the first
+ * document, for thirteen icons. See barrelImports. Development only: a
+ * build tree-shakes the barrel itself.
+ */
+function barrelImportsPlugin() {
+    const entries = new Map();
+    return {
+        name: "rsc-kit:barrel-imports",
+        apply: () => barrelImports && process.env.NODE_ENV !== "production",
+        enforce: "pre",
+        applyToEnvironment: (environment) => environment.name === "rsc" || environment.name === "ssr",
+        async transform(code, id) {
+            if (id.includes("/node_modules/") ||
+                !/\.[cm]?[jt]sx?$/.test(id.split("?")[0]))
+                return;
+            if (!code.includes("from"))
+                return;
+            const pending = [];
+            const wanted = new Set();
+            for (const m of code.matchAll(/import\s*(?:type\s+)?\{[^}]*\}\s*from\s*['"]([^'"./][^'"]*)['"]/g)) {
+                wanted.add(m[1]);
+            }
+            for (const specifier of wanted) {
+                if (entries.has(specifier))
+                    continue;
+                pending.push(this.resolve(specifier, id).then((resolved) => {
+                    entries.set(specifier, resolved && !resolved.external ? resolved.id.split("?")[0] : null);
+                }));
+            }
+            await Promise.all(pending);
+            const out = unrollBarrelImports(code, (specifier) => entries.get(specifier) ?? null);
+            return out === null ? undefined : { code: out, map: null };
+        },
+    };
+}
 /**
  * "use ssr" modules, rewritten for the server-components environment into
  * proxies that call the real module in the ssr environment. See useSsr.ts.
@@ -4478,10 +4826,107 @@ function clientImportsAudit() {
         },
     };
 }
+/**
+ * A Nitro runtime plugin, so instrumentation.ts runs when the server starts.
+ *
+ * Nitro loads the rsc service at the first request, not at startup - so
+ * without this, register() would run when the first visitor arrived, and a
+ * bad environment would take down a server that had already reported itself
+ * up. The plugin runs at app init and sends the service one request, which
+ * loads the module; loading it begins register(), and the request waits for
+ * it. Not on a Worker: there is no startup, and the first request is the
+ * first chance to read a binding.
+ */
+const STARTUP_PLUGIN = `import { viteServices } from "#nitro/virtual/vite-services"
+
+export default function rscKitStartup() {
+  if (typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers') return
+
+  // The ssr service is the one Nitro's renderer asks; its fetch imports the
+  // rsc entry and hands the request on. The rsc service's own export is the
+  // handler function, not a { fetch }, so it cannot be probed directly.
+  const ssr = viteServices.ssr
+  if (!ssr) return
+
+  // Two ways to fail, one outcome. register() rejecting is reported by the
+  // module itself. instrumentation.ts throwing at import - an env schema
+  // refusing - means the module never evaluated, so nothing in it can
+  // report; the load rejects here instead. Either way a server that could
+  // not bootstrap has nothing correct to serve, and says so and stops
+  // rather than reporting itself up.
+  ssr
+    .fetch(new Request('http://rsc-kit.internal/_rsc/startup', { headers: { 'x-rsc-kit-startup': '1' } }))
+    .then((response) => {
+      if (!response.ok) throw new Error('the startup probe answered ' + response.status)
+    })
+    .catch((error) => {
+      console.error('[rsc-kit] instrumentation.ts failed at startup:', error)
+
+      if (typeof process !== 'undefined' && typeof process.exit === 'function') process.exit(1)
+    })
+}
+`;
+/**
+ * Where NODE_ENV=development came from, and what to do about it.
+ *
+ * Vite reads NODE_ENV from its env files in this order, later winning, and
+ * only when the process did not already set it - so the last file that
+ * names it is the one that decided. No file naming it means the shell or
+ * `--mode` did.
+ */
+function nodeEnvSetIn(mode, envDir) {
+    const files = [".env", ".env.local", `.env.${mode}`, `.env.${mode}.local`];
+    let culprit = null;
+    // The project's root, not Vite's: this plugin points Vite's root at the
+    // build directory, and the app's .env is read from the project root - by
+    // Nitro's dotenv loading into process.env, and by Vite where envDir says
+    // so. Both places are looked at; the project's is where the file is.
+    const dirs = [...new Set([projectRoot, envDir || projectRoot])];
+    for (const dir of dirs)
+        for (const name of files) {
+            const path = join(dir, name);
+            if (!existsSync(path))
+                continue;
+            const lines = readFileSync(path, "utf-8").split("\n");
+            const at = lines.findIndex((line) => /^\s*(?:export\s+)?NODE_ENV\s*=/.test(line));
+            if (at !== -1)
+                culprit = `${path}:${at + 1}`;
+        }
+    return culprit;
+}
+function refuseDevelopmentBuild(config) {
+    const culprit = nodeEnvSetIn(config.mode, config.envDir);
+    return ("[rsc-kit] vite build is running as a development build, and the output cannot work: " +
+        "the pages are compiled against React's development JSX runtime (jsxDEV), the server " +
+        "bundles carry React's production build, and every route fails to render.\n\n" +
+        (culprit
+            ? `NODE_ENV=development is set in ${culprit}. Remove that line - Vite sets NODE_ENV ` +
+                "itself: development under `vite`, production under `vite build`."
+            : `NODE_ENV is "${process.env.NODE_ENV ?? ""}" from the environment or --mode ` +
+                "(mode: " + JSON.stringify(config.mode) + "). Build with NODE_ENV=production, or unset it."));
+}
 export function rscKit(options = {}) {
     resolvePaths(options);
+    const serverExternals = [
+        ...RUNTIME_BUILTINS,
+        ...[...DEFAULT_SERVER_EXTERNALS, ...(options.serverExternalPackages ?? [])].map(externalPackage),
+    ];
     const routesPlugin = {
         name: "rsc-kit",
+        // A Nitro module, which Nitro's Vite plugin collects from any plugin
+        // that carries one. Only for a built server: the dev server evaluates
+        // the entry through Vite's runner when it is first asked for, and there
+        // is no earlier moment to offer.
+        nitro: {
+            name: "rsc-kit",
+            setup(nitro) {
+                if (nitro.options.dev || !instrumentationFile())
+                    return;
+                nitro.options.virtual ??= {};
+                nitro.options.virtual["#rsc-kit/startup"] = STARTUP_PLUGIN;
+                nitro.options.plugins = [...(nitro.options.plugins ?? []), "#rsc-kit/startup"];
+            },
+        },
         config(_config, env) {
             if (!existsSync(appDir)) {
                 throw new Error(`[rsc-kit] No app directory at ${appDir} — nothing to build.`);
@@ -4493,6 +4938,7 @@ export function rscKit(options = {}) {
             apiRoutes.clear();
             discover(appDir);
             registerMetadataRoutes(appDir);
+            siteHosts = ownHosts(rootMetadataBase(appDir), hostsOption);
             // Silent when it worked. The names were printed on every dev start and
             // every build — thirty of them for a middling app, above the output that
             // actually says something, and the build's classification table lists
@@ -4680,7 +5126,7 @@ export function rscKit(options = {}) {
                         build: {
                             rollupOptions: {
                                 input: { index: join(genDir, "entry.rsc.tsx") },
-                                external: RUNTIME_BUILTINS,
+                                external: serverExternals,
                             },
                         },
                     },
@@ -4688,7 +5134,7 @@ export function rscKit(options = {}) {
                         build: {
                             rollupOptions: {
                                 input: { index: join(genDir, "entry.ssr.tsx") },
-                                external: RUNTIME_BUILTINS,
+                                external: serverExternals,
                             },
                         },
                     },
@@ -4927,6 +5373,24 @@ export function rscKit(options = {}) {
             }
         },
         configResolved(config) {
+            // A build that is not a production build cannot work here, and the
+            // way it fails is opaque: plugin-react emits the development JSX
+            // runtime (jsxDEV), the server bundles resolve React's production
+            // build, and every route fails to render with React's "message
+            // omitted in production builds". The usual cause is NODE_ENV=development
+            // in a .env file, which Vite honours - a line the scaffold itself once
+            // wrote. Named, with the file and line, before any of that happens.
+            //
+            // Refused rather than overridden, because a plugin cannot override it:
+            // Vite notes whether NODE_ENV was set before it loads the config file
+            // and applies the .env value after the config hooks have run, so an
+            // assignment here is overwritten - and patching the resolved config
+            // afterwards leaves the client bundle's process.env.NODE_ENV and
+            // import.meta.env.DEV already decided, which is a production server
+            // serving a development client.
+            if (config.command === "build" && !config.isProduction) {
+                throw new Error(refuseDevelopmentBuild(config));
+            }
             isWatch = config.build?.watch != null;
             resolvedConfig = config;
             const nitroMain = config.plugins.find((p) => p.name === "nitro:main");
@@ -4976,6 +5440,7 @@ export function rscKit(options = {}) {
             clientChunks: (meta) => meta.normalizedId,
             ...actionEncryptionKey(),
         }),
+        barrelImportsPlugin(),
         useSsrModules(),
         serverRendererInRsc(),
         metadataRoutesPlugin(),