@gulibs/vgrove-autoroutes/README.md

🚀 基于文件系统的自动路由生成 Vite 插件，完整支持 React Router v7+ 和现代化的路由模式

# VGrove AutoRoutes

> 🚀 零配置的文件系统自动路由生成器，为 React Router v7+ 打造

[![npm version](https://badge.fury.io/js/@gulibs%2Fvgrove-autoroutes.svg)](https://badge.fury.io/js/@gulibs%2Fvgrove-autoroutes)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ 为什么选择 VGrove AutoRoutes？

**告别手动路由配置的繁琐！** VGrove AutoRoutes 基于文件系统自动生成路由，让你专注于业务逻辑：

- 🔥 **零配置启动** - 放入文件即生成路由，无需手动配置
- ⚡ **完美热更新** - 文件变化实时同步，开发体验丝滑
- 🎯 **智能识别** - 自动区分页面、布局、数据加载等文件类型
- 📦 **代码分割** - 内置 React.lazy 支持，自动优化性能
- 🛡️ **类型安全** - 完整 TypeScript 支持，智能提示无忧

## 🚀 快速开始

### 安装

```bash
npm install @gulibs/vgrove-autoroutes
```

### 配置

```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import autoRoutes from '@gulibs/vgrove-autoroutes';

export default defineConfig({
  plugins: [
    react(),
    autoRoutes({
      dirs: [{ dir: './src/pages', baseRoute: '/' }],
      dynamic: true    // 启用代码分割
    })
  ]
});
```

### 创建页面

```
src/pages/
├── page.tsx                 # / 路由
├── about.page.tsx          # /about 路由  
├── users/
│   ├── page.tsx            # /users 路由
│   ├── loader.tsx          # 数据加载（不生成路由）
│   └── [id]/
│       ├── page.tsx        # /users/:id 路由
│       └── action.tsx      # 表单处理（不生成路由）
└── layout.tsx              # 根布局
```

### 使用路由

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

const router = createBrowserRouter(routes);

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <RouterProvider router={router} />
  </React.StrictMode>
);
```

## 📁 文件约定

### 路由文件（生成路由）

| 文件名 | 路由路径 | 说明 |
|--------|----------|------|
| `page.tsx` | `/` | 目录首页 |
| `about.page.tsx` | `/about` | 扁平风格页面 |
| `users.settings.page.tsx` | `/users/settings` | 多层路由 |
| `[id].page.tsx` | `/:id` | 动态路由 |
| `[...slug].page.tsx` | `/*` | 通配符路由 |
| `layout.tsx` | - | 嵌套布局组件 |

### 辅助文件（不生成路由）

| 文件名 | 功能 | 说明 |
|--------|------|------|
| `loader.tsx` | 数据加载 | 为同名路由提供数据 |
| `action.tsx` | 表单处理 | 处理 POST/PUT/DELETE 请求 |
| `middleware.ts` | 中间件 | 路由级别的中间件逻辑 |
| `error.tsx` | 错误边界 | 错误处理组件 |
| `loading.tsx` | 加载状态 | 加载指示器组件 |

## ⚙️ 配置选项

```typescript
interface AutoRoutesOptions {
  // 路由目录配置
  dirs: Array<{
    dir: string;           // 扫描目录
    baseRoute?: string;    // 基础路由前缀
    include?: string[];    // 包含模式
    exclude?: string[];    // 排除模式
  }>;
  
  // 路由模式
  routeMode?: 'flat' | 'nested';  // 默认: 'flat'
  
  // 动态导入
  dynamic?: boolean;              // 默认: false
  
  // 调试模式
  debug?: boolean;               // 默认: false
  
  // 全局排除
  exclude?: string[];
}
```

### 多目录配置

```typescript
autoRoutes({
  dirs: [
    { dir: './src/pages', baseRoute: '/' },
    { dir: './src/admin', baseRoute: '/admin' },
    { dir: './src/api', baseRoute: '/api' }
  ],
  dynamic: true,
  exclude: ['**/test/**', '**/*.test.*']
})
```

## 📝 实用示例

### 页面组件

```typescript
// src/pages/users/page.tsx
import { useLoaderData, Form } from 'react-router';

export default function UsersPage() {
  const { users } = useLoaderData();
  
  return (
    <div>
      <h1>用户管理</h1>
      {users.map(user => (
        <div key={user.id}>{user.name}</div>
      ))}
      
      <Form method="post">
        <input name="name" placeholder="用户名" />
        <button type="submit">添加用户</button>
      </Form>
    </div>
  );
}
```

### 数据加载器

```typescript
// src/pages/users/loader.tsx
import type { LoaderFunctionArgs } from 'react-router';

export default async function loader({ request }: LoaderFunctionArgs) {
  const users = await fetch('/api/users').then(res => res.json());
  return { users };
}

export function errorBoundary({ error }) {
  return (
    <div className="error">
      <h2>加载失败</h2>
      <p>{error.message}</p>
    </div>
  );
}
```

### 表单处理器

```typescript
// src/pages/users/action.tsx
import type { ActionFunctionArgs } from 'react-router';
import { redirect } from 'react-router';

export default async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const name = formData.get('name');
  
  await fetch('/api/users', {
    method: 'POST',
    body: JSON.stringify({ name }),
    headers: { 'Content-Type': 'application/json' }
  });
  
  return redirect('/users');
}
```

### 布局组件

```typescript
// src/pages/layout.tsx
import { Outlet, Link } from 'react-router';
import { Suspense } from 'react';

export default function RootLayout() {
  return (
    <div>
      <nav>
        <Link to="/">首页</Link>
        <Link to="/about">关于</Link>
        <Link to="/users">用户</Link>
      </nav>
      
      <main>
        <Suspense fallback={<div>加载中...</div>}>
          <Outlet />
        </Suspense>
      </main>
    </div>
  );
}
```

## 🔧 TypeScript 支持

添加类型声明以获得完整的智能提示：

```typescript
// vite-env.d.ts
/// <reference types="@gulibs/vgrove-autoroutes/react-routes" />
```

或在 `tsconfig.json` 中添加：

```json
{
  "compilerOptions": {
    "types": ["@gulibs/vgrove-autoroutes/react-routes"]
  }
}
```

## 🐛 故障排除

### 热更新不工作？

**✅ v0.0.164 已完全修复热更新问题！**

如果仍有问题：
- 确保文件在配置的目录中
- 检查文件命名是否符合约定
- 尝试重启开发服务器

### 路由没有生成？

检查以下几点：
- 文件名是否包含 `.page.tsx` 或为 `page.tsx`
- 文件是否被 `exclude` 规则排除
- 启用 `debug: true` 查看详细日志

### TypeScript 类型错误？

```typescript
// 添加类型声明
declare module '@gulibs/react-autopages' {
  export const routes: Array<RouteObject>;
}
```

## 🎉 最新更新

### v0.0.164 - 虚拟模块优化版本
- 🔥 **完全修复热更新** - 虚拟模块采用路径嵌入方式，避免时间戳冲突
- ⚡ **性能优化** - 减少不必要的模块重新创建
- 🛡️ **稳定性提升** - 热更新更加可靠和快速

### v0.0.163 - 稳定性增强
- 🐛 修复文件监听循环问题
- 🚀 优化缓存机制
- ✅ 完善错误处理

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

- [GitHub 仓库](https://github.com/gulibs/vite-plugin-react-auto-routes)
- [问题反馈](https://github.com/gulibs/vite-plugin-react-auto-routes/issues)

---

**🚀 立即体验零配置路由的便利！**

```bash
npm install @gulibs/vgrove-autoroutes
```

**如果这个项目对您有帮助，请给我们一个 ⭐ Star！**