@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.1b930379

package/README.md

@@ -45,6 +45,30 @@ For Cloudflare Workers:
 npm install @cloudflare/vite-plugin
 ```
 
+## Import Paths
+
+Use these import paths consistently:
+
+- `@rangojs/router` — server/RSC router APIs, route DSL, `createRouter`, `urls`, `redirect`, `Prerender`, `Static`, shared types
+- `@rangojs/router/client` — hooks and components such as `Link`, `Outlet`, `href`, `useNavigation`, `useLoader`, `useAction`, `useLocationState`
+- `@rangojs/router/cache` — public cache APIs such as `CFCacheStore`, `MemorySegmentCacheStore`, `createDocumentCacheMiddleware`
+- `@rangojs/router/host`, `@rangojs/router/theme`, `@rangojs/router/vite` — specialized public subpaths
+- `@rangojs/router/rsc`, `@rangojs/router/ssr` — advanced server-only integration subpaths for custom request/HTML pipelines
+
+Use only subpaths that are explicitly exported from the package. Avoid deep imports such as `@rangojs/router/cache/cf`.
+
+`@rangojs/router` is conditionally resolved. Server-only root APIs such as
+`createRouter()`, `urls()`, `redirect()`, `Prerender()`, and `cookies()` rely on
+the `react-server` export condition and are meant to run in router definitions,
+handlers, and other RSC/server modules. Outside that environment the root entry
+falls back to stub implementations that throw guidance errors.
+
+If you hit a root-entrypoint stub error:
+
+- hooks and components like `Link`, `Outlet`, `useLoader`, `useNavigation`, and `MetaTags` belong in `@rangojs/router/client`
+- cache APIs like `CFCacheStore` and `createDocumentCacheMiddleware` belong in `@rangojs/router/cache`
+- host-router APIs belong in `@rangojs/router/host`
+
 ## Quick Start
 
 ### Vite Config
@@ -62,6 +86,9 @@ export default defineConfig({
 
 ### Router
 
+This file is a server/RSC module and should import router construction APIs from
+`@rangojs/router`.
+
 ```tsx
 // src/router.tsx
 import { createRouter, urls } from "@rangojs/router";
@@ -248,7 +275,8 @@ All handler typing styles are supported, but they solve different problems:
 Example of a scoped local name inside a mounted module:
 
 ```tsx
-import type { Handler, ScopedRouteMap } from "@rangojs/router";
+import type { Handler } from "@rangojs/router";
+import type { ScopedRouteMap } from "@rangojs/router/__internal";
 
 type BlogRoutes = ScopedRouteMap<"blog">;
 
@@ -488,7 +516,7 @@ function Nav() {
   return (
     <nav>
       <Link to={href("/")}>Home</Link>
-      <Link to={href("/blog")} prefetch="hybrid">
+      <Link to={href("/blog")} prefetch="adaptive">
         Blog
       </Link>
       <Link to={href("/about")}>About</Link>
@@ -842,16 +870,22 @@ module, use `scopedReverse<typeof localPatterns>(ctx.reverse)` or
 
 ## Subpath Exports
 
-| Export                   | Description                                                                       |
-| ------------------------ | --------------------------------------------------------------------------------- |
-| `@rangojs/router`        | Core: `createRouter`, `urls`, `createLoader`, `Handler`, `Prerender`, `Meta`      |
-| `@rangojs/router/client` | Client: `Link`, `Outlet`, `href`, `useNavigation`, `useLoader`, `MetaTags`        |
-| `@rangojs/router/cache`  | Cache: `CFCacheStore`, `MemorySegmentCacheStore`, `createDocumentCacheMiddleware` |
-| `@rangojs/router/theme`  | Theme: `useTheme`, `ThemeProvider`, `ThemeScript`                                 |
-| `@rangojs/router/host`   | Host routing: `createHostRouter`, `defineHosts`                                   |
-| `@rangojs/router/vite`   | Vite plugin: `rango()`                                                            |
-| `@rangojs/router/server` | Server utilities                                                                  |
-| `@rangojs/router/build`  | Build utilities                                                                   |
+| Export                   | Description                                                                                              |
+| ------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `@rangojs/router`        | Server/RSC core and shared types: `createRouter`, `urls`, `createLoader`, `Handler`, `Prerender`, `Meta` |
+| `@rangojs/router/client` | Client: `Link`, `Outlet`, `href`, `useNavigation`, `useLoader`, `MetaTags`                               |
+| `@rangojs/router/cache`  | Cache: `CFCacheStore`, `MemorySegmentCacheStore`, `createDocumentCacheMiddleware`                        |
+| `@rangojs/router/theme`  | Theme: `useTheme`, `ThemeProvider`, `ThemeScript`                                                        |
+| `@rangojs/router/host`   | Host routing: `createHostRouter`, `defineHosts`                                                          |
+| `@rangojs/router/vite`   | Vite plugin: `rango()`                                                                                   |
+| `@rangojs/router/rsc`    | Advanced server pipeline APIs: `createRSCHandler`, request-context access                                |
+| `@rangojs/router/ssr`    | Advanced SSR bridge APIs: `createSSRHandler`                                                             |
+| `@rangojs/router/server` | Internal build/runtime utilities for advanced integrations                                               |
+| `@rangojs/router/build`  | Build utilities                                                                                          |
+
+The root entrypoint is not a generic client/runtime barrel. If you need hooks
+or components, import from `@rangojs/router/client`; if you need cache or host
+APIs, use their dedicated subpaths.
 
 ## Examples
 

package/dist/bin/rango.js

@@ -574,8 +574,20 @@ var init_per_module_writer = __esm({
 });
 
 // src/build/route-types/router-processing.ts
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync as existsSync3, unlinkSync } from "node:fs";
-import { join as join2, dirname as dirname2, resolve as resolve2, basename as pathBasename } from "node:path";
+import {
+  readFileSync as readFileSync3,
+  writeFileSync as writeFileSync2,
+  existsSync as existsSync3,
+  unlinkSync,
+  readdirSync as readdirSync2
+} from "node:fs";
+import {
+  join as join2,
+  dirname as dirname2,
+  resolve as resolve2,
+  sep,
+  basename as pathBasename
+} from "node:path";
 import ts5 from "typescript";
 function countPublicRouteEntries(source) {
   const matches = source.matchAll(/^\s+(?:"([^"]+)"|([a-zA-Z_$][^:]*)):\s*["{]/gm) ?? [];
@@ -588,6 +600,76 @@ function countPublicRouteEntries(source) {
   }
   return count;
 }
+function isRoutableSourceFile(name) {
+  return (name.endsWith(".ts") || name.endsWith(".tsx") || name.endsWith(".js") || name.endsWith(".jsx")) && !name.includes(".gen.");
+}
+function findRouterFilesRecursive(dir, filter, results) {
+  let entries;
+  try {
+    entries = readdirSync2(dir, { withFileTypes: true });
+  } catch (err) {
+    console.warn(
+      `[rsc-router] Failed to scan directory ${dir}: ${err.message}`
+    );
+    return;
+  }
+  const childDirs = [];
+  const routerFilesInDir = [];
+  for (const entry of entries) {
+    const fullPath = join2(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      childDirs.push(fullPath);
+      continue;
+    }
+    if (!isRoutableSourceFile(entry.name)) continue;
+    if (filter && !filter(fullPath)) continue;
+    try {
+      const source = readFileSync3(fullPath, "utf-8");
+      if (ROUTER_CALL_PATTERN.test(source)) {
+        routerFilesInDir.push(fullPath);
+      }
+    } catch {
+      continue;
+    }
+  }
+  if (routerFilesInDir.length > 0) {
+    results.push(...routerFilesInDir);
+    return;
+  }
+  for (const childDir of childDirs) {
+    findRouterFilesRecursive(childDir, filter, results);
+  }
+}
+function findNestedRouterConflict(routerFiles) {
+  const routerDirs = [
+    ...new Set(routerFiles.map((filePath) => dirname2(resolve2(filePath))))
+  ].sort((a, b) => a.length - b.length);
+  for (let i = 0; i < routerDirs.length; i++) {
+    const ancestorDir = routerDirs[i];
+    const prefix = ancestorDir.endsWith(sep) ? ancestorDir : `${ancestorDir}${sep}`;
+    for (let j = i + 1; j < routerDirs.length; j++) {
+      const nestedDir = routerDirs[j];
+      if (!nestedDir.startsWith(prefix)) continue;
+      const ancestorFile = routerFiles.find(
+        (filePath) => dirname2(resolve2(filePath)) === ancestorDir
+      );
+      const nestedFile = routerFiles.find(
+        (filePath) => dirname2(resolve2(filePath)) === nestedDir
+      );
+      if (ancestorFile && nestedFile) {
+        return { ancestor: ancestorFile, nested: nestedFile };
+      }
+    }
+  }
+  return null;
+}
+function formatNestedRouterConflictError(conflict, prefix = "[rsc-router]") {
+  return `${prefix} Nested router roots are not supported.
+Router root: ${conflict.ancestor}
+Nested router: ${conflict.nested}
+Move the nested router into a sibling directory or configure it as a separate app root.`;
+}
 function extractUrlsVariableFromRouter(code) {
   const sourceFile = ts5.createSourceFile(
     "router.tsx",
@@ -711,19 +793,8 @@ function detectUnresolvableIncludesForUrlsFile(filePath) {
   return diagnostics;
 }
 function findRouterFiles(root, filter) {
-  const files = findTsFiles(root, filter);
   const result = [];
-  for (const filePath of files) {
-    if (filePath.includes(".gen.")) continue;
-    try {
-      const source = readFileSync3(filePath, "utf-8");
-      if (/\bcreateRouter\s*[<(]/.test(source)) {
-        result.push(filePath);
-      }
-    } catch {
-      continue;
-    }
-  }
+  findRouterFilesRecursive(root, filter, result);
   return result;
 }
 function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
@@ -739,6 +810,10 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
   }
   const routerFilePaths = knownRouterFiles ?? findRouterFiles(root);
   if (routerFilePaths.length === 0) return;
+  const nestedRouterConflict = findNestedRouterConflict(routerFilePaths);
+  if (nestedRouterConflict) {
+    throw new Error(formatNestedRouterConflictError(nestedRouterConflict));
+  }
   for (const routerFilePath of routerFilePaths) {
     let routerSource;
     try {
@@ -798,14 +873,15 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
     }
   }
 }
+var ROUTER_CALL_PATTERN;
 var init_router_processing = __esm({
   "src/build/route-types/router-processing.ts"() {
     "use strict";
     init_codegen();
-    init_scan_filter();
     init_include_resolution();
     init_per_module_writer();
     init_route_name();
+    ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
   }
 });
 
@@ -1428,6 +1504,15 @@ function runStaticGeneration(args, mode) {
     formatDiagnostics(uniqueDiagnostics);
     console.warn("");
   }
+  const nestedRouterConflict = findNestedRouterConflict(routerFiles);
+  if (nestedRouterConflict) {
+    console.error(
+      `
+${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}
+`
+    );
+    process.exit(1);
+  }
   for (const urlsFile of urlsFiles) {
     writePerModuleRouteTypesForFile(urlsFile);
   }
@@ -1471,6 +1556,15 @@ async function runRuntimeDiscovery(args, configFile) {
     console.error("[rango] No router files found in the provided paths");
     process.exit(1);
   }
+  const nestedRouterConflict = findNestedRouterConflict(routerEntries);
+  if (nestedRouterConflict) {
+    console.error(
+      `
+${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}
+`
+    );
+    process.exit(1);
+  }
   let discoverAndWriteRouteTypes2;
   try {
     const mod = await Promise.resolve().then(() => (init_runtime_discovery(), runtime_discovery_exports));