next-vite-router 1.2.3 → 1.3.0

package/README.md

@@ -4,7 +4,7 @@ File-based routing for React + Vite.
 
 Define routes with folders and let the package generate the
 [React Router](https://reactrouter.com/) `RouteObject[]`. It does not replace
-React Router, navigation, history, loaders, or application state.
+React Router, navigation, history, or application state.
 
 ## Start here
 
@@ -31,6 +31,10 @@ export default defineConfig({
 });
 ```
 
+The plugin ships both ESM and CJS, so this works when `package.json` has no
+`"type": "module"` (Vite 5 loads `vite.config.ts` with `require()` in that
+case). You can also rename the file to `vite.config.mts` to force ESM.
+
 Create your route tree:
 
 ```text
@@ -88,10 +92,12 @@ npm run dev
 
 ## Use React Router directly
 
-`Router` is only a convenience wrapper around `useRoutes(routes)`. Routes are
-generated lazily on the first render, so calls to `configureRouter` and
-`registerMiddleware` made during application setup are applied before route
-elements are created. You can keep using React Router APIs:
+`Router` is only a convenience wrapper around `useRoutes(routes)`. The
+lazy-loading behavior and `loadingFallback` configured through `configureRouter`
+are read at render time, so they take effect even when `generateRoutes()` runs
+at module scope before application setup finishes. Register middleware with
+`registerMiddleware` *before* calling `generateRoutes()`, because route elements
+are wrapped while the tree is built. You can keep using React Router APIs:
 
 ```tsx
 import {
@@ -115,10 +121,18 @@ export default function App() {
 }
 ```
 
-Use `useNavigate`, loaders, actions, and other React Router APIs from
-`react-router-dom`. The package `useParams` hook is also available from the
-virtual module and maps catch-all names such as `slug`. The package does not
-create competing navigation or data-loading APIs.
+Keep using React Router's navigation and hooks from `react-router-dom`
+(`useNavigate`, `useLocation`, `Link`, `Outlet`). For parameters, import
+`useParams` from the virtual module instead of `react-router-dom`: dynamic
+`[id]` segments work with either hook, but named catch-all segments
+(`[...slug]`, `[[...slug]]`) are only surfaced as `slug` through the package
+`useParams`. React Router's own `useParams` returns them under `params["*"]`.
+
+The generated `RouteObject[]` carries page, layout, and not-found elements only.
+There is no file convention that produces React Router route `loader` or
+`action` functions, and those data APIs run only under a data router
+(`createBrowserRouter` + `RouterProvider`), not under `BrowserRouter` with
+`useRoutes`. Fetch data inside your page components instead.
 
 ## File conventions
 
@@ -133,13 +147,17 @@ create competing navigation or data-loading APIs.
 | `(admin)` | Route group omitted from the URL |
 
 Catch-all pages and `not-found.tsx` at the same level both use React Router's
-`*` path and should not be declared together if their fallback behavior must
-be distinct. The catch-all parameter provider wraps the page route, so a
-layout cannot read that parameter through the package `useParams` hook.
+`*` path and are rejected during route validation because their fallback
+behavior would be ambiguous. The catch-all parameter provider wraps the page
+route, so a layout cannot read that parameter through the package `useParams`
+hook.
 
 The Vite plugin accepts custom `pageFile`, `layoutFile`, and `notFoundFile`
 names. `createRouteGenerator` accepts the same options, plus `pagesDir`, as
 its optional fourth argument when custom glob paths or extensions are used.
+For the Vite plugin, `pagesDir` is relative to the Vite project root (the
+default is `src/app`). The lower-level route path utility also accepts an
+absolute `pagesDir`, which is useful for custom route generators.
 
 Layouts are the recommended way to add route-scoped navigation, providers, or
 authorization:
@@ -206,6 +224,9 @@ configureRouter({
 });
 ```
 
+The fallback is resolved when a route suspends during render, so the order of
+`configureRouter` relative to `generateRoutes()` does not matter.
+
 `enableLazyLoading: false` is available for compatibility and testing. It does
 not turn Vite's asynchronous imports into synchronous imports.
 
@@ -302,7 +323,12 @@ pnpm exec tsc -p test/fixture/tsconfig.json --noEmit
 pnpm run test:local
 ```
 
-The route matrix lives in [`test/routes.test.js`](./test/routes.test.js).
+The route matrix lives in [`test/routes.test.js`](./test/routes.test.js) and
+includes React Router `matchRoutes` assertions for dynamic parameters, route
+groups, nested `not-found.tsx` fallbacks, and catch-all pages under layouts.
+`test/test-route-types.js` covers generated TypeScript declarations and HMR
+updates, while `test/test-compatibility.js` checks the supported dependency
+ranges and generated production bootstrap.
 
 ## License
 

package/dist/cli.cjs

@@ -548,7 +548,7 @@ const init = new commander.Command().name("init").description(
 Project "${projectName}" is ready!
 `);
 });
-const version = "1.2.3";
+const version = "1.3.0";
 const pkg = {
   version
 };

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("./tree-hc1dSMdb.cjs"),l=require("react"),S=require("react-router-dom"),C={enableLazyLoading:!0};let f={...C};function v(e){f={...f,...e}}function F(){f={...C}}function T(){return f}let g=[];function x(e,t){g.push({pattern:e,middleware:t})}function A(){g=[]}function y(e,t){let r=t;for(const n of g)n.pattern.lastIndex=0,n.pattern.test(e)&&(r=n.middleware(r)),n.pattern.lastIndex=0;return r}const M=()=>l.createElement("div"),h=new Map;function N(){const e=T();if(e.enableLazyLoading===!1)return null;const t=e.loadingFallback||M;return l.createElement(t)}function $(){h.clear()}function p(e,t,r){let n=h.get(t);n||(n=l.lazy(e),h.set(t,n));const a=l.createElement(l.Suspense,{fallback:l.createElement(N)},l.createElement(n));return r?y(r,a):a}const P=l.createContext(void 0);function w({name:e,children:t}){return l.createElement(P.Provider,{value:e},t)}function k(){return l.useContext(P)}function E(e,t){return y(e,l.createElement(t))}function D(e){const t=c.parseRouteSegments(e)[0];return(t==null?void 0:t.kind)==="catchAll"&&t.optional}function d(e){const t=c.parseRouteSegments(e)[0];return t?c.routeSegmentToPath(t):""}function s(e,t){return m(e,t,!0)}function m(e,t,r=!1){const n=e.page;if(!n)throw new Error(`Route node "${e.fullPath}" has no page loader`);const a=p(async()=>({default:(await n()).default}),`page:${e.fullPath||t}`,t),o=c.parseRouteSegments(e.segment)[0],u=(o==null?void 0:o.kind)==="catchAll"?l.createElement(w,{name:o.name,children:a}):a;return r?{index:!0,element:u}:{path:d(e.segment),element:u}}function q(e){const t=e.notFound;if(!t)throw new Error(`Route node "${e.fullPath}" has no not-found loader`);const r=e.fullPath?`/${e.fullPath}`:"/";return{path:"*",element:p(async()=>({default:(await t()).default}),`notfound:${e.fullPath}`,r)}}function L(e){return e.notFound?[q(e)]:[]}function I(e,t,r,n){return{...t?{path:t}:{},element:E(e,r),children:n.length>0?n:void 0}}function b(e,t){const r=[];return[...e.children.entries()].sort(([n],[a])=>n.localeCompare(a)).forEach(([n,a])=>{const o=d(n),u=o?t?`${t}/${o}`:`/${o}`:t;r.push(...R(a,!1,u))}),r}function z(e,t){const r=[];return e.page&&r.push(s(e,t||"/")),r.push(...b(e,t)),r.push(...L(e)),r}function G(e,t,r,n,a,o){if(D(e.segment)){const u=[...a,...o];return[s(e,t),{path:n,element:m(e,r).element,children:u.length>0?u:void 0}]}return a.length>0||o.length>0?[{path:n,children:[s(e,r),...a,...o]}]:[{path:n,element:m(e,r).element}]}function O(e,t,r,n){const a=[...e.page?[s(e,t)]:[],...r,...n];return[{children:a.length>0?a:void 0}]}function j(e){const t=z(e,"");return e.layout?[{path:"/",element:E("/",e.layout),children:t}]:e.page?t.length>1?[{path:"/",children:t}]:[{path:"/",element:m(e,"/",!1).element}]:e.notFound?[{path:"/",children:t}]:t}function R(e,t=!1,r=""){if(t)return j(e);const n=d(e.segment),a=!n,o=a?r:r+"/"+n,u=b(e,o),i=L(e);return e.layout?[I(o,a?"":n,e.layout,z(e,o))]:e.page&&!a?G(e,r,o,n,u,i):e.page||e.notFound||!a?a?O(e,o,u,i):[{path:n,children:[...e.page?[s(e,o)]:[],...u,...i]}]:u}function B(e,t,r,n){return()=>{const a=c.buildRouteTree(e,t,r,n);return R(a,!0)}}function H(){const e=S.useParams(),t=k();return typeof t=="string"&&e["*"]!==void 0?{...e,[t]:e["*"]}:e}exports.assertNoDuplicateRoutes=c.assertNoDuplicateRoutes;exports.assertNoRouteConflicts=c.assertNoRouteConflicts;exports.buildRouteTree=c.buildRouteTree;exports.extractRoutePath=c.extractRoutePath;exports.normalizeSegment=c.normalizeSegment;exports.parseRouteSegments=c.parseRouteSegments;exports.routeSegmentToPath=c.routeSegmentToPath;exports.CatchAllParamProvider=w;exports.clearLazyCache=$;exports.clearMiddlewares=A;exports.configureRouter=v;exports.createLazyElement=p;exports.createRouteGenerator=B;exports.registerMiddleware=x;exports.resetRouterConfig=F;exports.treeToRoutes=R;exports.useParams=H;

package/dist/index.d.cts

@@ -0,0 +1,144 @@
+import { ComponentType } from 'react';
+import { default as default_2 } from 'react';
+import { ReactElement } from 'react';
+import { RouteObject } from 'react-router-dom';
+
+export declare function assertNoDuplicateRoutes(filePaths: string[], fileOptions?: RouteFileOptions): void;
+
+export declare function assertNoRouteConflicts(pageFiles: string[], notFoundFiles: string[], fileOptions?: RouteFileOptions): void;
+
+export declare function buildRouteTree(pages: Record<string, () => Promise<any>>, layouts: Record<string, any>, notFounds: Record<string, () => Promise<any>>, fileOptions?: RouteFileOptions): RouteNode;
+
+export declare function CatchAllParamProvider({ name, children, }: {
+    name: string;
+    children: default_2.ReactElement;
+}): default_2.ReactElement;
+
+/**
+ * Clear the module-level lazy component cache.
+ *
+ * `lazyComponentCache` is a package-wide singleton keyed by route path, so a
+ * `React.lazy` component created in one context (for example a previous test)
+ * is reused whenever another context requests the same key with a different
+ * loader. Exposing an explicit reset keeps that state from leaking, mirroring
+ * `clearMiddlewares` for the middleware registry.
+ */
+export declare function clearLazyCache(): void;
+
+export declare function clearMiddlewares(): void;
+
+export declare function configureRouter(config: RouterConfig): void;
+
+/**
+ * Create a lazy element wrapped with Suspense and apply middlewares
+ * @param loader - Function that loads the component
+ * @param cacheKey - Unique key for the cache
+ * @param routePath - Route path for middlewares
+ */
+export declare function createLazyElement(loader: () => Promise<any>, cacheKey: string, routePath?: string): default_2.ReactElement;
+
+/**
+ * Create a custom route generator function using your own files
+ *
+ * ⚠️ NOTE: This function is intended for advanced use only.
+ * For most cases, use the Vite plugin which automatically handles the paths.
+ *
+ * @example
+ * // In your configuration file
+ * const pages = import.meta.glob("../../pages/**\\/page.tsx");
+ * const layouts = import.meta.glob("../../pages/**\\/layout.tsx", { eager: true });
+ * const notFounds = import.meta.glob("../../pages/**\\/not-found.tsx");
+ *
+ * export const generateCustomRoutes = createRouteGenerator(pages, layouts, notFounds);
+ *
+ * // Then use it
+ * const routes = generateCustomRoutes();
+ */
+export declare function createRouteGenerator(pages: Record<string, () => Promise<any>>, layouts: Record<string, any>, notFounds: Record<string, () => Promise<any>>, fileOptions?: RouteFileOptions): () => RouteObject[];
+
+/**
+ * Extract the route path from a file path
+ * @example "../../app/blog/[id]/page.tsx" -> "blog/[id]"
+ * @example "../../app/page.tsx" -> ""
+ *
+ * `pagesDir` may be relative or absolute. The plugin resolves it relative to
+ * the Vite project root before passing it here.
+ * The prefix is stripped lazily so it matches the FIRST directory boundary
+ * that equals `pagesDir` (or the leading `app`/`pages` root marker when no
+ * `pagesDir` is supplied). A greedy match would instead consume up to the
+ * LAST such folder, which mangles routes that legitimately contain a nested
+ * folder named like the pages directory (e.g. `app/docs/app/page.tsx`).
+ */
+export declare function extractRoutePath(filePath: string, { pagesDir, pageFile, layoutFile, notFoundFile }?: RouteFileOptions): string;
+
+/**
+ * Normalize a Next.js segment to a React Router segment
+ * @example (admin) -> ""
+ * @example [id] -> :id
+ * @example [...slug] -> *
+ */
+export declare function normalizeSegment(segment: string): string;
+
+export declare function parseRouteSegments(routePath: string): RouteSegment[];
+
+export declare function registerMiddleware(pattern: RegExp, middleware: RouteMiddleware): void;
+
+/**
+ * Restore the module-level router configuration to its defaults.
+ *
+ * `configureRouter` merges, so it can never drop keys back to their initial
+ * state. A dedicated reset lets isolated contexts (for example tests) start
+ * from a known configuration instead of inheriting whatever was set globally
+ * before, matching the explicit reset offered by `clearMiddlewares`.
+ */
+export declare function resetRouterConfig(): void;
+
+export declare type RouteFileOptions = {
+    pagesDir?: string;
+    pageFile?: string;
+    layoutFile?: string;
+    notFoundFile?: string;
+};
+
+export declare type RouteMiddleware = (element: ReactElement) => ReactElement;
+
+export declare type RouteModuleLoader = () => Promise<{
+    default: ComponentType;
+}>;
+
+export declare type RouteNode = {
+    segment: string;
+    fullPath: string;
+    page?: RouteModuleLoader;
+    layout?: ComponentType;
+    notFound?: RouteModuleLoader;
+    children: Map<string, RouteNode>;
+};
+
+export declare type RouterConfig = {
+    loadingFallback?: React.ComponentType;
+    enableLazyLoading?: boolean;
+};
+
+export declare type RouteSegment = {
+    kind: "group";
+    name: string;
+} | {
+    kind: "static";
+    name: string;
+} | {
+    kind: "dynamic";
+    name: string;
+} | {
+    kind: "catchAll";
+    name: string;
+    optional: boolean;
+};
+
+export declare function routeSegmentToPath(segment: RouteSegment): string;
+
+export declare function treeToRoutes(node: RouteNode, isRoot?: boolean, currentPath?: string): RouteObject[];
+
+export declare function useParams<T extends Record<string, string | undefined> = Record<string, string | undefined>>(): T;
+
+export { }

package/dist/index.d.ts

@@ -5,6 +5,8 @@ import { RouteObject } from 'react-router-dom';
 
 export declare function assertNoDuplicateRoutes(filePaths: string[], fileOptions?: RouteFileOptions): void;
 
+export declare function assertNoRouteConflicts(pageFiles: string[], notFoundFiles: string[], fileOptions?: RouteFileOptions): void;
+
 export declare function buildRouteTree(pages: Record<string, () => Promise<any>>, layouts: Record<string, any>, notFounds: Record<string, () => Promise<any>>, fileOptions?: RouteFileOptions): RouteNode;
 
 export declare function CatchAllParamProvider({ name, children, }: {
@@ -12,6 +14,17 @@ export declare function CatchAllParamProvider({ name, children, }: {
     children: default_2.ReactElement;
 }): default_2.ReactElement;
 
+/**
+ * Clear the module-level lazy component cache.
+ *
+ * `lazyComponentCache` is a package-wide singleton keyed by route path, so a
+ * `React.lazy` component created in one context (for example a previous test)
+ * is reused whenever another context requests the same key with a different
+ * loader. Exposing an explicit reset keeps that state from leaking, mirroring
+ * `clearMiddlewares` for the middleware registry.
+ */
+export declare function clearLazyCache(): void;
+
 export declare function clearMiddlewares(): void;
 
 export declare function configureRouter(config: RouterConfig): void;
@@ -47,6 +60,14 @@ export declare function createRouteGenerator(pages: Record<string, () => Promise
  * Extract the route path from a file path
  * @example "../../app/blog/[id]/page.tsx" -> "blog/[id]"
  * @example "../../app/page.tsx" -> ""
+ *
+ * `pagesDir` may be relative or absolute. The plugin resolves it relative to
+ * the Vite project root before passing it here.
+ * The prefix is stripped lazily so it matches the FIRST directory boundary
+ * that equals `pagesDir` (or the leading `app`/`pages` root marker when no
+ * `pagesDir` is supplied). A greedy match would instead consume up to the
+ * LAST such folder, which mangles routes that legitimately contain a nested
+ * folder named like the pages directory (e.g. `app/docs/app/page.tsx`).
  */
 export declare function extractRoutePath(filePath: string, { pagesDir, pageFile, layoutFile, notFoundFile }?: RouteFileOptions): string;
 
@@ -58,8 +79,20 @@ export declare function extractRoutePath(filePath: string, { pagesDir, pageFile,
  */
 export declare function normalizeSegment(segment: string): string;
 
+export declare function parseRouteSegments(routePath: string): RouteSegment[];
+
 export declare function registerMiddleware(pattern: RegExp, middleware: RouteMiddleware): void;
 
+/**
+ * Restore the module-level router configuration to its defaults.
+ *
+ * `configureRouter` merges, so it can never drop keys back to their initial
+ * state. A dedicated reset lets isolated contexts (for example tests) start
+ * from a known configuration instead of inheriting whatever was set globally
+ * before, matching the explicit reset offered by `clearMiddlewares`.
+ */
+export declare function resetRouterConfig(): void;
+
 export declare type RouteFileOptions = {
     pagesDir?: string;
     pageFile?: string;
@@ -84,10 +117,26 @@ export declare type RouteNode = {
 
 export declare type RouterConfig = {
     loadingFallback?: React.ComponentType;
-    pagesDir?: string;
     enableLazyLoading?: boolean;
 };
 
+export declare type RouteSegment = {
+    kind: "group";
+    name: string;
+} | {
+    kind: "static";
+    name: string;
+} | {
+    kind: "dynamic";
+    name: string;
+} | {
+    kind: "catchAll";
+    name: string;
+    optional: boolean;
+};
+
+export declare function routeSegmentToPath(segment: RouteSegment): string;
+
 export declare function treeToRoutes(node: RouteNode, isRoot?: boolean, currentPath?: string): RouteObject[];
 
 export declare function useParams<T extends Record<string, string | undefined> = Record<string, string | undefined>>(): T;