pangu-chart-cli

一个专注于 Vue 3 可视化组件库打包的 Vite 配置生成器。

简介

pangu-chart-cli 是一个专为 Vue 3 chart/可视化组件库设计的打包工具。它简化了 Vite 配置流程,自动处理 Element Plus namespace、banner 注入、CSS 代码分割等复杂配置,让开发者专注于组件开发本身。

核心特性:

• 自动生成 Vite 配置(UMD + ES 双格式输出)
• Element Plus CSS namespace 自定义(避免样式冲突)
• 自动添加 banner(包含 name/version/author/时间戳)
• 开发服务自动检测 example 目录
• CSS 代码分割 + Gzip 压缩
• TypeScript 类型支持

适用场景:

• Vue 3 组件库开发
• 可视化图表库打包
• Element Plus 二次封装组件库

安装

全局安装

npm install -g pangu-chart-cli
# 或
pnpm add -g pangu-chart-cli

项目依赖

npm install --save-dev pangu-chart-cli
# 或
pnpm add -D pangu-chart-cli

CLI 命令

CLI 工具提供两个命令别名:vcc 和 vis-chart-cli,以下以 vcc 为例。

vcc dev / vcc d

启动 Vite 开发服务。

执行逻辑:

1. 检测项目根目录下的 example/package.json 是否存在
2. 若存在,进入 example 目录执行开发服务
3. 若不存在,在项目根目录执行开发服务
4. 若目标目录无 vite.config.js 或 vite.config.ts,使用内置默认配置
5. 服务监听 0.0.0.0(局域网可访问)

使用示例:

vcc dev
# 或
vcc d

vcc build / vcc b

执行 Vite 打包。

执行逻辑:

1. 在项目根目录查找 vite.config.js 或 vite.config.ts
2. 若无配置文件,使用内置默认配置
3. 输出 UMD + ES 双格式
4. 自动添加 banner(包含组件名称、版本、作者、构建时间)
5. 清理隐藏文件(._*、.DS_Store)

使用示例:

vcc build
# 或
vcc b

vcc -v

查看当前版本号。

vcc -v

API 文档

本工具提供三个核心 API 函数,用于在 vite.config.js 中生成配置。

getConfig(config)

生成完整的 Vite UserConfig 配置对象。

参数:

| 参数名 | 类型 | 必填 | 说明 | | --------------- | ------------------- | ---- | --------------------------- | | name | string | ✓ | package.json 中的组件名称 | | version | string | ✓ | package.json 中的版本号 | | author | string | - | 作者信息,用于 banner | | elementConfig | boolean \| object | - | Element Plus namespace 配置 |

返回值结构:

{
  // 全局变量定义
  define: {
    'process.env': process.env || {}
  },

  // 插件列表
  plugins: [
    // 若启用 elementConfig,包含 elementNamespacePlugin
    vue({ isProduction: true }),
    compression({ ext: '.gz', deleteOriginFile: false }),
    banner({
      outDir: '<输出目录路径>',
      content: '<组件名> v<版本号> Author: <作者> Date: <时间戳>'
    })
  ],

  // 开发服务器配置
  server: {
    host: '0.0.0.0'  // 局域网可访问
  },

  // CSS 预处理器配置(若启用 elementConfig)
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: "@forward '<config.scss路径>' with (\n  $namespace: '<namespace名称>'\n);"
      }
    }
  },

  // 构建配置
  build: {
    target: ['chrome94', 'edge94', 'firefox92'],  // 浏览器兼容目标
    reportCompressedSize: false,                  // 不报告压缩大小
    emptyOutDir: true,                            // 清空输出目录
    outDir: '<组件名>_v<版本号>',                  // 输出目录名
    cssCodeSplit: true,                           // CSS 代码分割

    // 库模式配置
    lib: {
      entry: './index.js',                        // 入口文件
      formats: ['umd', 'es'],                     // 输出格式
      name: '<大写组件名>_v<版本号>',               // UMD 全局变量名
      fileName: (format) => format === 'es' ? 'es/index.js' : 'index.js'
    },

    // Rollup 配置
    rollupOptions: {
      external: ['vue'],                          // 外部化依赖
      output: {
        globals: { vue: 'Vue' },                  // UMD 全局变量映射
        chunkFileNames: 'es/js/[name]-[hash].js', // chunk 文件名格式
        assetFileNames: (assetInfo) => {          // 资源文件名格式
          if (assetInfo.name?.endsWith('.css')) {
            return 'es/style.css'
          }
          return 'es/assets/[name]-[hash][extname]'
        }
      }
    }
  }
}

使用示例:

import { getConfig } from 'pangu-chart-cli';

export default getConfig({
  name: 'my-chart',
  version: '1.0.0',
  author: 'Your Name',
  elementConfig: {
    enable: true,
    entryFile: 'src/index.vue',
    configSrc: 'element-plus/theme-chalk/src/mixins/config.scss',
    namespace: 'MyChart'
  }
});

getBaseConfig(config)

生成基础的 build 配置对象(不含 plugins),用于自定义扩展。

参数:

| 参数名 | 类型 | 必填 | 说明 | | --------- | -------- | ---- | ------------------------- | | name | string | ✓ | package.json 中的组件名称 | | version | string | ✓ | package.json 中的版本号 |

返回值结构:

{
  build: {
    target: ['chrome94', 'edge94', 'firefox92'],
    reportCompressedSize: false,
    emptyOutDir: true,
    outDir: '<组件名>_v<版本号>',
    cssCodeSplit: true,

    lib: {
      entry: './index.js',
      formats: ['umd', 'es'],
      name: '<大写组件名>_v<版本号>',
      fileName: (format) => format === 'es' ? 'es/index.js' : 'index.js'
    },

    rollupOptions: {
      external: ['vue'],
      output: {
        globals: { vue: 'Vue' },
        chunkFileNames: 'es/js/[name]-[hash].js',
        assetFileNames: (assetInfo) => {
          if (assetInfo.name?.endsWith('.css')) {
            return 'es/style.css'
          }
          return 'es/assets/[name]-[hash][extname]'
        }
      }
    }
  }
}

使用示例:

import { getBaseConfig } from 'pangu-chart-cli';

const baseConfig = getBaseConfig({
  name: 'my-chart',
  version: '1.0.0'
});

// 自定义扩展
export default {
  ...baseConfig,
  plugins: [
    /* 自定义插件列表 */
  ]
};

getPackageInfo(config)

获取打包信息(输出目录、UMD name、elementConfig)。

参数:

| 参数名 | 类型 | 必填 | 说明 | | --------------- | ------------------- | ---- | --------------------------- | | name | string | ✓ | package.json 中的组件名称 | | version | string | ✓ | package.json 中的版本号 | | elementConfig | boolean \| object | - | Element Plus namespace 配置 |

返回值结构:

{
  name: '<大写组件名>_v<版本号>',     // UMD 全局变量名(首字母大写,版本号用_分隔)
  outDir: '<组件名>_v<版本号>',      // 输出目录名
  elementConfig: <原始值>            // 传入的 elementConfig 值
}

说明:

• name 格式:组件名首字母大写 + _v + 版本号(. 替换为 _)
  • 例如:my-chart v1.0.0 → My-chart_v1_0_0
• outDir 格式:组件名 + _v + 版本号
  • 例如:my-chart v1.0.0 → my-chart_v1.0.0

使用示例:

import { getPackageInfo } from 'pangu-chart-cli';

const info = getPackageInfo({
  name: 'my-chart',
  version: '1.0.0'
});

console.log(info);
// 输出: { name: 'My-chart_v1_0_0', outDir: 'my-chart_v1.0.0', elementConfig: undefined }

elementConfig 配置详解

elementConfig 用于自定义 Element Plus CSS namespace,避免样式冲突。支持三种形态:

形态一:false / 不传

含义:不启用 namespace 功能。

默认值:无(不处理 Element Plus namespace)

使用场景:不需要隔离 Element Plus 样式,或组件库不依赖 Element Plus。

getConfig({
  name: 'my-chart',
  version: '1.0.0',
  elementConfig: false
});

形态二:true

含义:启用 namespace 功能,使用默认配置。

默认值:

| 参数 | 默认值 | 说明 | | ----------- | --------------------------------------------------- | ---------------------------------- | | enable | true | 启用功能 | | entryFile | 'src/index.vue' | Vue 入口文件路径(相对于项目根目录) | | configSrc | 'element-plus/theme-chalk/src/mixins/config.scss' | Element Plus SCSS config 文件路径 | | namespace | <大写组件名> | 自动生成(组件名首字母大写) |

使用场景:快速启用 namespace,无需自定义参数。

getConfig({
  name: 'my-chart',
  version: '1.0.0',
  elementConfig: true
});

// 实际配置:
// {
//   enable: true,
//   entryFile: 'src/index.vue',
//   configSrc: 'element-plus/theme-chalk/src/mixins/config.scss',
//   namespace: 'My-chart'
// }

形态三:object(自定义配置)

含义:启用 namespace 功能,自定义参数。

参数说明:

| 参数 | 类型 | 必填 | 说明 | | ----------- | --------- | ---- | ----------------------------------- | | enable | boolean | - | 是否启用(默认:true) | | entryFile | string | - | Vue 入口文件路径(支持相对/绝对路径) | | configSrc | string | - | Element Plus SCSS config 文件路径 | | namespace | string | - | 自定义 namespace 名称 |

默认值(未指定参数时):

• enable: true
• entryFile: 'src/index.vue'
• configSrc: 'element-plus/theme-chalk/src/mixins/config.scss'
• namespace: <大写组件名>(组件名首字母大写)

使用场景:需要自定义入口文件、namespace 名称等参数。

getConfig({
  name: 'my-chart',
  version: '1.0.0',
  elementConfig: {
    enable: true,
    entryFile: 'src/components/Chart.vue',
    configSrc: 'element-plus/theme-chalk/src/mixins/config.scss',
    namespace: 'MyCustomChart'
  }
});

elementConfig 工作原理

启用 elementConfig 后,工具会执行以下操作:

1. SCSS namespace 注入:在 Vite 配置中添加 SCSS 预处理器配置,自动注入 @forward 语句修改 Element Plus namespace:

   @forward 'element-plus/theme-chalk/src/mixins/config.scss' with (
     $namespace: 'MyChart'
   );

2. Vue 模板包装:通过 elementNamespacePlugin 在入口 Vue 文件的 <template> 中自动包装 <el-config-provider namespace="MyChart">:

   <template>
     <el-config-provider namespace="MyChart">
       <!-- 原模板内容 -->
     </el-config-provider>
   </template>
   
   <script setup>
   import { ElConfigProvider } from 'element-plus';
   </script>

3. 避免样式冲突:所有 Element Plus 组件样式都会使用自定义 namespace,避免与其他 Element Plus 组件库产生样式冲突。

项目结构

pangu-chart-cli/
├── bin/
│   └── index.js                 # CLI 入口(指向 dist/index.js)
├── core/
│   ├── index.js                 # 命令注册(commander)
│   ├── dev/
│   │   └── index.js             # dev 命令逻辑
│   └── build/
│       └── index.js             # build 命令逻辑
├── viteConfig/
│   ├── index.js                 # getConfig API 实现
│   ├── base.js                  # getBaseConfig/getPackageInfo 实现
│   ├── default.js               # 默认 Vite 配置模板
│   └── vite-plugin-element-namespace.js  # Element namespace 插件
├── index.d.ts                   # TypeScript 类型定义
├── package.json
├── rollup.config.js             # Rollup 打包配置
└── dist/                        # 打包输出目录

开发指南

本地构建

使用 bun + rollup 进行本地构建:

pnpm build

构建流程:

1. bun ./build/index.js - 预处理
2. rollup --config - 打包生成 dist/ 目录

发布流程

使用 standard-version 管理版本和生成 CHANGELOG:

# Patch 版本(1.0.0 -> 1.0.1)
pnpm release:patch

# Minor 版本(1.0.0 -> 1.1.0)
pnpm release:minor

# Major 版本(1.0.0 -> 2.0.0)
pnpm release:major

# Beta 版本(1.0.0 -> 1.0.1-beta.0)
pnpm release:beta

发布到 npm:

npm publish

依赖说明

运行时依赖:

• commander - CLI 框架
• chalk - 终端颜色输出
• ora - 终端加载动画
• cross-spawn - 跨平台进程执行
• dayjs - 时间处理
• await-to-js - 异步错误处理
• yann-fs - 文件系统工具

开发依赖:

• rollup - 打包工具
• vite - 构建核心(用户项目运行时依赖)
• standard-version - 版本管理

用户项目需要安装:

• vite - 构建工具
• element-plus - Element Plus 组件库(若使用 elementConfig)
• @vitejs/plugin-vue - Vue 插件

常见问题

Q: Element Plus 未安装时使用 elementConfig 会报错吗?

A: 会报错。使用 elementConfig 前需确保项目已安装 Element Plus:

npm install element-plus

Q: 开发服务启动后局域网无法访问?

A: 工具默认监听 0.0.0.0,局域网应可访问。请检查防火墙设置或使用 --host 参数指定 IP。

Q: 打包输出目录命名规则?

A: 输出目录格式为 <组件名>_v<版本号>,例如 my-chart_v1.0.0。

Q: UMD 全局变量名命名规则?

A: UMD name 格式为 <大写组件名>_v<版本号>(. 替换为 _),例如 My-chart_v1_0_0。

License

MIT License

Copyright (c) 2024 Yann

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.