@rangojs/router 0.0.0-experimental.a6f6907d → 0.0.0-experimental.a99e6916

package/skills/rango/SKILL.md

@@ -10,28 +10,30 @@ Django-inspired RSC router with composable URL patterns, type-safe href, and ser
 
 ## Skills
 
-| Skill              | Description                                                                |
-| ------------------ | -------------------------------------------------------------------------- |
-| `/router-setup`    | Create and configure the RSC router                                        |
-| `/route`           | Define routes with `urls()` and `path()`                                   |
-| `/layout`          | Layouts that wrap child routes                                             |
-| `/loader`          | Data loaders with `createLoader()`                                         |
-| `/middleware`      | Request processing and authentication                                      |
-| `/intercept`       | Modal/slide-over patterns for soft navigation                              |
-| `/parallel`        | Multi-column layouts and sidebars                                          |
-| `/caching`         | Segment caching with memory or KV stores                                   |
-| `/use-cache`       | Function-level caching with `"use cache"` directive                        |
-| `/cache-guide`     | When to use `cache()` vs `"use cache"` — differences and decision guide    |
-| `/document-cache`  | Edge caching with Cache-Control headers                                    |
-| `/theme`           | Light/dark mode with FOUC prevention                                       |
-| `/links`           | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
-| `/hooks`           | Client-side React hooks                                                    |
-| `/typesafety`      | Type-safe routes, params, href, and environment                            |
-| `/host-router`     | Multi-app host routing with domain/subdomain patterns                      |
-| `/tailwind`        | Set up Tailwind CSS v4 with `?url` imports                                 |
-| `/response-routes` | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
-| `/mime-routes`     | Content negotiation — same URL, different response types via Accept header |
-| `/fonts`           | Load web fonts with preload hints                                          |
+| Skill                   | Description                                                                |
+| ----------------------- | -------------------------------------------------------------------------- |
+| `/router-setup`         | Create and configure the RSC router                                        |
+| `/route`                | Define routes with `urls()` and `path()`                                   |
+| `/layout`               | Layouts that wrap child routes                                             |
+| `/loader`               | Data loaders with `createLoader()`                                         |
+| `/middleware`           | Request processing and authentication                                      |
+| `/intercept`            | Modal/slide-over patterns for soft navigation                              |
+| `/parallel`             | Multi-column layouts and sidebars                                          |
+| `/caching`              | Segment caching with memory or KV stores                                   |
+| `/use-cache`            | Function-level caching with `"use cache"` directive                        |
+| `/cache-guide`          | When to use `cache()` vs `"use cache"` — differences and decision guide    |
+| `/document-cache`       | Edge caching with Cache-Control headers                                    |
+| `/theme`                | Light/dark mode with FOUC prevention                                       |
+| `/links`                | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
+| `/hooks`                | Client-side React hooks                                                    |
+| `/typesafety`           | Type-safe routes, params, href, and environment                            |
+| `/host-router`          | Multi-app host routing with domain/subdomain patterns                      |
+| `/tailwind`             | Set up Tailwind CSS v4 with `?url` imports                                 |
+| `/response-routes`      | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
+| `/mime-routes`          | Content negotiation — same URL, different response types via Accept header |
+| `/fonts`                | Load web fonts with preload hints                                          |
+| `/migrate-nextjs`       | Migrate a Next.js App Router project to Rango                              |
+| `/migrate-react-router` | Migrate a React Router / Remix project to Rango                            |
 
 ## Quick Start
 

package/src/index.ts

@@ -147,24 +147,52 @@ export { createVar, type ContextVar } from "./context-var.js";
 export { nonce } from "./rsc/nonce.js";
 
 /**
- * Error-throwing stub for server-only `Prerender` function.
+ * SSR/client stub for server-only `Prerender` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Prerender
+ * calls in RSC code must not crash at module-evaluation time.
  */
-export function Prerender(): never {
-  throw serverOnlyStubError("Prerender");
+export function Prerender(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "prerenderHandler" as const, $$id: id };
 }
 
 /**
- * Error-throwing stub for server-only `Passthrough` function.
+ * SSR/client stub for server-only `Passthrough` function.
  */
-export function Passthrough(): never {
-  throw serverOnlyStubError("Passthrough");
+export function Passthrough(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "passthroughHandler" as const, $$id: id };
 }
 
 /**
- * Error-throwing stub for server-only `Static` function.
+ * SSR/client stub for server-only `Static` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Static
+ * calls in RSC code must not crash at module-evaluation time.
  */
-export function Static(): never {
-  throw serverOnlyStubError("Static");
+export function Static(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "staticHandler" as const, $$id: id };
 }
 
 /**

package/src/route-definition/dsl-helpers.ts

@@ -55,6 +55,9 @@ const hasRoutesInItem = (item: AllUseItems): boolean => {
   if (item.type === "layout" && item.uses) {
     return item.uses.some((child) => hasRoutesInItem(child));
   }
+  if (item.type === "middleware" && item.uses) {
+    return item.uses.some((child) => hasRoutesInItem(child));
+  }
   return false;
 };
 
@@ -353,10 +356,37 @@ const cache: RouteHelpers<any, any>["cache"] = (
   return { name: namespace, type: "cache", uses: result } as CacheItem;
 };
 
-const middleware: RouteHelpers<any, any>["middleware"] = (...fn) => {
+const middleware: RouteHelpers<any, any>["middleware"] = (...args: any[]) => {
+  // Four call forms:
+  //   middleware(fn)                       — single fn, sibling
+  //   middleware(fn, () => [...])          — single fn, wrapping
+  //   middleware([fn1, fn2])              — array, sibling
+  //   middleware([fn1, fn2], () => [...]) — array, wrapping
+  const isArray = Array.isArray(args[0]);
+
+  // Reject the removed variadic form before executing anything.
+  // middleware(fn1, fn2, fn3) — 3+ args, always wrong.
+  // middleware(fn1, fn2) where fn2 is a middleware fn (length >= 1), not a
+  // children callback (length === 0) — legacy two-fn form, reject early.
+  if (
+    args.length > 2 ||
+    (!isArray &&
+      args.length === 2 &&
+      typeof args[1] === "function" &&
+      args[1].length > 0)
+  ) {
+    throw new Error(
+      "middleware() no longer accepts variadic arguments. " +
+        "Use middleware([fn1, fn2, ...]) instead of middleware(fn1, fn2, ...).",
+    );
+  }
+
+  const fns: MiddlewareFn<any>[] = isArray ? args[0] : [args[0]];
+  const children: (() => any[]) | undefined =
+    typeof args[1] === "function" ? args[1] : undefined;
+
   // Prevent "use cache" functions from being used as middleware.
-  // Checked before context validation — this is a static invariant.
-  for (const f of fn) {
+  for (const f of fns) {
     if (isCachedFunction(f)) {
       throw new Error(
         `A "use cache" function cannot be used as middleware. ` +
@@ -367,17 +397,80 @@ const middleware: RouteHelpers<any, any>["middleware"] = (...fn) => {
     }
   }
 
-  const ctx = getContext().getStore();
+  const store = getContext();
+  const ctx = store.getStore();
   if (!ctx) throw new Error("middleware() must be called inside map()");
 
-  // Attach to last entry in stack
-  const parent = ctx.parent;
-  if (!parent || !("middleware" in parent)) {
-    invariant(false, "No parent entry available for middleware()");
+  if (!children) {
+    // Sibling mode: attach to parent entry
+    const parent = ctx.parent;
+    if (!parent || !("middleware" in parent)) {
+      invariant(false, "No parent entry available for middleware()");
+    }
+    const name = `$${store.getNextIndex("middleware")}`;
+    parent.middleware.push(...fns);
+    return { name, type: "middleware" } as MiddlewareItem;
+  }
+
+  // Wrapping mode: create a transparent layout that carries the middleware
+  const mwIndex = store.getNextIndex("middleware");
+  const namespace = `${ctx.namespace}.${mwIndex}`;
+
+  const urlPrefix = getUrlPrefix();
+  const entry = {
+    id: namespace,
+    shortCode: store.getShortCode("layout"),
+    type: "layout",
+    parent: ctx.parent,
+    handler: RootLayout,
+    loading: undefined,
+    middleware: [...fns],
+    revalidate: [],
+    errorBoundary: [],
+    notFoundBoundary: [],
+    layout: [],
+    parallel: {},
+    intercept: [],
+    loader: [],
+    ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+  } as EntryData;
+
+  // Run children callback. If the second arg was actually a middleware fn
+  // (old variadic form: middleware(mw1, mw2)), this will return a non-array
+  // and the invariant below gives a clear migration error.
+  const rawResult = store.run(namespace, entry, children);
+
+  invariant(
+    Array.isArray(rawResult),
+    "middleware(fn, children) expects the second argument to return an array of use items. " +
+      "To pass multiple middleware, use middleware([fn1, fn2]).",
+  );
+
+  const result = rawResult.flat(3);
+
+  invariant(
+    result.every((item: any) => isValidUseItem(item)),
+    `middleware() children callback must return an array of use items [${namespace}]`,
+  );
+
+  const hasRoutes =
+    result &&
+    Array.isArray(result) &&
+    result.some((item) => item != null && hasRoutesInItem(item));
+
+  if (!hasRoutes) {
+    const parent = ctx.parent;
+    if (parent && "layout" in parent) {
+      entry.parent = null;
+      parent.layout.push(entry);
+    }
   }
-  const name = `$${getContext().getNextIndex("middleware")}`;
-  parent.middleware.push(...fn);
-  return { name, type: "middleware" } as MiddlewareItem;
+
+  return {
+    name: namespace,
+    type: "middleware",
+    uses: result,
+  } as MiddlewareItem;
 };
 
 const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {

package/src/route-definition/helpers-types.ts

@@ -182,21 +182,41 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
     ): InterceptItem;
   };
   /**
-   * Attach middleware to the current route/layout
+   * Attach middleware to the current route/layout, or wrap child segments
+   *
+   * **Sibling mode** — attaches middleware to the parent entry:
    * ```typescript
-   * middleware(async (ctx, next) => {
-   *   const session = await getSession(ctx.request);
-   *   if (!session) return redirect("/login");
-   *   ctx.set("user", session.user);
-   *   next();
-   * })
+   * layout(<DashboardShell />, () => [
+   *   middleware(authMiddleware),
+   *   middleware([authMiddleware, loggingMiddleware]),
+   *   path("/", DashboardPage),
+   * ])
+   * ```
+   *
+   * **Wrapping mode** — scopes middleware to the children only:
+   * ```typescript
+   * middleware(authMiddleware, () => [
+   *   path("/dashboard", DashboardPage),
+   *   path("/settings", SettingsPage),
+   * ])
    *
-   * // Chain multiple middleware
-   * middleware(authMiddleware, loggingMiddleware, rateLimitMiddleware)
+   * middleware([authMiddleware, loggingMiddleware], () => [
+   *   path("/admin", AdminPage),
+   * ])
    * ```
-   * @param fns - One or more middleware functions to execute in order
    */
-  middleware: (...fns: MiddlewareFn<TEnv>[]) => MiddlewareItem;
+  middleware: {
+    (fn: MiddlewareFn<TEnv>): MiddlewareItem;
+    (
+      fn: MiddlewareFn<TEnv>,
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+    (fns: MiddlewareFn<TEnv>[]): MiddlewareItem;
+    (
+      fns: MiddlewareFn<TEnv>[],
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+  };
   /**
    * Control when a segment should revalidate during navigation
    * ```typescript

package/src/urls/path-helper-types.ts

@@ -264,9 +264,20 @@ export type PathHelpers<TEnv> = {
       ) => InterceptItem;
 
   /**
-   * Attach middleware to the current route/layout
+   * Attach middleware to the current route/layout, or wrap child segments
    */
-  middleware: (...fns: MiddlewareFn<TEnv>[]) => MiddlewareItem;
+  middleware: {
+    (fn: MiddlewareFn<TEnv>): MiddlewareItem;
+    (
+      fn: MiddlewareFn<TEnv>,
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+    (fns: MiddlewareFn<TEnv>[]): MiddlewareItem;
+    (
+      fns: MiddlewareFn<TEnv>[],
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+  };
 
   /**
    * Control when a segment should revalidate during navigation