快速开始

欢迎使用 @feoe/fs-router，这是一个基于文件的编译时约定式路由库，为 React Router 应用提供类型安全的路由解决方案。

特性概览

🚀 约定式路由 - 基于文件系统的路由约定，零配置即可使用
📝 最佳实践 - 自带 React-Router v6+ BrowserRouter/DataRouter 组件模块化
🔒 类型安全 - 完整的 TypeScript 支持，提供类型安全的导航
⚡ 高性能 - 支持代码分割和懒加载，优化应用性能
🔧 多构建工具支持 - 支持 Vite、Webpack、Rspack 等主流构建工具
🔄 热更新 - 开发时文件变更自动重新生成路由

安装

使用你喜欢的包管理器安装：

npm

1npm install @feoe/fs-router -D

yarn

1yarn add @feoe/fs-router

pnpm

1pnpm add @feoe/fs-router

系统要求

Node.js 16.0 或更高版本
React 18.0 或更高版本
TypeScript 4.5 或更高版本（可选，但推荐）
React-Router 6.0 或更高版本

基础配置

根据你使用的构建工具，选择对应的配置方式：

Vite

使用包管理器快速创建 Vite 应用，更多模版见 Scaffolding Your First Vite Project：

1npm create vite@latest

修改 vite.config.js 配置，集成 @feoe/fs-router/vite 插件：

1// vite.config.ts
2import { defineConfig } from 'vite'
3import react from '@vitejs/plugin-react'
4import { FileBasedRouterVite as fileBasedRouter } from '@feoe/fs-router/vite'
5
6export default defineConfig({
7  plugins: [
8    react(),
9    fileBasedRouter({
10      routesDirectory: 'src/routes',
11      generatedRoutesPath: 'src/routes.tsx'
12    })
13  ]
14})

Rspack

使用包管理器快速创建 Rspack 应用：

1npm create rspack@latest

修改 rspack.config.js 配置，集成 @feoe/fs-router/rspack 插件：

1// rspack.config.js
2const { FileBasedRouterRspack as fileBasedRouter } = require('@feoe/fs-router/rspack')
3
4module.exports = {
5  plugins: [
6    fileBasedRouter({
7      routesDirectory: 'src/routes',
8      generatedRoutesPath: 'src/routes.tsx'
9    })
10  ]
11}

Rsbuild

使用包管理器快速创建 Rsbuild 应用，更多模版见 Templates：

1npm create rsbuild@latest

修改 rsbuild.config.ts 配置，集成 @feoe/fs-router/rspack 插件：

1// rsbuild.config.js
2import { FileBasedRouterRspack } from "@feoe/fs-router/rspack";
3
4const pluginRouter = FileBasedRouterRspack({
5	routesDirectory: 'src/routes',
6  generatedRoutesPath: 'src/routes.tsx'
7});
8
9export default defineConfig({
10	tools: {
11		rspack: {
12			plugins: [pluginRouter],
13		},
14	},
15});

Webpack

1// webpack.config.js
2const { FileBasedRouterWebpack as fileBasedRouter } = require('@feoe/fs-router/webpack')
3
4module.exports = {
5  plugins: [
6    fileBasedRouter({
7      routesDirectory: 'src/routes',
8      generatedRoutesPath: 'src/routes.tsx'
9    })
10  ]
11}

创建第一个路由

在 src/routes 目录下创建页面文件：

src/routes/
├── layout.tsx          # 根布局 (必须配置)
├── page.tsx            # 首页 (/)
└── about/
    └── page.tsx        # 关于页面 (/about)

创建根布局文件 src/routes/layout.tsx：

1import { Outlet } from 'react-router-dom'
2
3export default function Layout() {
4  return (
5    <div>
6      <nav>
7        <a href="/">首页</a>
8        <a href="/about">关于</a>
9      </nav>
10      <main>
11        <Outlet />
12      </main>
13    </div>
14  )
15}

创建首页 src/routes/page.tsx：

1export default function HomePage() {
2  return (
3    <div>
4      <h1>欢迎使用 fs-router</h1>
5      <p>这是基于文件的约定式路由示例</p>
6    </div>
7  )
8}

创建关于页面 src/routes/about/page.tsx：

1export default function AboutPage() {
2  return (
3    <div>
4      <h1>关于我们</h1>
5      <p>这是关于页面</p>
6    </div>
7  )
8}

在你的应用入口文件中使用生成的路由：

1// src/main.tsx
2import React from 'react'
3import ReactDOM from 'react-dom/client'
4import { createBrowserRouter, RouterProvider } from 'react-router-dom'
5import { routes } from './routes'
6
7// 此处示例，使用 DataRouter
8const router = createBrowserRouter(routes)
9
10ReactDOM.createRoot(document.getElementById('root')!).render(
11  <React.StrictMode>
12    <RouterProvider router={router} />
13  </React.StrictMode>
14)

恭喜！你已经成功创建了第一个基于文件的路由应用。

页面导航

快速开始#

特性概览#

安装#

npm#

yarn#

pnpm#

系统要求#

基础配置#

Vite#

Rspack#

Rsbuild#

Webpack#

创建第一个路由#