@lightfish/router

基于文件系统的 React Router 路由生成工具。将 Vite import.meta.glob 导入的页面模块映射，自动转换为 react-router-dom 的 RouteObject[]。

安装

pnpm add @lightfish/router

peerDependencies 要求：

• react >= 18
• react-router-dom 6.21.1

快速开始

1. 按文件系统约定组织页面

src/pages/
├── index.tsx            # 首页 /
├── layout.tsx           # 全局布局（可选）
├── settings.tsx         # 首页元信息（可选）
├── users/
│   ├── index.tsx        # /users
│   ├── layout.tsx       # users 目录专属布局（可选）
│   ├── 404.tsx          # users 下的 404（可选）
│   └── [id]/
│       ├── index.tsx    # /users/:id
│       └── settings.tsx # /users/:id 的页面元信息
└── components/          # 被默认忽略，不生成路由
    └── UserCard.tsx

2. 在 Vite 项目中配合 import.meta.glob 使用

// src/router.tsx
import { createFileRoutes } from "@lightfish/router";
import { createBrowserRouter, RouterProvider } from "react-router-dom";

// 导入所有页面模块（eager 模式确保路由表立即可用）
const pages = import.meta.glob("/src/pages/**/*.tsx", { eager: true }) as Record<string, any>;
const layouts = import.meta.glob("/src/pages/**/layout.tsx", { eager: true }) as Record<string, any>;
const notFounds = import.meta.glob("/src/pages/**/404.tsx", { eager: true }) as Record<string, any>;
const settings = import.meta.glob("/src/pages/**/settings.tsx", { eager: true }) as Record<string, any>;

const routeObjects = createFileRoutes({
  pages,
  layouts,
  notFounds,
  settings,
  // 以下为默认值，可按需覆盖：
  // rootDir: "/src/pages",
  // ignoredSegmentNames: ["components", "models"],
});

const router = createBrowserRouter(routeObjects);

export function AppRouter() {
  return <RouterProvider router={router} />;
}

3. 挂载到应用入口

// src/main.tsx
import { createRoot } from "react-dom/client";
import { AppRouter } from "./router";

createRoot(document.getElementById("root")!).render(<AppRouter />);

文件路由约定

| 文件名 | 作用 | 说明 | |---|---|---| | index.tsx | 页面组件 | 必选。每个目录的默认页面。 | | layout.tsx | 布局组件 | 可选。包裹当前目录及其子路由。组件内部通过 <Outlet /> 渲染子路由。 | | 404.tsx | 404 页面 | 可选。当前目录下的未匹配路径兜底。 | | settings.tsx | 页面元信息 | 可选。default 导出 { title?: string }，组件挂载时自动设置 document.title。 |

动态路由

文件或目录名中的 [param] 语法会被转换为 react-router-dom 的 :param 路径参数：

| 文件路径 | 生成的路由 path | |---|---| | src/pages/users/[id]/index.tsx | /users/:id | | src/pages/posts/[postId]-[slug]/index.tsx | /posts/:postId-:slug |

忽略目录

路径中包含 ignoredSegmentNames（默认 ["components", "models"]）中任意目录名的文件不会生成路由。允许你将辅助组件就近放在页面目录下：

src/pages/users/
├── index.tsx          # ✅ 生成路由 /users
└── components/
    └── UserTable.tsx  # ❌ 忽略，不生成路由

API

createFileRoutes(options): RouteObject[]

核心函数，接收配置对象，返回 react-router-dom 的 RouteObject[]。

CreateFileRoutesOptions

| 字段 | 类型 | 默认值 | 说明 | |---|---|---|---| | pages | Record<string, FileRouteModule> | 必填 | import.meta.glob 导入的页面模块映射。key 为文件路径，value 为模块对象。 | | layouts | Record<string, FileRouteModule> | {} | layout 模块映射。 | | notFounds | Record<string, FileRouteModule> | {} | 404 模块映射。 | | settings | Record<string, FileRouteSettingsModule> | {} | 页面元信息模块映射。 | | rootDir | string | "/src/pages" | 页面文件的根目录，会从文件路径中去掉此前缀。 | | ignoredSegmentNames | string[] | ["components", "models"] | 需要忽略的目录名列表。 | | commonLayout | FileRouteComponent | 内置 DefaultLayout | 全局公共布局组件。当某目录无 layout.tsx 时使用。 | | commonNotFound | FileRouteComponent | 内置 DefaultNotFound | 全局公共 404 组件。当某目录无 404.tsx 时使用。 |

routeSegmentToPath(segment: string): string

将文件路由的动态段语法 [param] 转换为 :param。也可单独使用。

License

MIT