Webpack Routes Plugin

基于文件系统的webpack约定式路由插件，自动生成路由配置，告别手写路由文件！

🚀 特性

• ✅ 约定式路由 - 基于文件系统自动生成路由配置
• ✅ 动态路由 - 支持 [id].jsx 格式的动态路由
• ✅ 嵌套路由 - 支持多级目录结构
• ✅ 自定义路由 - 可以添加不符合约定的自定义路由
• ✅ 热重载 - 开发模式下自动监听文件变化
• ✅ Meta信息提取 - 自动从JSDoc注释中提取页面meta信息
• ✅ TypeScript支持 - 支持 .ts 和 .tsx 文件
• ✅ 灵活配置 - 丰富的配置选项满足各种需求

📦 安装

npm install webpack-routes-plugin --save-dev

或者使用 yarn：

yarn add webpack-routes-plugin --dev

🎯 快速开始

1. 配置webpack

// webpack.config.js
const WebpackRoutesPlugin = require('webpack-routes-plugin');

module.exports = {
  // ... 其他配置
  plugins: [
    new WebpackRoutesPlugin({
      pagesDir: 'src/pages',          // 页面文件目录
      outputPath: 'src/routes.js',    // 生成的路由文件路径
      extensions: ['.js', '.jsx'],     // 支持的文件扩展名
    })
  ]
};

2. 创建页面文件

src/pages/
├── index.jsx          → /
├── about.jsx          → /about
├── blog/
│   ├── index.jsx      → /blog
│   └── [id].jsx       → /blog/:id
└── user/
    └── profile.jsx    → /user/profile

3. 使用生成的路由

// src/App.jsx
import React from 'react';
import { Routes, Route } from 'react-router-dom';
import routes from './routes';

function App() {
  return (
    <Routes>
      {routes.map((route, index) => (
        <Route
          key={index}
          path={route.path}
          element={<route.component />}
        />
      ))}
    </Routes>
  );
}

export default App;

📖 路由约定

基础路由

| 文件路径 | 生成路由 | | --- | --- | | pages/index.jsx | / | | pages/about.jsx | /about | | pages/contact.jsx | /contact |

嵌套路由

| 文件路径 | 生成路由 | | --- | --- | | pages/blog/index.jsx | /blog | | pages/blog/create.jsx | /blog/create | | pages/user/profile.jsx | /user/profile | | pages/user/settings.jsx | /user/settings |

动态路由

| 文件路径 | 生成路由 | 参数 | | --- | --- | --- | | pages/blog/[id].jsx | /blog/:id | { id } | | pages/user/[id]/profile.jsx | /user/:id/profile | { id } | | pages/[category]/[slug].jsx | /:category/:slug | { category, slug } |

⚙️ 配置选项

new WebpackRoutesPlugin({
  // 页面文件目录，默认为 'src/pages'
  pagesDir: 'src/pages',
  
  // 生成的路由文件路径，默认为 'src/routes.js'
  outputPath: 'src/routes.js',
  
  // 支持的文件扩展名
  extensions: ['.js', '.jsx', '.ts', '.tsx'],
  
  // 是否包含子目录，默认为 true
  includeSubdirectories: true,
  
  // 排除的文件或目录
  exclude: ['components', 'utils', '_app.js'],
  
  // 自定义路由配置
  customRoutes: [
    {
      path: '/custom',
      component: './src/components/CustomPage.jsx',
      name: 'custom',
      meta: {
        title: '自定义页面',
        requiresAuth: true
      }
    }
  ],
  
  // 是否生成TypeScript类型定义
  generateTypes: false
})

🏷️ Meta信息提取

插件会自动从JSDoc注释中提取页面meta信息：

/**
 * @title 用户资料
 * @description 查看和编辑用户个人信息
 * @auth true
 */
import React from 'react';

const UserProfile = () => {
  // ... 组件代码
};

export default UserProfile;

生成的路由配置会包含：

{
  path: '/user/profile',
  component: UserProfile,
  name: 'user-profile',
  meta: {
    title: '用户资料',
    description: '查看和编辑用户个人信息',
    requiresAuth: true
  }
}

🎨 生成的路由文件示例

// 此文件由 webpack-routes-plugin 自动生成，请勿手动修改
import Component0 from './pages/index.jsx';
import Component1 from './pages/about.jsx';
import Component2 from './pages/blog/index.jsx';
import Component3 from './pages/blog/[id].jsx';
import Component4 from './pages/user/profile.jsx';

const routes = [
{
  path: '/',
  component: Component0,
  name: 'home',
  meta: {"title":"首页","description":"欢迎来到我们的网站首页"}
},
{
  path: '/about',
  component: Component1,
  name: 'about',
  meta: {"title":"关于我们","description":"了解更多关于我们的信息"}
},
{
  path: '/blog',
  component: Component2,
  name: 'blog',
  meta: {"title":"博客列表","description":"查看所有博客文章"}
},
{
  path: '/blog/:id',
  component: Component3,
  name: 'blog-id',
  meta: {"title":"博客详情","description":"查看具体博客文章内容"},
  dynamic: true,
  params: ["id"]
},
{
  path: '/user/profile',
  component: Component4,
  name: 'user-profile',
  meta: {"title":"用户资料","description":"查看和编辑用户个人信息","requiresAuth":true}
}
];

export default routes;

🚦 使用React Router

与React Router完美集成：

import React from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import routes from './routes';

function App() {
  return (
    <BrowserRouter>
      <Routes>
        {routes.map((route, index) => (
          <Route
            key={index}
            path={route.path}
            element={<route.component />}
          />
        ))}
      </Routes>
    </BrowserRouter>
  );
}

export default App;

📂 项目结构示例

project/
├── src/
│   ├── pages/
│   │   ├── index.jsx
│   │   ├── about.jsx
│   │   ├── blog/
│   │   │   ├── index.jsx
│   │   │   └── [id].jsx
│   │   └── user/
│   │       ├── profile.jsx
│   │       └── settings.jsx
│   ├── components/
│   │   └── CustomPage.jsx
│   ├── routes.js          ← 自动生成
│   └── App.jsx
├── webpack.config.js
└── package.json

🔧 开发模式

在开发模式下，插件会自动监听页面文件的变化，并重新生成路由配置：

npm run dev

当你添加、删除或修改页面文件时，路由配置会自动更新，无需手动重启开发服务器。

📝 特殊文件

以下文件名会被自动跳过，不会生成路由：

• _app.jsx - 应用程序根组件
• _document.jsx - 文档组件
• _error.jsx - 错误页面组件
• 404.jsx - 404页面组件

🎭 自定义路由

除了约定式路由，你还可以添加自定义路由：

new WebpackRoutesPlugin({
  customRoutes: [
    {
      path: '/api-docs',
      component: './src/components/ApiDocs.jsx',
      name: 'api-docs',
      meta: {
        title: 'API文档',
        layout: 'docs'
      }
    }
  ]
})

🏃‍♂️ 运行示例

# 克隆项目
git clone https://github.com/js0205/webpack-routes-plugin.git

# 安装依赖
cd webpack-routes-plugin
npm install

# 运行示例
npm run dev

访问 http://localhost:8080 查看示例应用。

📊 版本历史

1.0.0

• 🎉 首次发布
• ✅ 基础约定式路由功能
• ✅ 动态路由支持
• ✅ Meta信息提取
• ✅ 热重载支持

🆘 问题反馈

如果你在使用过程中遇到问题，请：

1. 查看文档和示例代码
2. 搜索已有的 Issues
3. 如果没有找到解决方案，请创建新的 Issue

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发设置

# 克隆项目
git clone https://github.com/js0205/webpack-routes-plugin.git

# 安装依赖
cd webpack-routes-plugin
npm install

# 运行示例
npm run dev

提交规范

请遵循 Conventional Commits 规范。

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

如果这个插件对你有帮助，请给个 ⭐️ 支持一下！