webpack-routes-plugin/README.md

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

# Webpack Routes Plugin

![npm version](https://img.shields.io/npm/v/webpack-routes-plugin.svg)
![license](https://img.shields.io/npm/l/webpack-routes-plugin.svg)
![downloads](https://img.shields.io/npm/dm/webpack-routes-plugin.svg)

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

## 🚀 特性

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

## 📦 安装

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

或者使用 yarn：

```bash
yarn add webpack-routes-plugin --dev
```

## 🎯 快速开始

### 1. 配置webpack

```javascript
// 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. 使用生成的路由

```javascript
// 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 }` |

## ⚙️ 配置选项

```javascript
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信息：

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

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

export default UserProfile;
```

生成的路由配置会包含：

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

## 🎨 生成的路由文件示例

```javascript
// 此文件由 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完美集成：

```javascript
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
```

## 🔧 开发模式

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

```bash
npm run dev
```

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

## 📝 特殊文件

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

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

## 🎭 自定义路由

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

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

## 🏃‍♂️ 运行示例

```bash
# 克隆项目
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](https://github.com/js0205/webpack-routes-plugin/issues)
3. 如果没有找到解决方案，请创建新的 Issue

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 开发设置

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

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

# 运行示例
npm run dev
```

### 提交规范

请遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范。

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

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