Babel 预设配置 - H5

babel-preset-h5 是有赞 H5 应用统一的 Babel 配置。

使用方式

安装

yarn add @kokojs/babel-preset-h5 --dev

PS: 如果项目中安装了 @youzan/koko-preset-h5，默认就会依赖 @kokojs/babel-preset-h5，因此可以跳过安装。

配置

在 babel.config.js 中添加对应的 preset：

module.exports = {
  presets: ['@kokojs/babel-preset-h5'],
};

如果是 npm 包的话，还需要在 dependencies 里添加以下两个依赖：

{
  "dependencies": {
    "@babel/runtime": "7.x",
    "core-js": "3.x"
  }
}

配置项

useESModules

• Type: boolean
• Default: true

useESModules 用于控制编译后的模块是否为 ESModule，默认为true，如果需要编译到 commonjs 模块，可以将这项配置设置为false。

module.exports = {
  presets: [
    [
      '@kokojs/babel-preset-h5',
      {
        useESModules: false,
      },
    ],
  ],
};

一般情况下，我们推荐默认输出 ESModule 模块，因为 ESModule 可以触发 Webpack 的 Tree Shaking 和 Scope Hoisting，从而减少代码体积.

如果你的 npm 包需要适配 Webpack 1.x 的旧仓库，则必须输出 commonjs 模块，因为 Webpack 1.x 不支持直接编译 ESModule.

当然，你也可以通过工具来同时输出两个版本，比如使用 rollup 的 output.format 来同时输出 ESModule 和 commonjs.

useBuiltIns

• Type: string | boolean
• Default: 'usage'
• 可选值：'entry'、false

等同于 @babel/preset-env 的 useBuiltIns 选项，用于控制 polyfill 的行为。

默认情况下，代码中会添加 core-js@3 的 polyfill 来确保兼容性。

在某些特殊场景下可以将这项配置设置为 false 来禁用 core-js（比如这个包需要在小程序中使用，而小程序不支持 core-js）。

注意：如果禁用了 core-js，请谨慎在代码中使用 ESNext API，以避免出现兼容性问题。

module.exports = {
  presets: [
    [
      '@kokojs/babel-preset-h5',
      {
        useBuiltIns: false,
      },
    ],
  ],
};

coreJsPure

• Type: boolean
• Default: false

coreJsPure 用于控制 core-js 的 polyfill 是否污染全局命名空间。

配置该属性后，编译结果的依赖将从 core-js 变更为 @babel/runtime-corejs3。

此选项的优先级高于 useBuiltIns 选项。

{
  "dependencies": {
    "@babel/runtime-corejs3": "7.x"
  }
}

loose

• Type: boolean
• Default: true

是否开启 babel-preset-env 的 loose 模式。

module.exports = {
  presets: [['@kokojs/babel-preset-h5', { loose: false }]],
};

excludeStyleLibs

• Type: string[]
• Default: []

excludeStyleLibs 用于控制打包时需要排除的组件库样式文件，通过配置这个属性，可以在将组件处理为 externals 依赖时，不打包对应的样式文件

enableDevTranspile

• Type: boolean
• Default: false

是否在 dev 模式下将代码编译至 ES5，注意开启后会降低 dev 的编译速度。

默认情况下，我们会在 build 时将代码编译至 ES5，而在 dev 阶段仅会对代码进行最小程度的编译（仅保证最新浏览器能运行）。

targets

• Type: string | string[] | object
• Default: ['Android >= 4.0', 'iOS >= 8']

编译目标浏览器版本，等同于 @babel/preset-env 的 targets 选项。

optimizeConstEnums

• Type: boolean
• Default: false

传递给 @babel/preset-typescript 的参数，是否开启 const enum 编译优化。

module.exports = {
  presets: [
    [
      '@kokojs/babel-preset-h5',
      {
        optimizeConstEnums: true,
      },
    ],
  ],
};

内置插件列表

@babel/preset-env

用于 polyfill ESNext 语法和添加 core-js3

@babel/plugin-transform-runtime

用于将 Babel helper 转换为 import 形式，减少代码体积

@babel/preset-typescript

用于转换 TypeScript 语法

babel-plugin-import

用于组件库按需引入，目前包含以下组件库：

• vant
• @youzan/vis-ui
• @youzan/captain
• @youzan/brand-ui
• @youzan/captain-showcase
• @youzan/wsc-membercenter
• @youzan/pay-components-h5

注意：此配置中不包含旧版 captain-ui，如果项目中依然使用了旧版 captain-ui，请保留对 captain-ui 的按需引入配置

@babel/plugin-proposal-class-properties

用于转换 class 的属性

@vue/babel-preset-jsx

用于转换 Vue JSX 语法，详见 vuejs/jsx

@babel/plugin-proposal-decorators

装饰器语法支持，可用于结合 vue-property-decorator 来使用 TS 编写 Vue 文件

维护者

陈嘉涵。