# babel-preset-taro

> Taro babel preset

Latest version **4.2.1** (published 2026-07-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install babel-preset-taro
pnpm add babel-preset-taro
yarn add babel-preset-taro
bun add babel-preset-taro
```

## Health

**Score 60/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score; popular repo.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 4.2.1 |
| Published | 2026-07-17 |
| First published | 2020-01-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 18 |
| Dependencies | 14 |
| Unpacked size | 32.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 37672 |
| Author | O2Team |
| Maintainers | defaultlee, yuche |

## Links

- npm: https://www.npmjs.com/package/babel-preset-taro
- Repository: https://github.com/NervJS/taro
- Homepage: https://github.com/nervjs/taro/tree/main/packages/babel-preset-taro#readme
- Issues: https://github.com/NervJS/taro/issues
- npm.io page: https://npm.io/package/babel-preset-taro

## Dependencies (14)

- [core-js](https://npm.io/package/core-js.md) ^3.36.1
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.24.4
- [@tarojs/helper](https://npm.io/package/@tarojs/helper.md) 4.2.1
- [@babel/preset-env](https://npm.io/package/@babel/preset-env.md) ^7.24.4
- [@babel/runtime-corejs3](https://npm.io/package/@babel/runtime-corejs3.md) ^7.24.4
- [@babel/preset-typescript](https://npm.io/package/@babel/preset-typescript.md) ^7.24.1
- [@babel/helper-plugin-utils](https://npm.io/package/@babel/helper-plugin-utils.md) ^7.24.8
- [@babel/plugin-transform-runtime](https://npm.io/package/@babel/plugin-transform-runtime.md) ^7.24.3
- [babel-plugin-dynamic-import-node](https://npm.io/package/babel-plugin-dynamic-import-node.md) ^2.3.3
- [babel-plugin-transform-solid-jsx](https://npm.io/package/babel-plugin-transform-solid-jsx.md) 4.2.1
- [@babel/plugin-proposal-decorators](https://npm.io/package/@babel/plugin-proposal-decorators.md) ^7.24.1
- [babel-plugin-transform-imports-api](https://npm.io/package/babel-plugin-transform-imports-api.md) 1.0.0
- [@babel/plugin-transform-class-properties](https://npm.io/package/@babel/plugin-transform-class-properties.md) ^7.24.1
- [@rnx-kit/babel-preset-metro-react-native](https://npm.io/package/@rnx-kit/babel-preset-metro-react-native.md) ^1.1.8

## Recent versions

- 4.2.1 (latest) — 2026-07-17
- 4.2.2-beta.4 (beta) — 2026-09-08
- 4.2.2-alpha.2 (alpha) — 2026-09-01
- 3.6.40 (v3-latest) — 2026-04-13
- 3.6.40-beta.1 (v3-beta) — 2026-03-25
- 4.0.9-alpha.8 (test) — 2025-05-14
- 4.0.7-canary.6 (canary) — 2024-11-12
- 4.0.2 (next) — 2024-07-16
- 3.6.15-theta.0 (theta) — 2024-05-06
- 3.6.24-nightly.10 (nightly) — 2024-02-28
- 3.0.29 (3.0) — 2021-03-09
- 0.0.0-experimental.2 (experimental) — 2020-04-27
- 4.2.2-beta.3 — 2026-09-08
- 4.2.2-beta.1 — 2026-09-02
- 4.2.2-alpha.1 — 2026-08-24
- … 878 more at https://npm.io/package/babel-preset-taro/versions

## README

---
title: Babel 配置
---

Taro 项目的 Babel 配置位于根目录的 `babel.config.js` 文件中，里面默认添加了一个 preset：`babel-preset-taro`，它会根据项目的技术栈添加一些常用的 `presets` 和 `plugins`。

```js title="babel.config.js"
module.exports = {
  presets: [
    ['taro', {/** 配置项 */}]
  ]
}
```

开发者可以修改 `babel.config.js`，修改 `babel-preset-taro` 的配置项，或添加自己想要的 `presets` 和 `plugins`。

## babel-preset-taro

`babel-preset-taro` 会根据当前项目的技术栈，选择性地使用以下的 `presets` 和 `plugins`。


#### 1. 通用

##### presets

- `@babel/preset-env`
- `@babel/preset-typescript`（TypeScript 环境）

##### plugins

- `@babel/plugin-transform-runtime`
- `@babel/plugin-proposal-decorators`
- `@babel/plugin-transform-class-properties`
- `babel-plugin-dynamic-import-node`（小程序环境）

#### 2. React

##### presets

- `@babel/preset-react`

##### plugins

- `react-refresh/babel`

#### 3. Vue3

##### plugins

- `@vue/babel-plugin-jsx`

以下将详细介绍 `babel-preset-taro` 的配置项。

### reactJsxRuntime

:::note
只在使用 **React** 时生效。
:::

**默认值**：`'automatic'`

`@babel/preset-react` 的 [runtime](https://babeljs.io/docs/en/babel-preset-react#runtime) 配置项。

### hot

:::note
只在使用 **React** 时生效。
:::

**默认值**：`true`

是否引入 `react-refresh/babel` 来支持使用 [fast-refresh](h5#fast-refresh)。

### vueJsx

:::note
只在使用 **Vue3** 时生效。
:::

**默认值**：`true`

**类型**：`true` | `false` | `object`

是否使用 `@vue/babel-plugin-jsx` 来支持使用 `jsx`。

当传入一个 `object` 时，等同于设置为 `true`，且该 `object` 将会作为 `@vue/babel-plugin-jsx` 的参数。

### targets

**默认值**：

```js
{
  ios: '9',
  android: '5'
}
```

`@babel/preset-env` 的 [targets](https://babeljs.io/docs/en/babel-preset-env#targets) 配置项。

### useBuiltIns

**默认值**：`false`

**有效值**：`'entry'` | `'usage'` | `false`

#### useBuiltIns: 'entry'

:::info
**优点**：全局彻底 polyfill，就算 `node_modules` 中的依赖存在不兼容的代码，也能成功运行。

**缺点**：可能会引入冗余代码、影响全局变量。
:::

当传入 `'entry'` 时，会把 `@babel/preset-env` 的 [useBuiltIns](https://babeljs.io/docs/en/babel-preset-env#usebuiltins) 选项设为 `'entry'`、[corejs](https://babeljs.io/docs/en/babel-preset-env#corejs) 选项设为 `'3'`。

开发者需要在入口文件 `app.js` 中引入 `core-js`：

```js title="src/app.js"
import "core-js"
```

Babel 会根据 [targets](babel-config#targets)，引入对应的 `core-js` 依赖。例如上述代码会被编译为：

```js title="dist/app.js"
import "core-js/modules/es.string.pad-start";
import "core-js/modules/es.string.pad-end";
// ...
```

> 当然，因为这时 Taro 把 `corejs` 设置为 `'3'`，所以可以使用 `core-js@3` **手动按需引入的能力**，详情请见[文档](https://babeljs.io/docs/en/babel-preset-env#usebuiltins)。

#### useBuiltIns: 'usage'

:::info
**优点**：按需引入、不会影响全局变量。

**缺点**：默认不会处理 `node_modules` 中的依赖，需要手动配置 `babel-loader`。
:::

当传入 `'usage'` 时，会把 `@babel/plugin-transform-runtime` 的 [corejs](https://babeljs.io/docs/en/babel-plugin-transform-runtime#corejs) 选项设为 `3`。

> 注意：传入 `'usage'` 时， Taro 没有使用 `@babel/preset-env` 的 `useBuiltIns: 'usage'` 而是使用了 `@babel/plugin-transform-runtime` 的 `corejs: 3`。原因在于：一、两者同时设置时会产生冲突。二、后者相对于前者，不会影响全局变量。

#### useBuiltIns: false

当传入 `false` 时，会把 `@babel/preset-env` 的 [useBuiltIns](https://babeljs.io/docs/en/babel-preset-env#usebuiltins) 选项设为 `false`，此时不会引入 `core-js`。

### loose

**默认值**：`false`

同时是 `@babel/preset-env`、`@babel/plugin-transform-class-properties` 的 `loose` 配置项。

### debug

**默认值**：`false`

`@babel/preset-env` 的 [debug](https://babeljs.io/docs/en/babel-preset-env#debug) 配置项。

### modules

**默认值**：`false`

`@babel/preset-env` 的 [modules](https://babeljs.io/docs/en/babel-preset-env#modules) 配置项。

### spec

`@babel/preset-env` 的 [spec](https://babeljs.io/docs/en/babel-preset-env#spec) 配置项。

### configPath

`@babel/preset-env` 的 [configPath](https://babeljs.io/docs/en/babel-preset-env#configpath) 配置项。

### include

`@babel/preset-env` 的 [include](https://babeljs.io/docs/en/babel-preset-env#include) 配置项。

### exclude

`@babel/preset-env` 的 [exclude](https://babeljs.io/docs/en/babel-preset-env#exclude) 配置项。

### shippedProposals

`@babel/preset-env` 的 [shippedProposals](https://babeljs.io/docs/en/babel-preset-env#shippedproposals) 配置项。

### forceAllTransforms

`@babel/preset-env` 的 [forceAllTransforms](https://babeljs.io/docs/en/babel-preset-env#forcealltransforms) 配置项。


### decoratorsBeforeExport

`@babel/plugin-proposal-decorators` 的 [decoratorsBeforeExport](https://babeljs.io/docs/en/babel-plugin-proposal-decorators#decoratorsbeforeexport) 配置项。

### decoratorsLegacy

**默认值**：`true`

`@babel/plugin-proposal-decorators` 的 [lagacy](https://babeljs.io/docs/en/babel-plugin-proposal-decorators#legacy) 配置项。

### absoluteRuntime

**默认值**：开发者根目录 `node_modules` 中的 `@babel/plugin-transform-runtime` 的路径。

**类型**：`string`

`@babel/plugin-transform-runtime` 的 [absoluteRuntime](https://babeljs.io/docs/en/babel-plugin-transform-runtime#absoluteruntime) 配置项。

### version

**默认值**：开发者根目录 `node_modules` 中的 `@babel/plugin-transform-runtime` 的版本号。

**类型**：`string`

`@babel/plugin-transform-runtime` 的 [version](https://babeljs.io/docs/en/babel-plugin-transform-runtime#version) 配置项。

---
_Source: https://npm.io/package/babel-preset-taro · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._