Universal Build Plugin

一个支持多种前端构建工具的通用插件框架，包括 Vite、Webpack、Rollup 等。

特性

• 🚀 多构建工具支持: 支持 Vite、Webpack、Rollup
• 📦 TypeScript 支持: 完整的 TypeScript 类型定义
• 🔧 可扩展架构: 基于抽象类的插件架构，易于扩展
• 📋 版本管理: 自动生成版本信息文件，包含构建时间、Git 信息等
• 🧪 完整测试: 包含完整的单元测试
• 📝 详细文档: 提供详细的 API 文档和使用示例

安装

npm install universal-build-plugin
# 或
yarn add universal-build-plugin
# 或
pnpm add universal-build-plugin

快速开始

Vite 项目

// vite.config.ts
import { defineConfig } from 'vite';
import { VitePlugin } from 'universal-build-plugin';

export default defineConfig({
  plugins: [
    new VitePlugin({
      name: 'my-plugin',
      debug: true,
      generateVersionFile: true, // 启用版本文件生成
    }).apply(),
  ],
});

Webpack 项目

// webpack.config.js
const { WebpackPlugin } = require('universal-build-plugin');

module.exports = {
  plugins: [
    new WebpackPlugin({
      name: 'my-plugin',
      debug: true,
    }),
  ],
};

Rollup 项目

// rollup.config.js
import { RollupPlugin } from 'universal-build-plugin';

export default {
  plugins: [
    new RollupPlugin({
      name: 'my-plugin',
      debug: true,
    }).apply(),
  ],
};

API 文档

PluginOptions

插件配置选项接口：

interface PluginOptions {
  /** 插件名称 */
  name?: string;
  /** 是否启用调试模式 */
  debug?: boolean;
  /** 是否生成版本文件 */
  generateVersionFile?: boolean;
  /** 自定义配置选项 */
  [key: string]: any;
}

BasePlugin

所有插件的基类，提供通用功能：

abstract class BasePlugin {
  constructor(options: PluginOptions);
  abstract apply(context: BuildContext): any;
  protected onBuildStart(context: BuildContext): Promise<void>;
  protected onBuildEnd(context: BuildContext): Promise<void>;
  protected onFileChanged(filePath: string, context: BuildContext): Promise<void>;
}

版本管理功能

插件会在构建完成后自动在项目根目录生成 version.json 文件，包含以下信息：

{
  "version": "1.0.0",
  "buildTime": "2024-08-07T10:30:00.000Z",
  "bundler": "vite",
  "mode": "production",
  "gitCommit": "a1b2c3d4",
  "gitBranch": "main",
  "environment": "production",
  "projectName": "my-project",
  "buildNumber": 42
}

启用版本管理

// 默认启用（使用 package.json 版本）
new VitePlugin({
  generateVersionFile: true, // 默认为 true
}).apply()

// 禁用版本管理
new VitePlugin({
  generateVersionFile: false,
}).apply()

自定义版本生成方式

插件支持多种版本生成方式：

1. Git Hash 版本

new VitePlugin({
  generateVersionFile: true,
  versionInfo: {
    versionType: 'git-hash',
    meta: {
      buildBy: 'CI/CD',
      environment: 'production',
    },
  },
}).apply()

2. 时间戳版本

new VitePlugin({
  generateVersionFile: true,
  versionInfo: {
    versionType: 'timestamp',
    meta: {
      buildServer: 'jenkins-01',
    },
  },
}).apply()

3. 自定义版本（支持异步）

new VitePlugin({
  generateVersionFile: true,
  versionInfo: {
    versionType: 'custom',
    customVersion: async () => {
      // 支持异步操作
      const apiResponse = await fetch('/api/version');
      const data = await apiResponse.json();
      return `v${data.major}.${data.minor}.${data.patch}`;
    },
    meta: {
      buildType: 'api-generated',
    },
  },
}).apply()

手动使用版本管理

import { VersionManager } from 'universal-build-plugin';

const versionManager = new VersionManager();

// 生成版本信息
const versionInfo = await versionManager.generateVersionInfo('vite', 'production');

// 写入版本文件
await versionManager.writeVersionFile(versionInfo);

// 读取现有版本文件
const existingVersion = await versionManager.readVersionFile();

自定义插件开发

创建自定义 Vite 插件

import { VitePlugin } from 'universal-build-plugin';

class MyVitePlugin extends VitePlugin {
  protected shouldTransform(id: string): boolean {
    return id.endsWith('.special');
  }

  protected async transformCode(code: string, id: string, context: BuildContext): Promise<string> {
    // 自定义代码转换逻辑
    return `// Transformed by MyVitePlugin\n${code}`;
  }
}

// 使用
export default defineConfig({
  plugins: [
    new MyVitePlugin({ name: 'my-special-plugin' }).apply(),
  ],
});

创建自定义 Webpack 插件

import { WebpackPlugin } from 'universal-build-plugin';

class MyWebpackPlugin extends WebpackPlugin {
  protected async processAssets(assets: Array<{ name: string; source: any }>, context: BuildContext): Promise<void> {
    // 自定义资源处理逻辑
    console.log(`Processing ${assets.length} assets`);
  }
}

// 使用
module.exports = {
  plugins: [
    new MyWebpackPlugin({ name: 'my-webpack-plugin' }),
  ],
};

开发

安装依赖

npm install

构建

npm run build

测试

npm test

代码检查

npm run lint

格式化代码

npm run format

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License