ESBuild的优势

Transform API

Build API

 require('fs').writeFileSync('in.ts', 'let x: number = 1')
 require('esbuild').buildSync({
   entryPoints: ['in.ts'],
   outfile: 'out.js',
 })
 { errors: [], warnings: [] }
 require('fs').readFileSync('out.js', 'utf8')
 'let x = 1;\n'

基础选项

bundle

 require('esbuild').buildSync({
   entryPoints: ['in.js'],
   bundle: true,
   outfile: 'out.js',
 })
 { errors: [], warnings: [] }

 // 以下的打包均会被忽略
 import(`pkg/${foo}`);
 require(`pkg/${foo}`);
 ['pkg'].map(require);

define

 let js = 'hooks = DEBUG && require("hooks")'
 require('esbuild').transformSync(js, {
   define: { DEBUG: 'true' },
 })
 {
   code: 'hooks = require("hooks");\n',
   map: '',
   warnings: []
 }
 require('esbuild').transformSync(js, {
   define: { DEBUG: 'false' },
 })
 {
   code: 'hooks = false;\n',
   map: '',
   warnings: []
 }

entryPoints

 require('esbuild').buildSync({
   entryPoints: ['home.ts', 'settings.ts'],
   bundle: true,
   write: true,
   outdir: 'out',
 })  // output: out/home.js  out/setting.js
 require('esbuild').buildSync({
   entryPoints: {
     out1: 'home.js',
     out2: 'settings.js',
   },
   bundle: true,
   write: true,
   outdir: 'out',
 }) // output out/out1.js  out/out2.js

external

 require('fs').writeFileSync('app.js', 'require("fsevents")')
 require('esbuild').buildSync({
   entryPoints: ['app.js'],
   outfile: 'out.js',
   bundle: true,
   platform: 'node',
   external: ['fsevents'],
 })
 
 require('esbuild').buildSync({
   entryPoints: ['app.js'],
   outfile: 'out.js',
   bundle: true,
   external: ['*.png', '/images/*'],
 })

format

1. iife

2. cjs

3. esm

inject

 require('esbuild').buildSync({
   entryPoints: ['entry.js'],
   bundle: true,
   inject: ['./process-shim.js'],
   outfile: 'out.js',
 })

 // out.js
 let process = {cwd: () => ""};
 console.log(process.cwd());

1. 自动在jsx中引入React.creatElement

2. 统一在文件中注入一段文件, 我们可以不用担心重复注入的问题, esm会自动帮助我们处理

3. 条件性注入一个文件

loader

require('esbuild').buildSync({
  entryPoints: ['app.js'],
  bundle: true,
  loader: {
    '.png': 'dataurl',
    '.svg': 'text',
  },
  outfile: 'out.js',
})

require('esbuild').buildSync({
  stdin: {
    contents: 'import pkg = require("./pkg")',
    loader: 'ts',
    resolveDir: __dirname,
  },
  bundle: true,
  outfile: 'out.js',
})

minify

1. 压缩空格

2. 压缩变量

3. 压缩语法

var js = 'fn = obj => { return obj.x }'

require('esbuild').transformSync(js, {
  minifyWhitespace: true,
})
{
  code: 'fn=obj=>{return obj.x};\n',
  map: '',
  warnings: []
}
require('esbuild').transformSync(js, {
  minifyIdentifiers: true,
})
{
  code: 'fn = (n) => {\n  return n.x;\n};\n',
  map: '',
  warnings: []
}
require('esbuild').transformSync(js, {
  minifySyntax: true,
}){
  code: 'fn = (obj) => obj.x;\n',
  map: '',
  warnings: []
}

1. esbuild的minify的产物是针对现代浏览器的, 例如: a === undefined || a === null ? 1 : a将会被压缩为a ?? 1, 如果这不是期望行为, 需要设置target为es6 -target=es6

2. 转义符\n将会被替换成为模板字符串的换行符, 以节省占用字节大小

3. 默认情况下esbuild不会压缩顶级声明的变量, 但当我们设置了format或bundle为true的时候, esbuild会认为压缩顶级声明变量是安全的, 而启动定义声明变量的压缩

4. 压缩不是百分之百安全的, 即使是其他受欢迎的压缩工具例如terser也一样, 特别是在对于.toString()的处理上, 如果不去处理这类的内容压缩带来的效果就变得很小了, 这里建议的是使用明确的注释替代

5. 默认情况下, esbuild不会保存函数和类的.name属性, 如果确实需要 可以设置keepNames为true

6. 使用eval或with等将会使得许多优化失效导致整个文件无法被压缩处理, 一般建议不直接使用eval, 而是通过let result = (0, eval)(something)以防止对应的副作用产生

7. esbuild中的压缩算法没有进行高级代码优化, 如果需要进行高级代码优化 得使用terser等工具

outdir

require('esbuild').buildSync({
  entryPoints: ['app.js'],
  bundle: true,
  outdir: 'out',
})

outfile

require('esbuild').buildSync({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
})

platform

• 默认的输出 格式 为 iife，将生成的 JavaScript 代码包裹在立即执行函数表达式中， 以阻止变量泄露到全局作用域中。

• 如果一个包在 package.json 文件中 的browser 配置配置了一个 map，esbuild 将会使用该 map 替换指定的文件或模块为对浏览器友好的版本。 例如，例如，一个包可能会用 path-browserify 替换 path。

• main fields 设置为 browser,module,main， 但是会有一些额外的特殊行为。如果你个包支持 module 与 main，但是不支持 browser， 那么当使用 require() 导入时，将使用 main 而不是 module。 此行为通过将函数赋值给 module.exports 来改善与导出函数的 CommonJS 模块的兼容性。

• conditions 设置自动包含了 browser 情况。 这将改变 package.json 文件中 exports 字段如何被解释为偏好特定于浏览器代码的方式。

• All process.env.NODE_ENV expressions are automatically defined to "production" if all minification options are enabled and "development" otherwise. This only happens if process, process.env, and process.env.NODE_ENV are not already defined. This substitution is necessary to avoid React-based code crashing instantly (since process is a node API, not a web API).

• 默认输出 格式 为 cjs，代表 CommonJS（node 使用的模块格式）。 ES6-风格的导出使用的 export 语句将会被转换为 CommonJS exports 对象中的 getters。

• 所有诸如 fs 的 内置 node 模块 会被自动标记为 external，因此在打包器尝试打包他们时不会导致错误。

• main 字段 设置为 main,module。 这意味着 tree shaking 操作可能不会发生在同时提供 module 和 main 的包中， 因为 tree shaking 操作只适用于 ECMAScript 模块，而不适用于 CommonJS 模块。
不幸的是，一些包将 module 视为 "browser code" 而不是 "ECMAScript module code"， 因此，这种默认行为是兼容性所必需的。如果你想要启用 tree shaking 并且知道这样做是安全的， 那么你可以手动将 main 字段 设置为 module,main。

• conditions 设置自动包含 node 情况。 这将改变 package.json 文件中 exports 字段如何被解释为偏好特定于 node 端代码的方式。

• 默认输出 格式 为 esm，使用 ECMAScript 2015 (即 ES6) 中引入的 export 语法。 如果默认值不合适的话你可以改变输出格式。

• main 字段 默认设置为空。如果你想使用 npm 风格的包， 你可能需要将其配置为其他内容，比如将 node 使用的 main 字段配置为 main。

• conditions 设置不会自动包含任何平台特定值。

serve

interface ServeOptions {
  port?: number;
  host?: string;
  servedir?: string;
  onRequest?: (args: ServeOnRequestArgs) => void;
}

interface ServeOnRequestArgs {
  remoteAddress: string;
  method: string;
  path: string;
  status: number;
  timeInMS: number;
}

sourcemap

1. linked: sourcemap会作为文件输出出来, 并且js文件中包含了//# sourceMappingURL=的注释, 指向这个文件

2. external: 会输出成为一个独立的.js.map文件, 源文件中不包含//# sourceMappingURL=注释

3. inline: 会输出到js输出文件的末尾作为一个base64

4. both: both inlune和external的行为

spliting

target

• chrome

• edge

• firefox

• hermes

• ie

• ios

• node

• opera

• rhino

• safari

watch

write

let result = require('esbuild').buildSync({
  entryPoints: ['app.js'],
  sourcemap: 'external',
  write: false,
  outdir: 'out',
})

for (let out of result.outputFiles) {
  console.log(out.path, out.contents)
}

进阶选项

allowOverwrite

analyze

(async () => {
  let esbuild = require('esbuild')

  let result = await esbuild.build({
    entryPoints: ['example.jsx'],
    outfile: 'out.js',
    minify: true,
    metafile: true,
  })

  let text = await esbuild.analyzeMetafile(result.metafile, {
    verbose: true,
  })
  console.log(text)
})()

assetNames

require('esbuild').buildSync({
  entryPoints: ['app.js'],
  assetNames: 'assets/[name]-[hash]',
  loader: { '.png': 'file' },
  bundle: true,
  outdir: 'out',
})

• [dir]: 相对路径

• [name]: 原本的文件名称

• [hash]: 内容的contentHash, 避免文件冲突

• [ext]: 文件后缀名称

banner

require('esbuild').buildSync({
  entryPoints: ['app.js'],
  banner: {
    js: '//comment',
    css: '/*comment*/',
  },
  outfile: 'out.js',
})

charset

let js = 'let π = Math.PI'
require('esbuild').transformSync(js)
{
  code: 'let \\u03C0 = Math.PI;\n',
  map: '',
  warnings: []
}
require('esbuild').transformSync(js, {
  charset: 'utf8',
})
{
  code: 'let π = Math.PI;\n',
  map: '',
  warnings: []
}

chunkNames

• [name]

• [hash]

• [ext]

color

conditions

if (importPath === './foo') {
  if (conditions.has('import')) return './imported.mjs'
  if (conditions.has('require')) return './required.cjs'
  return './fallback.js'
}

drop

require('esbuild').buildSync({
  entryPoints: ['app.js'],
  drop: ['debugger', 'console'],
})

entryNames

globalName

let js = 'module.exports = "test"'
require('esbuild').transformSync(js, {
  format: 'iife',
  globalName: 'xyz',
})

// 输出内容戴上了xyz的变量
var xyz = (() => {
  ...
  var require_stdin = __commonJS((exports, module) => {
    module.exports = "test";
  });
  return require_stdin();
})();

ignoreAnnotations

incremental

jsx

...

插件

let envPlugin = {
  name: 'env',
  setup(build) {
    // Intercept import paths called "env" so esbuild doesn't attempt
    // to map them to a file system location. Tag them with the "env-ns"
    // namespace to reserve them for this plugin.
    build.onResolve({ filter: /^env$/ }, args => ({
      path: args.path,
      namespace: 'env-ns',
    }))

    // Load paths tagged with the "env-ns" namespace and behave as if
    // they point to a JSON file containing the environment variables.
    build.onLoad({ filter: /.*/, namespace: 'env-ns' }, () => ({
      contents: JSON.stringify(process.env),
      loader: 'json',
    }))
  },
}

require('esbuild').build({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [envPlugin],
}).catch(() => process.exit(1))

概念

namespace

filters

生命周期回调

onResolve回调

• filter: 过滤的正则

• namespace: 可选的, 指定namespace

interface OnResolveArgs {
  path: string; // 当前模块的路径
  importer: string; // 导入了当前模块的路径(父路径)
  namespace: string; // 解析此导入模块的命名空间, 由加载此文件的加载回调(onLoad)设置
  resolveDir: string; // 文件的真实文件系统地址
  kind: ResolveKind; // 如何导入要解析的路径
  pluginData: any; // 前一个插件(onLoad)传递的数据
}

type ResolveKind =
  | 'entry-point' // 入口
  | 'import-statement'  // 由import导入
  | 'require-call' // 使用import导入的
  | 'dynamic-import'
  | 'require-resolve'
  | 'import-rule' // 使用@import导入的css
  | 'url-token'

interface OnResolveResult {
  errors?: Message[];
  external?: boolean; // 设置为true, 将会排除在打包流程外, 直接使用此模块
  namespace?: string; // 如果为空会被设置为file, 如果是file, 那么path就必须是一个当前文件系统中的绝对路径
  path?: string; // 如果有值, 后续的onResolve就不会再执行, 否则会继续执行后续的onResolve, 如果onResolve执行完了, esbuild会提供一个默认的解析路径
  pluginData?: any; // 透传到下一个plugin的参数
  pluginName?: string; // 返回其他的pluginName, 让后续用其他plugin来解析
  sideEffects?: boolean; // 设置为false表示这个模块没有被使用到的import内容可以被删除
  suffix?: string;
  warnings?: Message[];
  watchDirs?: string[]; // 用于返回额外的文件系统路径供监听, 默认情况下esbuild知会箭筒namespace为file和onLoad插件提供的文件路径, 如果需要增加的话, 就需要返回这个内容了
  watchFiles?: string[]; // 用于返回额外的文件路径供监听
}

interface Message {
  text: string;
  location: Location | null;
  detail: any; // The original error from a JavaScript plugin, if applicable
}

interface Location {
  file: string;
  namespace: string;
  line: number; // 1-based
  column: number; // 0-based, in bytes
  length: number; // in bytes
  lineText: string;
}

let exampleOnResolvePlugin = {
  name: 'example',
  setup(build) {
    let path = require('path')

    // Redirect all paths starting with "images/" to "./public/images/"
    build.onResolve({ filter: /^images\// }, args => {
      return { path: path.join(args.resolveDir, 'public', args.path) }
    })

    // Mark all paths starting with "http://" or "https://" as external
    build.onResolve({ filter: /^https?:\/\// }, args => {
      return { path: args.path, external: true }
    })
  },
}

require('esbuild').build({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [exampleOnResolvePlugin],
  loader: { '.png': 'binary' },
}).catch(() => process.exit(1))

onLoad回调

• filter: 过滤的正则

• namespace: 可选的, 指定namespace

interface OnLoadArgs {
  path: string; // 如果namespace是file的时候, 是绝对路径, 也有可能是别的, 例如一个http地址
  namespace: string; // onResolve环境设置的命名空间, 默认为file
  suffix: string;
  pluginData: any;
}

interface OnLoadResult {
  contents?: string | Uint8Array; // 如果有内容返回, 后续的onLoad回调就不会在执行, 否则会继续执行后续的onLoad回调, 直到使用默认的
  errors?: Message[];
  loader?: Loader; // 告诉esbuild如何进行解析, 默认是js loader
  pluginData?: any;
  pluginName?: string;
  resolveDir?: string;
  warnings?: Message[];
  watchDirs?: string[];
  watchFiles?: string[];
}

interface Message {
  text: string;
  location: Location | null;
  detail: any; // The original error from a JavaScript plugin, if applicable
}

interface Location {
  file: string;
  namespace: string;
  line: number; // 1-based
  column: number; // 0-based, in bytes
  length: number; // in bytes
  lineText: string;
}

let exampleOnLoadPlugin = {
  name: 'example',
  setup(build) {
    let fs = require('fs')

    // Load ".txt" files and return an array of words
    build.onLoad({ filter: /\.txt$/ }, async (args) => {
      let text = await fs.promises.readFile(args.path, 'utf8')
      return {
        contents: JSON.stringify(text.split(/\s+/)),
        loader: 'json',
      }
    })
  },
}

require('esbuild').build({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [exampleOnLoadPlugin],
}).catch(() => process.exit(1))

在onLoad中使用缓存

let examplePlugin = {
  name: 'example',
  setup(build) {
    let fs = require('fs')
    let cache = new Map

    build.onLoad({ filter: /\.example$/ }, async (args) => {
      let input = await fs.promises.readFile(args.path, 'utf8')
      let key = args.path
      let value = cache.get(key)

      if (!value || value.input !== input) {
        let contents = slowTransform(input)
        value = { input, output: { contents } }
        cache.set(key, value)
      }

      return value.output
    })
  }
}

onStart回调

let examplePlugin = {
  name: 'example',
  setup(build) {
    build.onStart(() => {
      console.log('build started')
    })
  },
}

onEnd回调

let examplePlugin = {
  name: 'example',
  setup(build) {
    build.onEnd(result => {
      console.log(`build ended with ${result.errors.length} errors`)
    })
  },
}

访问构建参数

let examplePlugin = {
  name: 'auto-node-env',
  setup(build) {
    const options = build.initialOptions
    options.define = options.define || {}
    options.define['process.env.NODE_ENV'] =
      options.minify ? '"production"' : '"development"'
  },
}

路径解析

let examplePlugin = {
  name: 'example',
  setup(build) {
    build.onResolve({ filter: /^example$/ }, async () => {
      const result = await build.resolve('./foo', { resolveDir: './bar' })
      if (result.errors.length > 0) {
        return { errors: result.errors }
      }
      return { path: result.path, external: true }
    })
  },
}

require('esbuild').build({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [examplePlugin],
}).catch(() => process.exit(1))

插件限制

总结

1. 插件有name, setup方法, esbuild在初始化的时候会调用setup方法传入构建的options来初始化整个构建流程, 同时注册对应的生命周期回调

2. 首先, 会按顺序调用onResolve回调来解析导入内容, 处理导入的路径关系, 当文件匹配到对应的正则关系时会触发对应回调, 直到有path的输出为止

3. 接下来会走到onLoad回调, onLoad回调会获取路径path, 根据路径path来解析出内容, 输出content, 也就是这个路径对应的内容文本或buffer

4. 接下来会执行onStart回调, 代表构建开始

5. 最后会执行onEnd回调, 代表构建结束, 回调的参数为最终的构建结果

番外

1. 如何基于esbuild实现ddl的功能

1. 通过虚拟文件来引入和全局注册需要进行预打包的包依赖, 同时在window上注册对应包的变量

2. 通过esbuild来对其进行预打包, 生成文件

3. 使用esbuild插件来对预打包的内容进行排除, 并打包代码

4. 提前引入ddl打包的内容至html文件中

const isProduction = process.env.NODE_ENV == 'production'

const contents = `window.React = require('react')
window.ReactDOM = require('react-dom')
window.mobx = require('mobx')
window.mobxReact = require('mobx-react') `

require('esbuild').buildSync({
  stdin: {
    contents,
    sourcefile: 'react-build.js',
    loader: 'js',
    resolveDir: __dirname
  },
  define: {'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development')},
  bundle: true,
  format: 'iife',
  minify: isProduction,
  sourcemap: false,
  target: ['chrome58'],
  outfile: './lib/react.js',
})

const reactPlugin = {
  name: 'react',
  setup(build) {
    build.onResolve({filter: /^(react|react-dom|mobx|mobx-react)$/}, args => {
      return {
        path: args.path,
        namespace: 'react-ns'
      }
    })
    build.onLoad({filter: /^react$/, namespace: 'react-ns'}, () => {
      return {
        contents: 'module.exports = React'
      }
    })
    build.onLoad({filter: /^react-dom$/, namespace: 'react-ns'}, () => {
      return {
        contents: 'module.exports = ReactDOM'
      }
    })
    build.onLoad({filter: /^mobx$/, namespace: 'react-ns'}, () => {
      return {
        contents: 'module.exports = mobx'
      }
    })
    build.onLoad({filter: /^mobx-react$/, namespace: 'react-ns'}, () => {
      return {
        contents: 'module.exports = mobxReact'
      }
    })
  }
}

// esbuild 同步方式不支持 plugin
async function start() {
  let esbuild = require('esbuild')
  await esbuild.build({
    entryPoints: ['index.js'],
    target: ['chrome58'],
    bundle: true,
    outdir: 'lib',
    define: {'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development')},
    plugins: [reactPlugin],
    tsconfig: 'tsconfig.json'
  })
}

start()

2. 如何自定义loader

let etPlugin = {
  name: 'et',
  setup(build) {
    build.onResolve({filter: /.*\.et$/}, args => {
      let p = path.relative(__dirname, args.resolveDir)
      return {
        path: path.posix.join(p, args.path),
        namespace: 'et'
      }
    })
    build.onLoad({filter: /.*/, namespace: 'et'}, args => {
      // 读取文件生成 js 函数
      let fn = et.compileFile(args.path, {debug: !isProduction})
      return {
        contents: `module.exports = ${fn.toString()}`
      }
    })
  }
}

3. 参考