npm package: @kokojs/babel-preset-h5
Description: Babel preset for h5 projects.
Latest version: 4.0.36

# Babel 预设配置 - H5

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

## 使用方式

### 安装

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

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

### 配置

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

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

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

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

## 配置项

### useESModules

- Type: `boolean`
- Default: `true`

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

```js
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](https://babeljs.io/docs/en/babel-preset-env#usebuiltins) 选项，用于控制 polyfill 的行为。

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

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

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

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

### coreJsPure

- Type: `boolean`
- Default: `false`

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

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

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

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

### loose

- Type: `boolean`
- Default: `true`

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

```js
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 选项](https://babeljs.io/docs/en/babel-preset-env#targets)。

### optimizeConstEnums

- Type: `boolean`
- Default: `false`

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

```js
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](https://github.com/vuejs/jsx)

#### @babel/plugin-proposal-decorators

装饰器语法支持，可用于结合 [`vue-property-decorator`](https://github.com/kaorun343/vue-property-decorator) 来使用 TS 编写 Vue 文件

## 维护者

陈嘉涵。