✨ 特性

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

📦 安装

``bash
npm install @feoe/fs-router -D


或

yarn add @feoe/fs-router -D

或

pnpm add @feoe/fs-router -D
`

系统要求

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

🚀 快速开始

$3

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

#### Vite

`typescript
// vite.config.ts
import { defineConfig } from 'vite'
import { FileBasedRouterVite as fileBasedRouter } from '@feoe/fs-router/vite'

export default defineConfig({
plugins: [
fileBasedRouter({
routesDirectory: 'src/routes',
generatedRoutesPath: 'src/routes.tsx'
})
]
})
`

#### Rspack

`javascript
// rspack.config.js
const { FileBasedRouterRspack as fileBasedRouter } = require('@feoe/fs-router/rspack')

module.exports = {
plugins: [
fileBasedRouter({
routesDirectory: 'src/routes',
generatedRoutesPath: 'src/routes.tsx'
})
]
}
`

#### Webpack

`javascript
// webpack.config.js
const { FileBasedRouterWebpack as fileBasedRouter } = require('@feoe/fs-router/webpack')

module.exports = {
plugins: [
fileBasedRouter({
routesDirectory: 'src/routes',
generatedRoutesPath: 'src/routes.tsx'
})
]
}
`

$3

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

`
src/routes/
├── layout.tsx # 根布局 (必须配置)
├── page.tsx # 首页 (/)
├── about/
│ └── page.tsx # 关于页面 (/about)
└── users/
├── layout.tsx # 用户模块布局
├── page.tsx # 用户列表 (/users)
└── [id]/
└── page.tsx # 用户详情 (/users/:id)
`

$3

`tsx
// src/routes/layout.tsx
import { Outlet } from 'react-router-dom'

export default function Layout() {
return (



)
}
`

$3

`tsx
// src/routes/page.tsx
export default function HomePage() {
return (



)
}
`

$3

`tsx
// src/main.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import { createBrowserRouter, RouterProvider } from 'react-router-dom'
import { routes } from './routes'

const router = createBrowserRouter(routes)

ReactDOM.createRoot(document.getElementById('root')!).render(



)
`

📖 核心概念

$3

基于文件系统的路由约定，通过文件和目录结构自动生成路由配置：

- page.tsx - 页面组件
- page.data.ts - 页面数据加载 loader
- layout.tsx - 布局组件
- layout.data.ts - 布局数据加载 loader
- loading.tsx - 加载状态组件
- error.tsx - 错误边界组件
- loader.ts - 数据加载器

$3

使用方括号创建动态路由：

`
src/routes/
├── users/
│ ├── [id]/
│ │ └── page.tsx # /users/:id
│ └── [id]/
│ └── edit/
│ └── page.tsx # /users/:id/edit
`

$3

自动生成类型定义，提供完整的 TypeScript 支持：

`tsx
import { useNavigate } from 'react-router-dom'

const navigate = useNavigate()

// 类型安全的导航
navigate('/users/123') // ✅ 正确
navigate('/invalid') // ❌ TypeScript 错误
``

🎯 示例

查看完整的示例项目：

- Vite + Keep Alive Tabs - 带有标签页保活功能的 Vite 应用
- Rspack Admin Dashboard - 基于 Rspack 的管理后台应用

📚 文档

完整的文档和 API 参考请访问：https://fs-router.feoe.dev

- 介绍
- 快速开始
- 基础用法
- 高级特性
- API 参考

🤝 贡献

欢迎贡献代码！请查看 贡献指南 了解如何参与项目开发。

🙏 致谢

本项目的灵感来源于以下优秀的开源项目：

- Modern.js - 约定式路由设计参考
- Next.js App Router - 文件系统路由约定
- Remix File System Route Convention
- @TanStack/react-router - 类型安全实现参考
- @loadable/component - 代码分割实现

📄 许可证

MIT © feoe