file system based routing
npm install @feoe/fs-router


基于文件的约定式路由
为 React 应用提供类型安全的路由解决方案
- 🚀 约定式路由 - 基于文件系统的路由约定,零配置即可使用
- 📝 最佳实践 - 自带 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 或更高版本
根据你使用的构建工具,选择对应的配置方式:
#### 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'
})
]
}
`
在 src/routes 目录下创建页面文件:
``
src/routes/
├── layout.tsx # 根布局 (必须配置)
├── page.tsx # 首页 (/)
├── about/
│ └── page.tsx # 关于页面 (/about)
└── users/
├── layout.tsx # 用户模块布局
├── page.tsx # 用户列表 (/users)
└── [id]/
└── page.tsx # 用户详情 (/users/:id)
`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 (
欢迎使用 @feoe/fs-router
这是基于文件的约定式路由示例
)
}
`$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 - 代码分割实现