VGrove Core

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

🚀 特性

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

📦 安装

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

全局安装 CLI

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

🎯 快速开始

1. 创建配置文件

// 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

# 开发模式
vgrove dev

# 构建生产版本
vgrove build

# 预览构建结果
vgrove preview

# 显示帮助
vgrove --help

3. 编程式使用

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

export default createViteConfig(groveConfig);

⚙️ 配置选项

VGrove 配置

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

路由配置

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

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

UI 框架配置

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

国际化配置

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

构建配置

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

🔧 高级配置

多环境配置

// 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
      }
    }
  };
});

自定义插件集成

// 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 依赖：

// 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 命令

开发命令

# 启动开发服务器
vgrove dev

# 指定端口
vgrove dev --port 8080

# 指定主机
vgrove dev --host 0.0.0.0

构建命令

# 构建生产版本
vgrove build

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

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

预览命令

# 预览构建结果
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 模式）

🐛 调试

启用调试模式

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

环境变量

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

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

📊 性能优化

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

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

🔄 迁移指南

从传统 Vite 项目迁移

1. 安装 VGrove Core：

npm install @gulibs/vgrove-core

2. 创建 VGrove 配置：

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

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

3. 更新 Vite 配置：

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

export default createViteConfig(groveConfig);

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

如有问题，请提交 Issue。