unplugin-convention-routes

<a href="https://www.npmjs.org/package/unplugin-convention-routes"> <img src="https://img.shields.io/npm/v/unplugin-convention-routes.svg" alt="npm version"> </a> <a href="https://npmcharts.com/compare/unplugin-convention-routes?minimal=true"> <img src="https://img.shields.io/npm/dm/unplugin-convention-routes.svg" alt="npm downloads"> </a> unplugin-convention-routes 🔥 基于文件系统的约定式路由解决方案。 🔥 基于 `unplugin` 开发，支持 `Vite` 和 `Rspack` 构建工具，同时支持 `React` 和 `Vue` 框架。 ⚡️ 使用 `import.meta.glob` (Vite) 和 `import.meta.webpackContext` (Rspack) 实现零运行时依赖，自动支持 HMR。 *** ## 📦 安装 ```bash pnpm i unplugin-convention-routes ``` ## 🚀 使用 ### Vite ```ts // vite.config.ts import Pages from "unplugin-convention-routes/vite" export default defineConfig({ plugins: [ Pages({ resolver: "vue" }), // 或 'react' ], }) ``` ### Rspack ```ts // rsbuild.config.ts import Pages from "unplugin-convention-routes/rspack" export default defineConfig({ tools: { rspack: { plugins: [ Pages({ resolver: "vue" }), // 或 'react' ], }, }, }) ``` ## 📖 路由约定 ### 文件命名规则 | 文件名 | 路由路径 | | ------------------- | ----------------- | | `index.vue` | `/` | | `about.vue` | `/about` | | `about/index.vue` | `/about` | | `blog/[id].vue` | `/blog/:id` | | `blog/[...all].vue` | `/blog/:all(.*)*` | ### Vue 使用 ```ts // env.d.ts /// <reference types="unplugin-convention-routes/client-vue" /> ``` ```ts import { createRouter, createWebHistory } from "vue-router" // main.ts import routes from "~pages" const router = createRouter({ history: createWebHistory(), routes, }) ``` ### React 使用 ```ts // env.d.ts /// <reference types="unplugin-convention-routes/client-react" /> ``` ```tsx import { BrowserRouter, useRoutes } from "react-router-dom" // main.tsx import routes from "~react-pages" function App() { return useRoutes(routes) } createRoot(document.getElementById("root")!).render( <BrowserRouter> <App /> </BrowserRouter> ) ``` ## ⚙️ 配置选项 ### 完整类型定义 ```ts interface UserOptions { /** 路由解析器类型（必填） */ resolver: "vue" | "react" /** 页面目录配置 */ dirs?: string | PageDir[] /** 文件扩展名 */ extensions?: string[] /** 排除的文件模式 */ exclude?: string[] /** 导入路径风格 */ importPath?: "absolute" | "relative" /** 路径大小写敏感 */ caseSensitive?: boolean /** 路由名称分隔符 */ routeNameSeparator?: string /** 扩展路由配置的钩子函数 */ extendRoute?: (route: any, parent: any | undefined) => any | void /** 路由生成后的钩子函数 */ onRoutesGenerated?: (routes: any[]) => Awaitable<any[] | void> /** 客户端代码生成后的钩子函数 */ onClientGenerated?: (clientCode: string) => Awaitable<string | void> } interface PageDir { /** 目录路径 */ dir: string /** 基础路由前缀 */ baseRoute?: string /** 文件匹配模式 */ filePattern?: string } ``` ### 基础配置选项 | 选项 | 说明 | 默认值 | | -------------------- | ------------------------------- | ---------------------------------------------------------------- | | `resolver` | 框架类型，支持 `vue` 或 `react` | **必填** | | `dirs` | 页面目录配置，支持字符串或数组格式 | `'src/pages'` | | `extensions` | 文件扩展名列表 | Vue: `['vue', 'ts', 'js']` / React: `['tsx', 'jsx', 'ts', 'js']` | | `exclude` | 排除的文件模式列表 | `['node_modules', '.git', '**/__*__/**', '**/components/**', '**/components.*']` | | `caseSensitive` | 路径是否大小写敏感 | `false` | | `routeNameSeparator` | 路由名称分隔符 | `'-'` | | `importPath` | 导入路径风格，`absolute` 或 `relative` | `'relative'` | --- ### `resolver`（必填）指定路由解析器类型，决定生成的路由代码格式。 ```ts Pages({ resolver: "vue", // 生成 Vue Router 格式的路由 }) Pages({ resolver: "react", // 生成 React Router 格式的路由 }) ``` --- ### `dirs` 配置页面目录，支持字符串或数组格式。 #### 单目录配置（字符串） ```ts Pages({ resolver: "vue", dirs: "src/pages", // 默认值 }) ``` #### 多目录配置（数组）当项目有多个页面目录时，可以使用数组配置： ```ts Pages({ resolver: "vue", dirs: [ // 主页面目录 { dir: "src/pages", baseRoute: "" }, // 功能模块页面目录，所有路由添加 /features 前缀 { dir: "src/features/**/pages", baseRoute: "features" }, // 管理后台页面目录，所有路由添加 /admin 前缀 { dir: "src/admin/pages", baseRoute: "admin" }, ], }) ``` **`PageDir` 配置项说明：** | 属性 | 说明 | 示例 | | ------------ | -------------------- | ----------------------- | | `dir` | 目录路径，支持 glob 模式 | `'src/pages'` | | `baseRoute` | 基础路由前缀，所有路由会添加此前缀 | `'admin'` → `/admin/...` | | `filePattern` | 文件匹配模式，用于进一步筛选文件（可选） | `'**/*.vue'` | --- ### `extensions` 指定要识别的文件扩展名。 ```ts Pages({ resolver: "vue", extensions: ["vue"], // 只识别 .vue 文件 }) Pages({ resolver: "react", extensions: ["tsx", "jsx"], // 只识别 .tsx 和 .jsx 文件 }) ``` --- ### `exclude` 排除不需要生成路由的文件或目录。支持基本的 glob 模式匹配。 **支持的通配符：** | 通配符 | 说明 | 示例 | | ------ | ---- | ---- | | `**` | 匹配任意层级的目录和文件 | `**/components/**` 匹配任意层级的 components 目录 | | `*` | 匹配单个路径段中的任意字符（不包括 `/`） | `*.test.*` 匹配 `foo.test.ts` | | `?` | 匹配单个字符（不包括 `/`） | `file?.vue` 匹配 `file1.vue` | > ⚠️ **注意**：不支持 minimatch 的高级功能，如否定模式 `!`、花括号扩展 `{a,b}` 等。 **默认排除列表：** - `node_modules` - 依赖目录 - `.git` - Git 目录 - `**/__*__/**` - 测试相关目录（如 `__tests__`、`__mocks__`） - `**/components/**` - components 目录 - `**/components.*` - components 文件（如 `components.vue`、`components.tsx`） ```ts // 自定义排除列表（会覆盖默认值） Pages({ resolver: "vue", exclude: [ "node_modules", ".git", "**/__*__/**", "**/components/**", "**/*.test.*", // 排除测试文件 "**/*.spec.*", ], }) ``` --- ### `importPath` 控制组件导入路径的风格。 | 值 | 说明 | 示例 | | ----------- | ------------------------ | ----------------------------------------- | | `'relative'` | 相对路径（默认） | `'./pages/index.vue'` | | `'absolute'` | 绝对路径（基于项目根目录） | `'/src/pages/index.vue'` | ```ts Pages({ resolver: "vue", importPath: "absolute", // 使用绝对路径 }) ``` --- ### `caseSensitive` 控制路由路径是否大小写敏感。 ```ts Pages({ resolver: "vue", caseSensitive: true, // /About 和 /about 是不同的路由 }) ``` --- ### `routeNameSeparator` 设置路由名称的分隔符，用于从文件路径生成路由名称。 ```ts // 文件路径: src/pages/blog/[id].vue // 默认分隔符 '-': 路由名称为 'blog-id' Pages({ resolver: "vue", routeNameSeparator: "_", // 路由名称变为 'blog_id' }) ``` --- ### 高级钩子函数 #### `extendRoute` 扩展或修改单个路由配置。在每个路由生成时调用。 ```ts Pages({ resolver: "vue", extendRoute: (route, parent) => { // 为所有路由添加 meta 信息 route.meta = { ...route.meta, title: route.name, } // 为特定路由添加额外配置 if (route.path === "/admin") { route.meta = { requiresAuth: true } } // 返回修改后的路由（或返回 void 保持原引用） return route }, }) ``` **参数说明：** - `route` - 当前路由配置对象 - `parent` - 父路由配置（如果是嵌套路由） --- #### `onRoutesGenerated` 在所有路由生成完成后调用，可以批量修改路由数组。 ```ts Pages({ resolver: "vue", onRoutesGenerated: async (routes) => { // 添加全局路由（如 404 页面） routes.push({ path: "/:pathMatch(.*)*", name: "NotFound", component: () => import("./src/pages/404.vue"), }) // 过滤掉某些路由 return routes.filter(route => !route.path.startsWith("/draft")) }, }) ``` --- #### `onClientGenerated` 在客户端代码生成完成后调用，可以修改最终生成的代码字符串。 ```ts Pages({ resolver: "vue", onClientGenerated: (clientCode) => { // 在代码开头添加注释 const header = "// 自动生成的路由文件，请勿手动修改\n" return header + clientCode }, }) ``` --- ## 🔨 示例项目 - [Vite + Vue](./examples/vite-vue) - [Vite + React](./examples/vite-react) - [rsbuild + Vue](./examples/rsbuild-vue) - [rsbuild + React](./examples/rsbuild-react) ## 友情链接 - [unplugin](https://github.com/unjs/unplugin) - [vite-plugin-pages](https://github.com/hannoeru/vite-plugin-pages)