@rangojs/router 0.0.0-experimental.126 → 0.0.0-experimental.128

package/src/vite/discovery/prerender-collection.ts

@@ -13,6 +13,7 @@ import {
   runWithConcurrency,
   groupByConcurrency,
   notifyOnError,
+  resolvePrerenderError,
   stageBuildAssetModule,
 } from "../utils/prerender-utils.js";
 import type { DiscoveryState } from "./state.js";
@@ -231,6 +232,10 @@ export async function expandPrerenderRoutes(
   const manifestEntries: Record<string, string> = {};
   let doneCount = 0;
   let skipCount = 0;
+  // #587: a render error reaches here (matchForPrerender now re-throws it rather
+  // than baking the error boundary). Default "fail" fails the build; "warn" logs
+  // and skips baking the URL.
+  const prerenderOnError = state.opts?.prerenderOnError ?? "fail";
   const startTotal = performance.now();
 
   // Group entries by concurrency for batched rendering.
@@ -297,35 +302,22 @@ export async function expandPrerenderRoutes(
             doneCount++;
             break;
           } catch (err: any) {
-            if (err.name === "Skip") {
-              const elapsed = (performance.now() - startUrl).toFixed(0);
-              console.log(
-                `[rango]   SKIP ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
-              );
-              skipCount++;
-              notifyOnError(
-                registry,
-                err,
-                "prerender",
-                entry.routeName,
-                entry.urlPath,
-                true,
-              );
-              break;
-            }
-            // Regular error: log, notify, and fail the build
+            // Skip, or a render error under prerender.onError "warn": skip the
+            // URL (never bake the error page, #587). A render error under the
+            // default "fail" re-throws below to fail the build.
             const elapsed = (performance.now() - startUrl).toFixed(0);
-            console.error(
-              `[rango]   FAIL ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
-            );
-            notifyOnError(
+            resolvePrerenderError(
               registry,
               err,
+              prerenderOnError,
+              entry.urlPath.padEnd(40),
+              elapsed,
               "prerender",
               entry.routeName,
               entry.urlPath,
             );
-            throw err;
+            skipCount++;
+            break;
           }
         }
       },
@@ -378,6 +370,7 @@ export async function renderStaticHandlers(
   let staticDone = 0;
   let staticSkip = 0;
   let totalStaticCount = 0;
+  const prerenderOnError = state.opts?.prerenderOnError ?? "fail";
 
   // Count handlers for the log header
   for (const [, exportNames] of state.resolvedStaticModules) {
@@ -434,23 +427,19 @@ export async function renderStaticHandlers(
             break;
           }
         } catch (err: any) {
-          if (err.name === "Skip") {
-            const elapsed = (performance.now() - startHandler).toFixed(0);
-            console.log(
-              `[rango]   SKIP ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
-            );
-            staticSkip++;
-            notifyOnError(registry, err, "static", undefined, undefined, true);
-            handled = true;
-            break;
-          }
-          // Regular error: log, notify, and fail the build
+          // Same Skip/warn/fail policy as the prerender loop (shared helper).
           const elapsed = (performance.now() - startHandler).toFixed(0);
-          console.error(
-            `[rango]   FAIL ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+          resolvePrerenderError(
+            registry,
+            err,
+            prerenderOnError,
+            name.padEnd(40),
+            elapsed,
+            "static",
           );
-          notifyOnError(registry, err, "static");
-          throw err;
+          staticSkip++;
+          handled = true;
+          break;
         }
       }
       if (!handled) {

package/src/vite/discovery/state.ts

@@ -25,6 +25,12 @@ export interface PluginOptions {
    * Compiled into `DiscoveryState.scanFilter` once `projectRoot` is known.
    */
   discovery?: { include?: string[]; exclude?: string[] };
+  /**
+   * What to do when a Prerender/Static render throws at build time, from
+   * rango({ prerender: { onError } }). "fail" (default) fails the build; "warn"
+   * logs and skips baking the URL. See {@link import("../plugin-types.js").RangoOptions}.
+   */
+  prerenderOnError?: "fail" | "warn";
   /**
    * Shared context the built-in clientChunks strategy reads. Discovery populates
    * it (registered fallback hashes + single-router name) before the client build

package/src/vite/plugin-types.ts

@@ -139,6 +139,31 @@ interface RangoBaseOptions {
     include?: string[];
     exclude?: string[];
   };
+
+  /**
+   * What to do when a `Prerender` route's or `Static` handler's render throws at
+   * build time. Otherwise the route error boundary catches it and the rendered
+   * error page is baked as the artifact, then served as an HTTP 200 — a silent,
+   * user-visible breakage (issue #587). Independent of this setting, a render may
+   * `throw new Skip()` (from `@rangojs/router`) to skip a single URL/handler.
+   *
+   * - `"fail"` (**default**): fail the build, naming the URL/handler and the
+   *   original render error.
+   * - `"warn"`: log a warning and skip baking the artifact — it is never served as a
+   *   baked 200 error page. `"warn"` is a build-unblock, NOT a runtime contract for
+   *   the skipped entry: the route falls through to normal resolution, which may
+   *   render live (its handler is still bundled — e.g. when nothing else baked) or
+   *   404 (once prerender handler eviction has run for other baked entries), so the
+   *   outcome depends on the rest of the build, and a skipped `Static()` handler's
+   *   evicted code can surface as an error. For DEFINED runtime behavior use
+   *   `Passthrough()` (a live fallback) or `throw new Skip()` (an intentional skip);
+   *   otherwise prefer the default `"fail"`.
+   *
+   * @default "fail"
+   */
+  prerender?: {
+    onError?: "fail" | "warn";
+  };
 }
 
 /**

package/src/vite/plugins/expose-ids/router-transform.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { createHash } from "node:crypto";
 import { normalizePath, findMatchingParen } from "../expose-id-utils.js";
 import { getImportedFnNames } from "./export-analysis.js";
+import { codeMatchIndices } from "../../../build/route-types/source-scan.js";
 import { createRangoDebugger, createCounter, NS } from "../../debug.js";
 
 const debug = createRangoDebugger(NS.transform);
@@ -28,7 +29,16 @@ export function transformRouter(
   const routeNamesImport = `./${basename}.named-routes.gen.js`;
   const routeNamesVar = `__rsc_rn`;
 
+  // Only inject at call sites in REAL code, not inside comments or string
+  // literals — e.g. a `createRouter({ ... })` snippet in a JSDoc example must
+  // not get a `$$id`/`.named-routes.gen` import injected. The sibling analysis
+  // path (export-analysis.ts) already uses this same comment/string-aware scan;
+  // the raw `pat.exec(code)` loop below would otherwise match in comments too.
+  const codeOffsets = new Set(codeMatchIndices(code, pat));
+  pat.lastIndex = 0;
+
   while ((match = pat.exec(code)) !== null) {
+    if (!codeOffsets.has(match.index)) continue;
     const callStart = match.index;
     const parenPos = match.index + match[0].length - 1;
 

package/src/vite/rango.ts

@@ -428,6 +428,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       enableBuildPrerender: prerenderEnabled,
       buildEnv: options?.buildEnv,
       preset,
+      prerenderOnError: options?.prerender?.onError,
       discovery: options?.discovery,
       clientChunkCtx,
     }),

package/src/vite/router-discovery.ts

@@ -912,9 +912,15 @@ export function createRouterDiscoveryPlugin(
             logResult(200, `match ${result.routeName}`);
             return;
           } catch (err: any) {
-            console.warn(
-              `[rango] Dev prerender failed for ${pathname}: ${err.message}`,
-            );
+            // matchForPrerender now re-throws render failures instead of baking
+            // an error page (issue #587). In dev there is no frozen artifact, so
+            // we fall through (404 -> live handler). A `throw new Skip()` is the
+            // expected "skip this URL" signal, not a failure, so it stays quiet.
+            if (err?.name !== "Skip") {
+              console.warn(
+                `[rango] Dev prerender error for ${pathname} (serving live instead): ${err.message}`,
+              );
+            }
           }
         }
 

package/src/vite/utils/prerender-utils.ts

@@ -137,6 +137,42 @@ export function notifyOnError(
   }
 }
 
+/**
+ * Resolve a thrown build-time render error into the prerender build's policy and
+ * log a per-entry line. A `Skip` (or any render error under `prerender.onError:
+ * "warn"`) logs and returns so the caller skips the entry; a render error under
+ * the default "fail" logs FAIL, notifies `onError`, and re-throws to fail the
+ * build. Shared by `expandPrerenderRoutes` (prerender) and `renderStaticHandlers`
+ * (static) so the Skip/warn/fail policy lives in one place. `label` is the padded
+ * URL / handler name for the log line; `elapsed` is the per-entry duration string.
+ */
+export function resolvePrerenderError(
+  registry: Map<string, any>,
+  error: any,
+  onError: "fail" | "warn",
+  label: string,
+  elapsed: string,
+  phase: "prerender" | "static",
+  routeKey?: string,
+  pathname?: string,
+): void {
+  const isSkip = error?.name === "Skip";
+  if (isSkip || onError === "warn") {
+    if (isSkip) {
+      console.log(`[rango]   SKIP ${label} (${elapsed}ms) - ${error.message}`);
+    } else {
+      console.warn(
+        `[rango]   WARN ${label} (${elapsed}ms) - render error, not pre-rendered (prerender.onError: "warn"): ${error.message}`,
+      );
+    }
+    notifyOnError(registry, error, phase, routeKey, pathname, true);
+    return;
+  }
+  console.error(`[rango]   FAIL ${label} (${elapsed}ms) - ${error.message}`);
+  notifyOnError(registry, error, phase, routeKey, pathname);
+  throw error;
+}
+
 function getStagedAssetDir(projectRoot: string): string {
   return resolve(projectRoot, "node_modules/.rangojs-router-build/rsc-assets");
 }