@gulibs/vgrove-core/README.md

VGrove CLI - A unified development tool for React applications with auto-routes and i18n

# VGrove Core

> VGrove 生态系统的核心构建工具和配置管理器，提供统一的开发体验

## 🚀 特性

- **零配置**: 开箱即用的 Vite 配置和构建流程
- **智能集成**: 自动集成 VGrove UI 和 AutoRoutes
- **多框架支持**: 支持 React + SWC 的高性能构建
- **UI 框架检测**: 自动检测和配置 HeroUI/Tailwind CSS
- **开发服务器**: 内置开发服务器和热更新
- **构建优化**: 生产环境构建优化和代码分割
- **TypeScript**: 完整的类型支持

## 📦 安装

```bash
npm install @gulibs/vgrove-core
# 或
pnpm add @gulibs/vgrove-core
# 或
yarn add @gulibs/vgrove-core
```

### 全局安装 CLI

```bash
npm install -g @gulibs/vgrove-core
# 或
pnpm add -g @gulibs/vgrove-core
```

## 🎯 快速开始

### 1. 创建配置文件

```typescript
// vgrove.config.ts
import { defineConfig } from '@gulibs/vgrove-core';

export default defineConfig({
  // VGrove 特定配置
  vgrove: {
    // 路由配置
    routes: {
      dirs: [
        {
          dir: './src/pages',
          baseRoute: '/'
        }
      ],
      routeMode: 'flat',
      debug: true
    },
    
    // UI 框架配置
    ui: {
      framework: 'heroui' // 'heroui' | 'none'
    },
    
    // 国际化配置
    i18n: {
      locales: ['zh-CN', 'en-US'],
      defaultLocale: 'zh-CN',
      debug: false
    },
    
    // 构建配置
    build: {
      target: 'es2020',
      outDir: 'dist',
      sourcemap: true,
      minify: 'esbuild'
    }
  },
  
  // 标准 Vite 配置（可选）
  vite: {
    server: {
      port: 3000
    },
    resolve: {
      alias: {
        '@components': './src/components'
      }
    }
  }
});
```

### 2. 使用 CLI

```bash
# 开发模式
vgrove dev

# 构建生产版本
vgrove build

# 预览构建结果
vgrove preview

# 显示帮助
vgrove --help
```

### 3. 编程式使用

```typescript
// vite.config.ts
import { createViteConfig } from '@gulibs/vgrove-core';
import groveConfig from './vgrove.config';

export default createViteConfig(groveConfig);
```

## ⚙️ 配置选项

### VGrove 配置

```typescript
interface VGroveConfig {
  /** VGrove 特定配置 */
  vgrove?: {
    /** 路由配置 */
    routes?: AutoRoutesOptions;
    /** UI 框架配置 */
    ui?: UIConfig;
    /** 国际化配置 */
    i18n?: I18nConfig;
    /** 构建配置 */
    build?: BuildConfig;
  };
  /** 标准 Vite 配置 */
  vite?: UserConfig;
}
```

### 路由配置

```typescript
interface AutoRoutesOptions {
  /** 路由目录 */
  dirs: RouteOption[];
  /** 路由模式 */
  routeMode?: 'flat' | 'nested';
  /** 启用缓存 */
  cache?: boolean;
  /** 调试模式 */
  debug?: boolean;
}

interface RouteOption {
  /** 扫描目录 */
  dir: string;
  /** 基础路由 */
  baseRoute: string;
  /** 包含模式 */
  include?: string[];
  /** 排除模式 */
  exclude?: string[];
}
```

### UI 框架配置

```typescript
interface UIConfig {
  /** UI 框架类型 */
  framework?: 'heroui' | 'none';
}
```

### 国际化配置

```typescript
interface I18nConfig {
  /** 支持的语言 */
  locales?: string[];
  /** 默认语言 */
  defaultLocale?: string;
  /** 调试模式 */
  debug?: boolean;
}
```

### 构建配置

```typescript
interface BuildConfig {
  /** 构建目标 */
  target?: string;
  /** 输出目录 */
  outDir?: string;
  /** 源码映射 */
  sourcemap?: boolean;
  /** 代码压缩 */
  minify?: boolean | 'esbuild' | 'terser';
}
```

## 🔧 高级配置

### 多环境配置

```typescript
// vgrove.config.ts
import { defineConfig } from '@gulibs/vgrove-core';

export default defineConfig(({ command, mode }) => {
  const isDev = command === 'serve';
  const isProd = mode === 'production';
  
  return {
    vgrove: {
      routes: {
        debug: isDev, // 开发环境启用调试
        dirs: [
          {
            dir: './src/pages',
            baseRoute: '/'
          }
        ]
      },
      build: {
        sourcemap: isDev, // 开发环境启用源码映射
        minify: isProd // 生产环境启用压缩
      }
    },
    vite: {
      server: {
        port: isDev ? 3000 : undefined
      }
    }
  };
});
```

### 自定义插件集成

```typescript
// vgrove.config.ts
import { defineConfig } from '@gulibs/vgrove-core';
import { someCustomPlugin } from './plugins/custom-plugin';

export default defineConfig({
  vgrove: {
    // VGrove 配置
  },
  vite: {
    plugins: [
      // 自定义插件会与 VGrove 内置插件合并
      someCustomPlugin()
    ]
  }
});
```

### HeroUI 自动配置

VGrove Core 会自动检测项目中的 HeroUI 依赖：

```json
// package.json
{
  "dependencies": {
    "@heroui/react": "^2.0.0",
    "@tailwindcss/vite": "^4.0.0"
  }
}
```

当检测到这些依赖时，会自动：
- 启用 Tailwind CSS Vite 插件
- 配置 HeroUI 相关的构建选项
- 优化 CSS 处理流程

## 📁 项目结构

推荐的项目结构：

```
my-vgrove-app/
├── src/
│   ├── pages/              # 路由页面
│   │   ├── index.page.tsx
│   │   └── about.page.tsx
│   ├── components/         # 组件
│   ├── hooks/             # React Hooks
│   ├── utils/             # 工具函数
│   └── main.tsx           # 应用入口
├── public/                # 静态资源
├── vgrove.config.ts       # VGrove 配置
├── package.json
└── tsconfig.json
```

## 🚀 CLI 命令

### 开发命令

```bash
# 启动开发服务器
vgrove dev

# 指定端口
vgrove dev --port 8080

# 指定主机
vgrove dev --host 0.0.0.0
```

### 构建命令

```bash
# 构建生产版本
vgrove build

# 构建并分析包大小
vgrove build --analyze

# 构建到指定目录
vgrove build --outDir custom-dist
```

### 预览命令

```bash
# 预览构建结果
vgrove preview

# 指定预览端口
vgrove preview --port 4173
```

## 🔌 插件生态

VGrove Core 内置集成了以下插件：

- **@vitejs/plugin-react-swc**: React + SWC 支持
- **@gulibs/vgrove-autoroutes**: 自动路由生成
- **@gulibs/vgrove-i18n**: 国际化支持
- **@tailwindcss/vite**: Tailwind CSS 支持（HeroUI 模式）

## 🐛 调试

### 启用调试模式

```typescript
// vgrove.config.ts
export default defineConfig({
  vgrove: {
    routes: {
      debug: true // 路由调试
    },
    i18n: {
      debug: true // 国际化调试
    }
  }
});
```

### 环境变量

```bash
# 启用详细日志
DEBUG=vgrove:* vgrove dev

# 启用特定模块调试
DEBUG=vgrove:routes vgrove dev
```

## 📊 性能优化

VGrove Core 内置了多项性能优化：

- **SWC 编译**: 使用 SWC 替代 Babel，提升编译速度
- **智能缓存**: 路由和配置缓存，减少重复计算
- **代码分割**: 自动代码分割和懒加载
- **资源优化**: 图片、字体等资源优化
- **Tree Shaking**: 自动移除未使用的代码

## 🔄 迁移指南

### 从传统 Vite 项目迁移

1. 安装 VGrove Core：
```bash
npm install @gulibs/vgrove-core
```

2. 创建 VGrove 配置：
```typescript
// vgrove.config.ts
import { defineConfig } from '@gulibs/vgrove-core';

export default defineConfig({
  vgrove: {
    routes: {
      dirs: [{ dir: './src/pages', baseRoute: '/' }]
    }
  }
});
```

3. 更新 Vite 配置：
```typescript
// vite.config.ts
import { createViteConfig } from '@gulibs/vgrove-core';
import groveConfig from './vgrove.config';

export default createViteConfig(groveConfig);
```

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 支持

如有问题，请提交 [Issue](https://github.com/your-repo/vgrove-core/issues)。