next-fs-routes

Next.js-style file-structure routing for Vite apps using React Router data routes.

Install

pnpm add next-fs-routes

Usage

import {
  createViteFileRoutesRouter,
  type FileRouteModule,
} from "next-fs-routes";

const routeModules = import.meta.glob<FileRouteModule>(
  "./routes/**/{layout,page}.tsx",
);

export const router = createViteFileRoutesRouter({
  routeModules,
  validateInDev: import.meta.env.DEV,
});

Conventions

• routes/layout.tsx creates the root layout route.
• routes/page.tsx creates the root index route.
• routes/<segment>/page.tsx creates /<segment>.
• routes/<segment>/layout.tsx creates a nested layout route.
• routes/(group)/<segment>/page.tsx creates /<segment> without adding the group folder to the URL.
• routes/[id]/page.tsx becomes /:id.
• routes/not-found/page.tsx becomes the catch-all *.

Route modules must default export a React component. They may also export loader, action, and ErrorBoundary.

Route groups affect folders only, not filenames, so the recommended Vite glob stays explicit:

import.meta.glob<FileRouteModule>("./routes/**/{layout,page}.tsx");

API

createFileRoutes(routeModules, options?)

Builds React Router RouteObject[] values from Vite route modules.

validateFileRouteModules(routeModules, options?)

Loads each route module and fails fast when a module is invalid.

createViteFileRoutesRouter({ routeModules, validateInDev, options })

Convenience helper that wraps createBrowserRouter(createFileRoutes(...)).

Options

type FileRouteOptions = {
  routesRoot?: string;
  notFoundSegment?: string;
};

• routesRoot defaults to ./routes
• notFoundSegment defaults to not-found