ants-bundle

antsxdp 定制构建工具，基于 esbuild 及 swc 实现

特点

1. 基于 esbuild 开发：无需关心内部构建逻辑，一键式构建
2. 覆盖常用的构建能力：通过 Plugin 式开发，完美支持 esbuild 的构建功能
3. 支持 ES5：借助 SWC 能力，支持构建至 ES5 环境

安装

# 建议当前项目中安装
pnpm i ants-bundle  -D

# 也可以全局安装，但不推荐
pnpm i ants-bundle -g

基础使用

ants-bundle [...files]

文件默认会构建至 dist目录下。

支持多入口

ants-bundle src/index.ts src/cli.ts

会在dist目录下产出index.js与cli.js。

也可以使用CLI的指令执行相同的功能

# 构建结果为 dist/index.js dist/cli.js
ants-bundle --entry src/index.ts --entry src/cli.ts

也可以指定构建后的文件名称

# 构建结果为 dist/foo.js 和 dist/bar.js
ants-bundle --entry.foo src/index.ts --entry.bar src/cli.ts

也可以在 ants-config.ts 中配置：

export default defineConfig({
  // 输出 dist/a.js 和 dist/b.js
  entry: ['src/a.ts', 'src/b.ts'],
  // 输出 dist/foo.js 和 dist/bar.js
  entry: {
    foo: 'src/a.ts',
    bar: 'src/b.ts',
  },
});

设置 exclude

默认情况下，除了生产环境下所依赖的模块(peerDependencies和dependencies)外，会自动构建其他的模块，如果不希望构建，可以使用--external避免构建。

自定义配置

可以使用如下配置

• ants-bundle.config.ts
• ants-bundle.config.js
• ants-bundle.config.cjs
• ants-bundle.config.json
• 在package.json中的ants-bundle

也可以使用defineConfig来进行定制化配置。

import { defineConfig } from 'ants-bundle';

export default defineConfig({
  entry: ['src/index.ts'],
  splitting: false,
  sourcemap: true,
  clean: true,
});

也可以在package.json中进行配置。

{
  "ants-bundle": {
    "entry": ["src/index.ts"],
    "splitting": false,
    "sourcemap": true,
    "clean": true
  }
}

生成声明文件

ants-bundle index.ts --dts

以上指令会导出./dist/index.js和./dist/index.d.ts，当导出多种构建格式时，每种构建格式都会生成一个声明文件。

如果有多个入口文件，每个入口文件都会生成一个对应的.d.ts文件。因此，如果想对单个入口文件生成声明文件时，请使用 --dts <entry>`` 格式，例如--dts src/index.ts`。

请注意，--dts不会解析 .d.ts 文件中使用的外部（比如node_modules）类型，如果这是某种要求，可以使用 --dts-resolve。

只导出声明文件

--dts-only 指令等同于tsc的emitDeclarationOnly。可以使用此指令只生成声明文件。

生成 sourcemap

ants-bundle index.ts --sourcemap

会导出 ./dist/index.js and ./dist/index.js.map。

如果有多个入口文件，每个入口文件都会生成相对于的.map文件。

构建产物格式

支持ESM、CJS和IIFE。

可以一次性构建多种类型：

ants-bundle src/index.ts --format esm,cjs,iife

将会生成以下文件结构：

dist
├── index.mjs         # esm
├── index.global.js   # iife
└── index.js          # cjs

如果package.json中的type配置为module，产出结果会有所不同：

dist
├── index.js          # esm
├── index.global.js   # iife
└── index.cjs         # cjs

如果不想使用诸如.mjs或者.cjs这类文件后缀，或者当前环境不支持此后缀，可以使用--legacy-output

ants-bundle src/index.ts --format esm,cjs,iife --legacy-output

会构建成:

dist
├── esm
│   └── index.js
├── iife
│   └── index.js
└── index.js

代码分割

目前代码分隔只支持ESM的产物类型，并且默认是开启的，如果想针对CJS的文件类型设置代码分隔，请设置--splitting，会启用esbuild的代码分隔功能。

对应地，如果想关闭代码分隔，请使用--no-splitting。

目标环境

此处默认使用tsconfig中的compilerOptions.target，也可以使用--target来手动声明。

支持 ES5

可以使用--target es5指令来将代码编译构建至 ES5 版本，代码首先会构建成ES2020，然后借助 SWC 编译成ES5。

watch 模式

ants-bundle src/index.ts --watch

启动watch模式，这意味着在初始构建后，ants-bundle 会监听文件变化。

可以使用--ignore-watch来取消指定文件的监听。

ants-bundle src src/index.ts --watch --ignore-watch folder1 --ignore-watch folder2

成功回调

ants-bundle src/index.ts --watch --onSuccess "node dist/index.js"

--onSuccess会返回Promise类型的函数，可以执行类似如下功能

import { defineConfig } from 'ants-bundle';

export default defineConfig({
  async onSuccess() {
    const server = http.createServer((req, res) => {
      res.end('Ants Studio!');
    });
    server.listen(3000);
    return () => {
      server.close();
    };
  },
});

压缩代码

可以使用--minify来压缩代码

ants-bundle src/index.ts --minify

或者使用terser而不是 esbuild 来压缩代码，前提条件是要先安装terser

ants-bundle src/index.ts --minify

tree shaking

esbuild默认开启tree shaking，但是特殊情况下（如：external 模块或者未使用的引用）等情况还是有些问题。

提供--treeshake指令来启用rollup的tree shaking。

针对更多帮助，请使用ants-bundle --help。