@evolonix/react-router-next 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Ruesch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,268 @@
+# react-router-next
+
+Next.js-style filesystem routing for React Router 7, delivered as a Vite plugin plus a tiny runtime. Drop a `page.tsx` into a folder, get a typed route — including typed params, typed `generate(...)` URL builders, nested layouts/loaders/loading/error boundaries, parallel routes (`@slot`), intercepting routes (`(.)`/`(..)`/`(...)`), `template.tsx` remount-on-navigation, and `_private` colocation folders.
+
+> Peer dependencies: `react ≥ 19`, `react-dom ≥ 19`, `react-router ≥ 7`, `vite ≥ 5`.
+
+## Install
+
+```sh
+npm i @evolonix/react-router-next react-router
+```
+
+## Quick start
+
+### 1. Add the Vite plugin
+
+```ts
+// vite.config.ts
+import react from "@vitejs/plugin-react";
+import { routeTypegen } from "@evolonix/react-router-next/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [routeTypegen(), react()],
+});
+```
+
+### 2. Mount the router
+
+```tsx
+// src/main.tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { AppRouter } from "@evolonix/react-router-next";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <AppRouter />
+  </StrictMode>,
+);
+```
+
+### 3. Drop pages into `src/app/`
+
+```
+src/app/
+├── layout.tsx                 # wraps everything below
+├── page.tsx                   # /
+├── not-found.tsx              # not-found boundary (root only)
+├── (marketing)/               # route group — folder name in (parens) is stripped
+│   ├── about/page.tsx         # /about
+│   └── pricing/page.tsx       # /pricing
+├── posts/
+│   ├── layout.tsx             # /posts/*
+│   ├── loader.ts              # parent loader
+│   ├── loading.tsx            # skeleton during nav
+│   ├── page.tsx               # /posts (index)
+│   └── [postId]/
+│       ├── loader.ts          # leaf loader
+│       ├── error.tsx          # error boundary
+│       └── page.tsx           # /posts/:postId
+├── dashboard/                 # parallel-route slots
+│   ├── layout.tsx             # function ({ children, analytics })
+│   ├── page.tsx               # /dashboard main panel
+│   ├── settings/page.tsx      # /dashboard/settings main panel
+│   └── @analytics/            # parallel slot — invisible in URL
+│       ├── page.tsx           # rendered for /dashboard
+│       ├── settings/page.tsx  # rendered for /dashboard/settings
+│       └── default.tsx        # fallback when slot has no match
+└── photos/
+    ├── page.tsx               # /photos
+    ├── [id]/
+    │   ├── page.tsx           # full-page detail
+    │   └── template.tsx       # remounts on every navigation
+    ├── (.)[id]/page.tsx       # modal interceptor — rendered on PUSH/REPLACE
+    └── _components/           # private folder — never routed, importable
+        └── dialog.tsx
+```
+
+Folder-name conventions:
+
+| Pattern       | URL effect                                                           | TypeScript shape        |
+| ------------- | -------------------------------------------------------------------- | ----------------------- |
+| `foo`         | `/foo`                                                               | —                       |
+| `(group)`     | (segment removed)                                                    | —                       |
+| `[id]`        | `:id`                                                                | `{ id: string }`        |
+| `[[id]]`      | `:id?` (optional)                                                    | `{ id?: string }`       |
+| `[...slug]`   | catch-all                                                            | `{ slug: string[] }`    |
+| `[[...slug]]` | optional catch-all                                                   | `{ slug?: string[] }`   |
+| `@slot`       | (segment removed) — contents become a slot prop on the parent layout | —                       |
+| `_private`    | folder is skipped by routing (still importable from siblings)        | —                       |
+| `(.)x`        | intercepts URL `<parent>/x` — same level as containing folder        | inherits `x`'s shape    |
+| `(..)x`       | intercepts one filesystem level up                                   | inherits target's shape |
+| `(..)(..)x`   | intercepts two filesystem levels up                                  | inherits target's shape |
+| `(...)x`      | intercepts `/x` from the app root                                    | inherits target's shape |
+
+File-name conventions inside a route folder:
+
+| File            | Role                                                                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------- |
+| `page.tsx`      | Leaf component for the route                                                                            |
+| `layout.tsx`    | Wraps children via `<Outlet/>`. With sibling `@slot/` folders, also receives each slot as a named prop. |
+| `template.tsx`  | Like `layout.tsx` but remounts on every navigation (keyed on `pathname`).                               |
+| `default.tsx`   | Fallback inside a `@slot/` directory when the URL doesn't match any of the slot's pages.                |
+| `loader.ts`     | React Router data loader                                                                                |
+| `loading.tsx`   | Rendered while a parent loader is pending                                                               |
+| `error.tsx`     | `errorElement` for the route                                                                            |
+| `not-found.tsx` | App-wide not-found boundary (root only)                                                                 |
+
+### 4. Use the typed helpers
+
+For each route folder the plugin exposes a virtual module — `virtual:react-router-next/<route-key>` — that mirrors the folder layout, with the root represented as `_root`:
+
+```tsx
+// src/app/posts/[postId]/page.tsx
+import type { RouteProps } from "virtual:react-router-next/posts/[postId]";
+import { useLoaderData } from "react-router";
+import type { Post } from "../loader";
+
+export default function PostPage({ params }: RouteProps) {
+  const post = useLoaderData<Post>();
+  return (
+    <article>
+      {post.title} (id: {params.postId})
+    </article>
+  );
+}
+```
+
+```tsx
+// any other component
+import { generate as generatePost } from "virtual:react-router-next/posts/[postId]";
+
+<NavLink to={generatePost({ postId: "1" })}>First post</NavLink>;
+```
+
+The runtime hook `useRouteParams` is also re-exported from the package itself if you'd rather not pin the route literal:
+
+```tsx
+import { useRouteParams } from "@evolonix/react-router-next";
+const { postId } = useRouteParams("posts/[postId]");
+```
+
+## Build your own router
+
+`<AppRouter />` is a thin wrapper around `createBrowserRouter` plus the package's filesystem-to-`RouteObject[]` builder. If you need a different router (memory router for tests, hash router, SSR via `createStaticRouter`, custom `RouterProvider` props, route post-processing, etc.) import the builder directly and feed it the same virtual module the default router uses:
+
+```tsx
+// src/main.tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { createBrowserRouter, RouterProvider } from "react-router";
+import {
+  buildRoutesFromModules,
+  type RouteModuleMap,
+} from "@evolonix/react-router-next";
+// @ts-expect-error virtual module is provided by the routeTypegen Vite plugin
+import { modules, appDir } from "virtual:react-router-next/app-tree";
+
+const routes = buildRoutesFromModules(modules as RouteModuleMap, appDir);
+const router = createBrowserRouter(routes);
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <RouterProvider router={router} />
+  </StrictMode>,
+);
+```
+
+The returned `RouteObject[]` is plain React Router 7 — pass it to any router factory, splice in extra routes, or wrap the elements before mounting.
+
+## Parallel routes (`@slot`)
+
+A folder prefixed with `@` doesn't contribute a URL segment — instead, its contents are matched independently against the current URL and rendered in the parent layout as a named prop. The parent layout's signature gains one prop per slot:
+
+```tsx
+// src/app/dashboard/layout.tsx
+export default function DashboardLayout({
+  children,
+  analytics,
+}: {
+  children: ReactNode;
+  analytics: ReactNode;
+}) {
+  return (
+    <div className="grid grid-cols-[2fr_1fr]">
+      <main>{children}</main>
+      <aside>{analytics}</aside>
+    </div>
+  );
+}
+```
+
+Each slot subtree can have its own `page.tsx` files (matching the parent's URL space) and a `default.tsx` fallback rendered when the URL doesn't match any of the slot's explicit pages.
+
+> **V1 caveat:** slot subtrees are matched via `useRoutes()` outside React Router's data router, so a `loader.ts` under a `@slot/` directory is dropped with a build-time warning. Use ordinary children for data-driven UI.
+
+## Intercepting routes (`(.)`/`(..)`/`(...)`)
+
+A folder whose name starts with `(.)`, `(..)`, `(..)(..)`, or `(...)` is an **interceptor**: its `page.tsx` is rendered when the user soft-navigates (PUSH/REPLACE) to a target URL elsewhere in the tree. On reload, back/forward, or direct visit, the original target page renders instead. The interceptor and the target share the same routeKey and `useRouteParams`/`generate` virtual module.
+
+```
+photos/
+├── page.tsx              # /photos
+├── [id]/page.tsx         # /photos/:id — full-page detail (POP / refresh)
+└── (.)[id]/page.tsx      # /photos/:id — modal (PUSH / REPLACE from in-app Link)
+```
+
+Prefix semantics (counted in **filesystem** levels — slots count, group folders count, but the prefix itself does not):
+
+- `(.)x` — same level as the interceptor's containing folder; appends `x`.
+- `(..)x` — pops one filesystem level above, then appends `x`.
+- `(..)(..)x` — pops two levels.
+- `(...)x` — anchors at the app root.
+
+> **V1 caveats:** the interceptor folder may only contain `page.tsx`. A `loader.ts` or `layout.tsx` inside an interceptor is dropped with a build-time warning. The intercept target route must exist — otherwise the build fails (a refresh on the URL has to render _something_).
+
+## `template.tsx` and `_private` folders
+
+- `template.tsx` works like `layout.tsx`, but the wrapper is keyed on `useLocation().pathname` so it remounts on every navigation. Useful for entry transitions or `useEffect`-based instrumentation that should fire per-navigation.
+- A folder whose name starts with `_` is skipped by the router entirely. Use it to colocate components, helpers, or fixtures alongside your routes without producing a URL.
+
+## How types work without running Vite
+
+The plugin (and the bundled `react-router-next` CLI) emit a single ambient `routes.d.ts` shim into `node_modules/.react-router-next/`. The shim contains one `declare module 'virtual:react-router-next/<route-key>' { … }` block per discovered route, so `tsc` and editors resolve the imports and infer per-route param shapes — even when Vite isn't running.
+
+Add the shim to your tsconfig:
+
+```jsonc
+// tsconfig.app.json
+{
+  "include": ["src", "node_modules/.react-router-next/routes.d.ts"],
+}
+```
+
+In CI, run typegen before `tsc`:
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "typegen": "react-router-next typegen",
+    "prebuild": "npm run typegen",
+    "build": "tsc -b && vite build",
+  },
+}
+```
+
+## Plugin options
+
+```ts
+routeTypegen({
+  appDir: "src/app", // default
+  outDir: "node_modules/.react-router-next", // default
+});
+```
+
+The CLI mirrors these:
+
+```sh
+react-router-next typegen \
+  --app-dir=src/app \
+  --out-dir=node_modules/.react-router-next
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+// src/plugin/typegen.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, isAbsolute, join, resolve } from "path";
+
+// src/plugin/scan.ts
+import { readdirSync } from "fs";
+import { relative } from "path";
+var ROUTE_DIR_FILE_RE = /^(page|layout|default|template)\.(tsx|jsx|ts|js)$/;
+function toPosix(p) {
+  return p.split("\\").join("/");
+}
+function isPrivateSegment(seg) {
+  return seg.startsWith("_");
+}
+function isSlotSegment(seg) {
+  return seg.startsWith("@") && seg.length > 1;
+}
+function parseInterceptPrefix(seg) {
+  if (seg.startsWith("(...)")) return { depth: "root", rest: seg.slice(5) };
+  if (seg.startsWith("(..)(..)")) return { depth: 3, rest: seg.slice(8) };
+  if (seg.startsWith("(..)")) return { depth: 2, rest: seg.slice(4) };
+  if (seg.startsWith("(.)")) return { depth: 1, rest: seg.slice(3) };
+  return null;
+}
+function scanAppDir(appDir) {
+  let entries;
+  try {
+    entries = readdirSync(appDir, { recursive: true, withFileTypes: true });
+  } catch {
+    return { routeDirs: [] };
+  }
+  const routeDirs = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!ROUTE_DIR_FILE_RE.test(entry.name)) continue;
+    const dir = entry.parentPath ?? entry.path ?? appDir;
+    const rel = toPosix(relative(appDir, dir));
+    if (rel !== "" && rel.split("/").some(isPrivateSegment)) continue;
+    routeDirs.add(dir);
+  }
+  return { routeDirs: [...routeDirs] };
+}
+function routeKeySegmentsOf(parts) {
+  return parts.filter((s) => !isSlotSegment(s) && !isPrivateSegment(s));
+}
+function computeRouteKey(parts) {
+  let interceptIdx = -1;
+  let intercept = null;
+  for (let i = 0; i < parts.length; i++) {
+    const p = parseInterceptPrefix(parts[i]);
+    if (p) {
+      interceptIdx = i;
+      intercept = p;
+      break;
+    }
+  }
+  if (intercept === null) return routeKeySegmentsOf(parts).join("/");
+  const fsPrefix = parts.slice(0, interceptIdx);
+  let resolved;
+  if (intercept.depth === "root") {
+    resolved = [];
+  } else {
+    const popCount = intercept.depth - 1;
+    resolved = fsPrefix.slice(0, Math.max(0, fsPrefix.length - popCount));
+  }
+  const prefixSegs = routeKeySegmentsOf(resolved);
+  const tail = parts.slice(interceptIdx + 1);
+  const restSegments = [];
+  if (intercept.rest) restSegments.push(intercept.rest);
+  restSegments.push(...tail);
+  return [...prefixSegs, ...routeKeySegmentsOf(restSegments)].join("/");
+}
+function routeKeyFor(appDir, routeDir) {
+  const rel = toPosix(relative(appDir, routeDir));
+  if (rel === "") return "";
+  return computeRouteKey(rel.split("/"));
+}
+function routeHasParams(routeKey) {
+  return routeKey.includes("[");
+}
+
+// src/plugin/render.ts
+var HEADER = "// AUTO-GENERATED by react-router-next typegen \u2014 do not edit.";
+function renderDeclareBody(routeKey) {
+  if (!routeHasParams(routeKey)) {
+    return `  import type { RouteParams as RouteParamsBase } from "@evolonix/react-router-next";
+  const PATH: ${JSON.stringify(routeKey)};
+  export type RouteParams = RouteParamsBase<typeof PATH>;
+  export function generate(): string;
+`;
+  }
+  return `  import type { RouteParams as RouteParamsBase } from "@evolonix/react-router-next";
+  const PATH: ${JSON.stringify(routeKey)};
+  export type RouteParams = RouteParamsBase<typeof PATH>;
+  export type RouteProps = { params: RouteParams };
+  export function useRouteParams(): RouteParams;
+  export function generate(params: RouteParams): string;
+`;
+}
+function virtualIdFor(routeKey) {
+  return `virtual:react-router-next/${routeKey === "" ? "_root" : routeKey}`;
+}
+function renderDtsShim(routeKeys) {
+  const blocks = routeKeys.map((key) => {
+    const id = virtualIdFor(key);
+    return `declare module ${JSON.stringify(id)} {
+${renderDeclareBody(key)}}
+`;
+  });
+  return `${HEADER}
+// Ambient declarations for react-router-next virtual route modules.
+// Generated by \`react-router-next typegen\` and the routeTypegen Vite plugin.
+
+declare module "virtual:react-router-next/app-tree" {
+  import type { ComponentType } from "react";
+  import type { LoaderFunction } from "react-router";
+
+  export type RouteModule = {
+    default?: ComponentType<{
+      params?: Record<string, string | string[] | undefined>;
+    }>;
+    loader?: LoaderFunction;
+  };
+
+  export const modules: Record<string, RouteModule>;
+  export const appDir: string;
+}
+
+${blocks.join("\n")}`;
+}
+
+// src/plugin/typegen.ts
+function resolveAgainst(root, p) {
+  return isAbsolute(p) ? p : resolve(root, p);
+}
+function writeIfChanged(path, contents) {
+  try {
+    const existing = readFileSync(path, "utf8");
+    if (existing === contents) return false;
+  } catch {
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, contents);
+  return true;
+}
+function generateRouteTypes(opts = {}) {
+  const root = opts.root ?? process.cwd();
+  const appDir = resolveAgainst(root, opts.appDir ?? "src/app");
+  const outDir = resolveAgainst(
+    root,
+    opts.outDir ?? "node_modules/.react-router-next"
+  );
+  const { routeDirs } = scanAppDir(appDir);
+  const routeKeys = [
+    ...new Set(routeDirs.map((dir) => routeKeyFor(appDir, dir)))
+  ].sort((a, b) => a.localeCompare(b));
+  const shimPath = join(outDir, "routes.d.ts");
+  const written = writeIfChanged(shimPath, renderDtsShim(routeKeys));
+  return { appDir, outDir, routeKeys, shimPath, written };
+}
+
+// src/cli.ts
+function parseArgs(argv) {
+  const flags = {};
+  const rest = [];
+  let command;
+  for (const arg of argv) {
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (eq === -1) {
+        flags[arg.slice(2)] = true;
+      } else {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+      }
+    } else if (!command) {
+      command = arg;
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { command, flags, rest };
+}
+function printHelp() {
+  console.log(`react-router-next \u2014 typed filesystem routing for React Router 7
+
+Usage:
+  react-router-next typegen [options]
+
+Options:
+  --app-dir <path>   Source directory of pages/layouts (default: src/app)
+  --out-dir <path>   Where the routes.d.ts shim is written
+                     (default: node_modules/.react-router-next)
+  --help, -h         Show this message
+`);
+}
+async function main() {
+  const { command, flags } = parseArgs(process.argv.slice(2));
+  if (flags.help || flags.h || command === "help") {
+    printHelp();
+    return;
+  }
+  if (command !== "typegen") {
+    if (command) {
+      console.error(`[react-router-next] Unknown command: ${command}`);
+    }
+    printHelp();
+    process.exit(command ? 1 : 0);
+  }
+  const result = generateRouteTypes({
+    appDir: typeof flags["app-dir"] === "string" ? flags["app-dir"] : void 0,
+    outDir: typeof flags["out-dir"] === "string" ? flags["out-dir"] : void 0
+  });
+  console.log(
+    `[react-router-next] ${result.routeKeys.length} route(s); shim ${result.written ? "updated" : "unchanged"} at ${result.shimPath}`
+  );
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugin/typegen.ts","../src/plugin/scan.ts","../src/plugin/render.ts","../src/cli.ts"],"sourcesContent":["import { mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { dirname, isAbsolute, join, resolve } from \"node:path\";\nimport { renderDtsShim } from \"./render\";\nimport { routeKeyFor, scanAppDir } from \"./scan\";\n\nexport type GenerateOptions = {\n  /** Project root used to resolve relative paths. Defaults to `process.cwd()`. */\n  root?: string;\n  /** Source-of-truth directory containing `page.tsx`/`layout.tsx`. Defaults to `src/app`. */\n  appDir?: string;\n  /** Where the ambient `routes.d.ts` shim is written. Defaults to `<root>/node_modules/.react-router-next`. */\n  outDir?: string;\n};\n\nexport type GenerateResult = {\n  appDir: string;\n  outDir: string;\n  routeKeys: string[];\n  shimPath: string;\n  written: boolean;\n};\n\nfunction resolveAgainst(root: string, p: string): string {\n  return isAbsolute(p) ? p : resolve(root, p);\n}\n\nfunction writeIfChanged(path: string, contents: string): boolean {\n  try {\n    const existing = readFileSync(path, \"utf8\");\n    if (existing === contents) return false;\n  } catch {\n    // file missing — fall through to write\n  }\n  mkdirSync(dirname(path), { recursive: true });\n  writeFileSync(path, contents);\n  return true;\n}\n\nexport function generateRouteTypes(opts: GenerateOptions = {}): GenerateResult {\n  const root = opts.root ?? process.cwd();\n  const appDir = resolveAgainst(root, opts.appDir ?? \"src/app\");\n  const outDir = resolveAgainst(\n    root,\n    opts.outDir ?? \"node_modules/.react-router-next\",\n  );\n\n  const { routeDirs } = scanAppDir(appDir);\n  const routeKeys = [\n    ...new Set(routeDirs.map((dir) => routeKeyFor(appDir, dir))),\n  ].sort((a, b) => a.localeCompare(b));\n\n  const shimPath = join(outDir, \"routes.d.ts\");\n  const written = writeIfChanged(shimPath, renderDtsShim(routeKeys));\n\n  return { appDir, outDir, routeKeys, shimPath, written };\n}\n","import { readdirSync } from \"node:fs\";\nimport { relative } from \"node:path\";\n\nconst ROUTE_DIR_FILE_RE = /^(page|layout|default|template)\\.(tsx|jsx|ts|js)$/;\n\nexport function toPosix(p: string): string {\n  return p.split(\"\\\\\").join(\"/\");\n}\n\nexport type ScanResult = {\n  /** Absolute paths of directories that contain a page/layout/default/template file. */\n  routeDirs: string[];\n};\n\nexport function isPrivateSegment(seg: string): boolean {\n  return seg.startsWith(\"_\");\n}\n\nexport function isSlotSegment(seg: string): boolean {\n  return seg.startsWith(\"@\") && seg.length > 1;\n}\n\nexport type InterceptDepth = 1 | 2 | 3 | \"root\";\n\nexport type InterceptParse = { depth: InterceptDepth; rest: string };\n\nexport function parseInterceptPrefix(seg: string): InterceptParse | null {\n  // Check from most specific to least so e.g. \"(...)x\" doesn't get caught by \"(.)\".\n  if (seg.startsWith(\"(...)\")) return { depth: \"root\", rest: seg.slice(5) };\n  if (seg.startsWith(\"(..)(..)\")) return { depth: 3, rest: seg.slice(8) };\n  if (seg.startsWith(\"(..)\")) return { depth: 2, rest: seg.slice(4) };\n  if (seg.startsWith(\"(.)\")) return { depth: 1, rest: seg.slice(3) };\n  return null;\n}\n\nexport function isRouteGroupSegment(seg: string): boolean {\n  return (\n    seg.startsWith(\"(\") &&\n    seg.endsWith(\")\") &&\n    parseInterceptPrefix(seg) === null\n  );\n}\n\nexport function scanAppDir(appDir: string): ScanResult {\n  let entries;\n  try {\n    entries = readdirSync(appDir, { recursive: true, withFileTypes: true });\n  } catch {\n    return { routeDirs: [] };\n  }\n  const routeDirs = new Set<string>();\n  for (const entry of entries) {\n    if (!entry.isFile()) continue;\n    if (!ROUTE_DIR_FILE_RE.test(entry.name)) continue;\n    const dir =\n      (entry as unknown as { parentPath?: string; path?: string }).parentPath ??\n      (entry as unknown as { path?: string }).path ??\n      appDir;\n    const rel = toPosix(relative(appDir, dir));\n    if (rel !== \"\" && rel.split(\"/\").some(isPrivateSegment)) continue;\n    routeDirs.add(dir);\n  }\n  return { routeDirs: [...routeDirs] };\n}\n\nfunction routeKeySegmentsOf(parts: readonly string[]): string[] {\n  // Keep route groups in the routeKey (they're literal directory components).\n  // Strip @slots and `_private` because they don't appear in any URL.\n  return parts.filter((s) => !isSlotSegment(s) && !isPrivateSegment(s));\n}\n\n/**\n * Compute the route key for a sequence of filesystem segments.\n *\n * - `_private` folders and `@slot` folders are stripped (they don't appear in URLs).\n * - Route groups `(group)` are preserved literally, matching the existing\n *   `(marketing)/about` shape.\n * - An intercept-prefixed segment (`(.)x`, `(..)x`, `(..)(..)x`, `(...)x`)\n *   collapses preceding filesystem segments by `depth - 1` levels (or all the\n *   way to the root for `(...)`), then appends the stripped name.\n *\n * For an interceptor folder, the returned key is the resolved target route key\n * — e.g. `photos/(.)[id]` → `photos/[id]`, the same key as the interceptor's\n * target page. That keeps `useRouteParams<...>()` aligned with the URL the\n * user sees regardless of which file rendered.\n */\nexport function computeRouteKey(parts: readonly string[]): string {\n  let interceptIdx = -1;\n  let intercept: InterceptParse | null = null;\n  for (let i = 0; i < parts.length; i++) {\n    const p = parseInterceptPrefix(parts[i]);\n    if (p) {\n      interceptIdx = i;\n      intercept = p;\n      break;\n    }\n  }\n\n  if (intercept === null) return routeKeySegmentsOf(parts).join(\"/\");\n\n  const fsPrefix = parts.slice(0, interceptIdx);\n  let resolved: string[];\n  if (intercept.depth === \"root\") {\n    resolved = [];\n  } else {\n    const popCount = intercept.depth - 1;\n    resolved = fsPrefix.slice(0, Math.max(0, fsPrefix.length - popCount));\n  }\n  const prefixSegs = routeKeySegmentsOf(resolved);\n  const tail = parts.slice(interceptIdx + 1);\n  const restSegments: string[] = [];\n  if (intercept.rest) restSegments.push(intercept.rest);\n  restSegments.push(...tail);\n  return [...prefixSegs, ...routeKeySegmentsOf(restSegments)].join(\"/\");\n}\n\nexport function routeKeyFor(appDir: string, routeDir: string): string {\n  const rel = toPosix(relative(appDir, routeDir));\n  if (rel === \"\") return \"\";\n  return computeRouteKey(rel.split(\"/\"));\n}\n\nexport function routeHasParams(routeKey: string): boolean {\n  return routeKey.includes(\"[\");\n}\n\n/** Match `(page|layout|loader|loading|error|default|template|not-found).{tsx,jsx,ts,js}`. */\nexport const ROUTE_FILE_RE =\n  /[\\\\/](page|layout|loader|loading|error|default|template|not-found)\\.(tsx|jsx|ts|js)$/;\n","import { routeHasParams } from \"./scan\";\n\nconst HEADER = \"// AUTO-GENERATED by react-router-next typegen — do not edit.\";\n\n/**\n * Source emitted into the **runtime** virtual module for a given route key.\n * Plain JavaScript — type info lives in the ambient `.d.ts` shim emitted by\n * `renderDtsShim`. Virtual modules aren't transformed as TypeScript by Vite,\n * so the runtime form must not contain type-only syntax.\n */\nexport function renderRuntimeModule(routeKey: string): string {\n  if (!routeHasParams(routeKey)) {\n    return `${HEADER}\nimport { generateUrl } from \"@evolonix/react-router-next\";\n\nconst PATH = ${JSON.stringify(routeKey)};\n\nexport function generate() {\n  return generateUrl(PATH, {});\n}\n`;\n  }\n\n  return `${HEADER}\nimport {\n  generateUrl,\n  useRouteParams as useRouteParamsBase,\n} from \"@evolonix/react-router-next\";\n\nconst PATH = ${JSON.stringify(routeKey)};\n\nexport function useRouteParams() {\n  return useRouteParamsBase(PATH);\n}\n\nexport function generate(params) {\n  return generateUrl(PATH, params);\n}\n`;\n}\n\n/**\n * Body of a `declare module 'virtual:react-router-next/<route-key>' { ... }`\n * block. Same shape as the runtime module, but with type-only declarations so\n * `tsc` and editors resolve consumer imports without spinning up Vite.\n */\nfunction renderDeclareBody(routeKey: string): string {\n  if (!routeHasParams(routeKey)) {\n    return `  import type { RouteParams as RouteParamsBase } from \"@evolonix/react-router-next\";\n  const PATH: ${JSON.stringify(routeKey)};\n  export type RouteParams = RouteParamsBase<typeof PATH>;\n  export function generate(): string;\n`;\n  }\n  return `  import type { RouteParams as RouteParamsBase } from \"@evolonix/react-router-next\";\n  const PATH: ${JSON.stringify(routeKey)};\n  export type RouteParams = RouteParamsBase<typeof PATH>;\n  export type RouteProps = { params: RouteParams };\n  export function useRouteParams(): RouteParams;\n  export function generate(params: RouteParams): string;\n`;\n}\n\nexport function virtualIdFor(routeKey: string): string {\n  return `virtual:react-router-next/${routeKey === \"\" ? \"_root\" : routeKey}`;\n}\n\n/**\n * Emit a single ambient `.d.ts` shim covering every discovered route. Import\n * specifiers that consumers write (e.g.\n * `virtual:react-router-next/posts/[postId]`) resolve to a `declare module`\n * block in this file at type-check time.\n */\nexport function renderDtsShim(routeKeys: readonly string[]): string {\n  const blocks = routeKeys.map((key) => {\n    const id = virtualIdFor(key);\n    return `declare module ${JSON.stringify(id)} {\n${renderDeclareBody(key)}}\n`;\n  });\n  return `${HEADER}\n// Ambient declarations for react-router-next virtual route modules.\n// Generated by \\`react-router-next typegen\\` and the routeTypegen Vite plugin.\n\ndeclare module \"virtual:react-router-next/app-tree\" {\n  import type { ComponentType } from \"react\";\n  import type { LoaderFunction } from \"react-router\";\n\n  export type RouteModule = {\n    default?: ComponentType<{\n      params?: Record<string, string | string[] | undefined>;\n    }>;\n    loader?: LoaderFunction;\n  };\n\n  export const modules: Record<string, RouteModule>;\n  export const appDir: string;\n}\n\n${blocks.join(\"\\n\")}`;\n}\n","#!/usr/bin/env node\nimport { generateRouteTypes } from \"./plugin/typegen\";\n\ntype ParsedArgs = {\n  command: string | undefined;\n  flags: Record<string, string | true>;\n  rest: string[];\n};\n\nfunction parseArgs(argv: string[]): ParsedArgs {\n  const flags: Record<string, string | true> = {};\n  const rest: string[] = [];\n  let command: string | undefined;\n  for (const arg of argv) {\n    if (arg.startsWith(\"--\")) {\n      const eq = arg.indexOf(\"=\");\n      if (eq === -1) {\n        flags[arg.slice(2)] = true;\n      } else {\n        flags[arg.slice(2, eq)] = arg.slice(eq + 1);\n      }\n    } else if (!command) {\n      command = arg;\n    } else {\n      rest.push(arg);\n    }\n  }\n  return { command, flags, rest };\n}\n\nfunction printHelp(): void {\n  console.log(`react-router-next — typed filesystem routing for React Router 7\n\nUsage:\n  react-router-next typegen [options]\n\nOptions:\n  --app-dir <path>   Source directory of pages/layouts (default: src/app)\n  --out-dir <path>   Where the routes.d.ts shim is written\n                     (default: node_modules/.react-router-next)\n  --help, -h         Show this message\n`);\n}\n\nasync function main(): Promise<void> {\n  const { command, flags } = parseArgs(process.argv.slice(2));\n\n  if (flags.help || flags.h || command === \"help\") {\n    printHelp();\n    return;\n  }\n\n  if (command !== \"typegen\") {\n    if (command) {\n      console.error(`[react-router-next] Unknown command: ${command}`);\n    }\n    printHelp();\n    process.exit(command ? 1 : 0);\n  }\n\n  const result = generateRouteTypes({\n    appDir: typeof flags[\"app-dir\"] === \"string\" ? flags[\"app-dir\"] : undefined,\n    outDir: typeof flags[\"out-dir\"] === \"string\" ? flags[\"out-dir\"] : undefined,\n  });\n\n  console.log(\n    `[react-router-next] ${result.routeKeys.length} route(s); shim ${\n      result.written ? \"updated\" : \"unchanged\"\n    } at ${result.shimPath}`,\n  );\n}\n\nmain().catch((err: unknown) => {\n  console.error(err);\n  process.exit(1);\n});\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { JSX, ComponentType, ReactNode } from 'react';
+import { LoaderFunction, RouteObject } from 'react-router';
+
+declare function AppRouter(): JSX.Element;
+
+type RouteParamsRecord = Record<string, string | string[] | undefined>;
+type RouteModule = {
+    default?: ComponentType<{
+        params?: RouteParamsRecord;
+        children?: ReactNode;
+        [slot: string]: unknown;
+    }>;
+    loader?: LoaderFunction;
+};
+type RouteModuleMap = Record<string, RouteModule>;
+declare function buildRoutesFromModules(modules: RouteModuleMap, appDir: string): RouteObject[];
+
+type ParseSegment<S extends string> = S extends `[[...${infer Name}]]` ? {
+    [K in Name]?: string[];
+} : S extends `[...${infer Name}]` ? {
+    [K in Name]: string[];
+} : S extends `[[${infer Name}]]` ? {
+    [K in Name]?: string;
+} : S extends `[${infer Name}]` ? {
+    [K in Name]: string;
+} : S extends `(${string})` ? Record<never, never> : S extends `@${string}` ? Record<never, never> : Record<never, never>;
+type ParseRoute<S extends string> = S extends `${infer Head}/${infer Tail}` ? ParseSegment<Head> & ParseRoute<Tail> : ParseSegment<S>;
+type RouteParams<S extends string> = string extends S ? Record<string, string | string[] | undefined> : {
+    [K in keyof ParseRoute<S>]: ParseRoute<S>[K];
+};
+type RouteProps<S extends string> = {
+    params: RouteParams<S>;
+};
+declare function parseRouteParams<S extends string>(route: S, rrParams: Readonly<Record<string, string | undefined>>): RouteParams<S>;
+declare function useRouteParams<S extends string>(route: S): RouteParams<S>;
+
+declare function generateUrl<S extends string>(route: S, params: RouteParams<S>): string;
+
+export { AppRouter, type RouteModule, type RouteModuleMap, type RouteParams, type RouteProps, buildRoutesFromModules, generateUrl, parseRouteParams, useRouteParams };