@rsc-kit/core 0.18.0 → 0.18.1

package/dist/vite.d.ts

@@ -101,6 +101,17 @@ export interface RscKitOptions {
      * reads this file follows the server instead of guessing at it.
      */
     hotFile?: string;
+    /**
+     * Packages the server bundles import at runtime rather than inline.
+     *
+     * For a dependency with a native binary, one that spawns a process, or one
+     * that reads files beside itself - anything a bundle breaks. A default list
+     * covers the usual ones (sharp, bcrypt, better-sqlite3, prisma, puppeteer,
+     * ...); this adds to it. Nitro traces an external package into
+     * .output/server/node_modules with its binaries, so the deployment is still
+     * one directory.
+     */
+    serverExternalPackages?: string[];
     /**
      * Where `rpc()` goes while `vite dev` is serving.
      *

package/dist/vite.js

@@ -42,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];
 }
@@ -2068,8 +2109,15 @@ function installHostCallsOnce(): void {
 function instrumentationFile() {
     for (const ext of ["ts", "tsx", "mts", "js", "mjs"]) {
         const file = join(sourceDir, `instrumentation.${ext}`);
-        if (existsSync(file))
-            return file;
+        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;
 }
@@ -2135,10 +2183,13 @@ ${
     // 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
-        ? `import * as __instrumentation from ${JSON.stringify(instrumentation)}`
-        : "const __instrumentation: { register?: () => unknown } = {}"}
+    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"))}
@@ -2675,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
@@ -4156,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
@@ -4236,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.
  *
@@ -4255,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
@@ -4790,8 +4866,51 @@ export default function rscKitStartup() {
     })
 }
 `;
+/**
+ * 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
@@ -5007,7 +5126,7 @@ export function rscKit(options = {}) {
                         build: {
                             rollupOptions: {
                                 input: { index: join(genDir, "entry.rsc.tsx") },
-                                external: RUNTIME_BUILTINS,
+                                external: serverExternals,
                             },
                         },
                     },
@@ -5015,7 +5134,7 @@ export function rscKit(options = {}) {
                         build: {
                             rollupOptions: {
                                 input: { index: join(genDir, "entry.ssr.tsx") },
-                                external: RUNTIME_BUILTINS,
+                                external: serverExternals,
                             },
                         },
                     },
@@ -5254,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");