@gswl/gsbuild

一个简单但功能强大的 TypeScript 库构建工具，基于 Vite 构建系统，用于管理和构建多包 monorepo 项目。

功能特点

• 自动构建 TypeScript 库
• 支持监视模式实时编译
• 自动创建必要的配置文件
• 同时支持 ES 模块和 CommonJS 格式
• 递归查找符合条件的库目录
• 动态监测新添加的库目录
• 支持自定义入口文件名称
• 适用于多包 monorepo 项目结构
• 自动将子目录包设为 external，避免循环依赖
• 支持编译主应用目录，可自定义主应用目录名
• 编译时自动删除所有注释
• 支持使用-r 参数删除 console 和 debugger 语句
• 支持使用-l 参数强制构建库文件

安装

npm install @gswl/gsbuild --save-dev

使用方法

基本用法

# 构建所有包
npx gsbuild

# 监视模式
npx gsbuild -w
# 或使用完整命令
npx gsbuild --watch

# 构建单个包
npx gsbuild -p 包名
# 或使用完整命令
npx gsbuild --package 包名

# 强制构建库文件
npx gsbuild -l
# 或使用完整命令
npx gsbuild --library

# 指定不同的入口文件（默认是index.ts）
npx gsbuild -f main.ts
# 或使用完整命令
npx gsbuild --file main.ts

# 指定不同的包目录并监视
npx gsbuild -d libs -w
# 或使用完整命令
npx gsbuild --dir libs --watch

# 指定当前工作目录
npx gsbuild -c /path/to/your/project
# 或使用完整命令
npx gsbuild --cwd /path/to/your/project

# 指定主应用目录
npx gsbuild -a webapp
# 或使用完整命令
npx gsbuild --app webapp

# 移除调试代码（console和debugger语句）
npx gsbuild -r
# 或使用完整命令
npx gsbuild --remove-debug

# 监视模式下使用HTML开发服务
npx gsbuild -w -s
# 或使用完整命令
npx gsbuild --watch --server

# 组合使用多个参数
npx gsbuild -p package1 -f main.ts -c /path/to/your/project -a webapp -w -r -s
# 或混合使用简写和完整命令
npx gsbuild --package package1 --file main.ts --cwd /path/to/your/project --app webapp --watch --remove-debug --server

在 package.json 中配置

{
  "scripts": {
    "build": "gsbuild",
    "build:watch": "gsbuild -w",
    "build:package": "gsbuild -p",
    "build:custom": "gsbuild -f main.ts -d libs",
    "build:app": "gsbuild -a webapp",
    "build:prod": "gsbuild -r",
    "build:lib": "gsbuild -l",
    "dev": "gsbuild -w -s"
  }
}

命令行参数

| 简写参数 | 完整参数 | 说明 | | --------------- | ------------------ | -------------------------------------------------- | | -w | --watch | 启用监视模式，检测文件变化自动重新构建 | | -p <包名> | --package <包名> | 指定要构建的单个包 | | -d <目录> | --dir <目录> | 指定包含多个包的目录（默认为 packages） | | -f <文件名> | --file <文件名> | 指定入口文件名称（默认为 index.ts） | | -c <目录路径> | --cwd <目录路径> | 指定当前工作目录（默认为命令执行目录） | | -a <目录名> | --app <目录名> | 指定主应用目录名称（默认为 app） | | -r | --remove-debug | 移除 console 和 debugger 语句 | | -s | --server | 监视模式下为 app 提供开发服务器 | | -l | --library | 构建子包，不然只会构建 app 或在-p 参数下构建指定包 |

自动配置

对于新的包，gsbuild 会自动创建：

1. 基本的package.json配置
2. TypeScript 配置文件tsconfig.json
3. 示例源码文件和目录结构

高级功能

递归目录查找

gsbuild 会递归查找指定目录下的所有子目录，只要该目录包含 src/入口文件（默认是 src/index.ts），就会被视为一个需要构建的库。

动态监测新库

在监视模式下，gsbuild 会监测整个目录结构的变化。当添加新的库目录或在现有目录中创建 src/入口文件 时，gsbuild 会自动检测并将其添加到构建过程中。

自定义入口文件

可以通过 -f 参数指定不同于默认 index.ts 的入口文件名称。例如：

npx gsbuild -f main.ts

这将使 gsbuild 查找和使用 src/main.ts 作为入口文件而不是 src/index.ts。

自动处理包之间的依赖关系

gsbuild 会自动将项目中的所有子包设置为 external 依赖，这意味着：

1. 避免了子包之间的循环依赖问题
2. 减少了最终打包文件的体积，避免代码重复打包
3. 允许子包之间正确地相互引用，同时保持独立构建

例如，如果您的项目中有 packageA 和 packageB 两个包，并且它们互相依赖，gsbuild 会自动确保在构建 packageA 时，packageB 被标记为外部依赖，反之亦然。这样可以解决循环依赖问题，同时保持代码的模块化结构。

在构建过程中，您可以在日志中看到所有被设置为 external 的包名。

主应用目录编译

当使用 -c 参数指定工作目录时，gsbuild 会自动在该目录下查找并编译 app 目录（可通过 -a 参数自定义）中的应用代码。与普通包不同，编译主应用时：

1. packages 目录中的所有包对应用不设为 external 依赖
2. 应用代码可以直接导入并使用项目中的所有包
3. 最终打包结果保存在 app/dist 目录

代码优化

gsbuild 提供两级代码优化：

1. 默认优化：无论是否指定任何参数，编译时都会自动删除所有注释（包括多行注释、单行注释和 JSDoc 注释）
2. 进阶优化：当使用 -r 参数时，除了删除注释外，还会移除所有 console.* 语句和 debugger 语句，适用于生产环境构建

开发服务器

使用 -s 或 --server 参数并与监视模式 -w 参数一起使用时，gsbuild 会为应用目录提供一个内置的开发服务器：

1. 自动生成适合 Vite 开发环境的 HTML 页面
2. 提供热更新支持，便于开发调试
3. 无需手动创建 HTML 文件，简化开发流程
4. 自动加载应用的入口文件

这个特性特别适合在开发阶段快速预览和测试应用。使用命令：

npx gsbuild -w -s

启动后，可以通过浏览器访问开发服务器提供的 URL 来访问应用。

项目结构

推荐的项目结构：

your-project/
├── app/                 # 主应用目录
│   ├── src/
│   │   └── index.ts
│   └── dist/            # 编译输出
├── packages/
│   ├── package1/
│   │   ├── src/
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── package2/
│       ├── src/
│       │   └── index.ts
│       ├── package.json
│       └── tsconfig.json
└── package.json

也支持嵌套结构：

your-project/
├── webapp/              # 自定义的主应用目录 (-a webapp)
│   ├── src/
│   │   └── index.ts
│   └── dist/
├── packages/
│   ├── group1/
│   │   ├── package1/
│   │   │   ├── src/
│   │   │   │   └── index.ts
│   │   │   ├── package.json
│   │   │   └── tsconfig.json
│   │   └── package2/
│   │       ├── src/
│   │       │   └── main.ts  # 自定义入口文件
│   │       ├── package.json
│   │       └── tsconfig.json
│   └── group2/
│       └── package3/
│           ├── src/
│           │   └── index.ts
│           ├── package.json
│           └── tsconfig.json
└── package.json

许可证

ISC