@babel/preset-env

@babel/preset-env は、ターゲット環境で必要な構文変換（およびオプションでブラウザのポリフィル）を細かく管理する必要なく、最新の JavaScript を使用できるようにするスマートプリセットです。これにより、開発が容易になり、JavaScript バンドルも小さくなります。

インストール
どのように動作するのか？
Browserslist の統合
オプション

インストール

npm
Yarn
pnpm

npm install --save-dev @babel/preset-env

yarn add --dev @babel/preset-env

pnpm add --save-dev @babel/preset-env

どのように動作するのか？

@babel/preset-env は、browserslist、compat-table、および electron-to-chromium のような多数の素晴らしいオープンソースプロジェクトがなければ実現できませんでした。

これらのデータソースを活用して、サポートされているターゲット環境のどのバージョンがJavaScript構文またはブラウザ機能をサポートするようになったかのマッピングと、それらの構文と機能をBabel変換プラグインおよびcore-jsポリフィルへのマッピングを維持しています。

注意

@babel/preset-env は、TC39 プロセスのその段階では、どのブラウザでも実装されていないため、Stage 3 未満の JavaScript 構文の提案は含みません。これらは手動で含める必要があります。shippedProposals オプションは、一部のブラウザが既に実装している Stage 3 の提案を含めます。

@babel/preset-env は、指定したターゲット環境をすべて取得し、それらをマッピングと照合して、プラグインのリストをコンパイルし、それを Babel に渡します。

Browserslist の統合

ブラウザベースまたは Electron ベースのプロジェクトの場合、.browserslistrc ファイルを使用してターゲットを指定することをお勧めします。これは、autoprefixer、stylelint、eslint-plugin-compat など、エコシステムの多くのツールで使用されているため、この構成ファイルが既に存在する可能性があります。

デフォルトでは、@babel/preset-env は、ターゲットまたは ignoreBrowserslistConfig オプションが設定されていない限り、browserslist 構成ソースを使用します。

ヒント

browserslist のデフォルトクエリ（明示的にまたは browserslist 構成がない場合）に依存している場合は、preset-env の動作に関する情報について「ターゲットなし」セクションを確認してください。

たとえば、ブラウザの市場シェアが 0.25% を超える（IE 10 や BlackBerry のようなセキュリティアップデートのないブラウザは無視する）ユーザーに必要なポリフィルとコード変換のみを含めるには

babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "useBuiltIns": "entry",
        "corejs": "3.22"
      }
    ]
  ]
}

.browserslistrc

> 0.25%
not dead

または

package.json

{ "browserslist": "> 0.25%, not dead" }

注意

v7.4.5 以降、browserslist クエリは mobileToDesktop: true で解決されることに注意してください。たとえば、クエリのスナップショットを作成する場合は、npx browserslist --mobile-to-desktop ">0.25%, not dead" を実行します。

オプション

プリセットのオプション設定の詳細については、プリセットオプションのドキュメントを参照してください。

`targets`

string | Array<string> | { [string]: string }。@babel/preset-env のドキュメントで browserslist 関連のオプションが指定されていない場合は、トップレベルの targets オプションがデフォルトになり、それ以外の場合は {} になります。

使用方法については、targets オプションのドキュメントを参照してください。

`bugfixes`

boolean。デフォルトは false です。

追加されたバージョン: v7.9.0

注意

このオプションは、Babel 8 でデフォルトで有効になります。

デフォルトでは、@babel/preset-env（および一般的には Babel プラグイン）は、ECMAScript 構文機能を密接に関連する小さな機能のコレクションにグループ化しました。これらのグループは大きくなる可能性があり、「関数の引数」には分割代入、デフォルトパラメータ、残余パラメータなど、多くのエッジケースが含まれています。このグループ化情報から、Babel は @babel/preset-env の targets オプションに指定したブラウザサポートターゲットに基づいて、各グループを有効または無効にします。

このオプションを有効にすると、@babel/preset-env は、壊れた構文をターゲットブラウザでサポートされている最も近い *壊れていない最新の構文* にコンパイルしようとします。targets と使用している最新の構文の数によっては、コンパイルされたアプリのサイズが大幅に削減される可能性があります。このオプションは、別のプリセットを使用しなくても、@babel/preset-modules の機能をマージします。

`spec`

boolean。デフォルトは false です。

このプリセットでサポートされているプラグインに対して、より仕様に準拠していますが、潜在的により遅い変換を有効にします。

注意

このオプションは非推奨となり、Babel 8 で削除されます。Babel 7.13 以降で使用できるトップレベルの assumptions への移行を検討してください。開始点としてコピー＆ペーストできる、同等の assumptions ベースの構成については、@babel/preset-env の "loose" モードと "spec" モードからの移行を参照してください。

`loose`

boolean。デフォルトは false です。

このプリセットで許可されているプラグインに対して、"loose" 変換を有効にします。

注意

`modules`

"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false。デフォルトは "auto" です。

ES モジュール構文を別のモジュールタイプに変換することを有効にします。cjs は commonjs のエイリアスにすぎないことに注意してください。

これを false に設定すると、ES モジュールが保持されます。ネイティブ ES モジュールをブラウザに出荷する場合にのみ使用してください。Babel でバンドラーを使用している場合、デフォルトの modules: "auto" が常に推奨されます。

`modules: "auto"`

デフォルトでは、@babel/preset-env は caller データを使用して、ES モジュールとモジュール機能（例：import()）を変換する必要があるかどうかを判断します。通常、caller データはバンドラープラグイン（例：babel-loader、@rollup/plugin-babel）で指定されるため、自分で caller データを渡すことは推奨されません。渡された caller がバンドラープラグインのものを上書きする可能性があり、バンドラーが新しいモジュール機能をサポートする場合、将来的に最適ではない結果になる可能性があります。

`debug`

boolean。デフォルトは false です。

preset-env によって有効になっているポリフィルと変換プラグイン、および該当する場合は、どのターゲットでそれが必要になったかを console.log に出力します。

`include`

Array<string|RegExp>。デフォルトは [] です。

履歴

バージョン	変更点
`v7.4.0`	`core-js@3` ポリフィルの挿入のサポート

常に含めるプラグインの配列。

有効なオプションには、次のものが含まれます。

Babel プラグイン - 完全名と短縮名の両方がサポートされています。たとえば、以下は機能的に同等です。
- @babel/plugin-transform-spread
- @babel/transform-spread
- babel-transform-spread
- transform-spread
core-js@2 および core-js@3 の両方の組み込み機能（es.map、es.set、または es.object.assign など）。

プラグイン名は、完全にまたは部分的に指定できます（または RegExp を使用）。

受け入れ可能な入力

完全名 (string): "es.math.sign"
部分名 (string): "es.math.*" (es.math プレフィックスが付いたすべてのプラグインに解決されます)
RegExp オブジェクト: /^transform-.*$/ または new RegExp("^transform-modules-.*")

上記の . は、任意の文字に一致する RegExp に相当し、実際の '.' 文字ではないことに注意してください。また、glob 形式の * とは対照的に、RegExp では任意の文字を照合するために .* が使用されることにも注意してください。

このオプションは、ネイティブ実装にバグがある場合、またはサポートされていない機能とサポートされている機能の組み合わせが機能しない場合に役立ちます。

例えば、Node 4 はネイティブクラスをサポートしますが、スプレッドはサポートしません。もし super がスプレッド引数と共に使用された場合、@babel/plugin-transform-classes トランスフォームを include する必要があります。なぜなら、そうでなければ super を伴うスプレッドをトランスパイルすることは不可能だからです。

注意

include オプションと exclude オプションは、このプリセットに含まれるプラグインでのみ機能します。例えば、@babel/plugin-proposal-do-expressions を含めたり、@babel/plugin-proposal-function-bind を除外したりするとエラーが発生します。このプリセットに含まれていないプラグインを使用するには、"plugins" に直接追加してください。

`exclude`

Array<string|RegExp>。デフォルトは [] です。

常に除外/削除するプラグインの配列。

指定できるオプションは include オプションと同じです。

このオプションは、例えば、Babel の async-to-gen の代わりに、fast-async のような別のプラグインを使用している場合に、@babel/plugin-transform-regenerator のようなトランスフォームを除外するのに役立ちます。

`useBuiltIns`

"usage" | "entry" | false、デフォルトは false。

このオプションは、@babel/preset-env がポリフィルをどのように処理するかを設定します。

usage または entry オプションのいずれかを使用すると、@babel/preset-env は core-js モジュールへの直接参照をベアインポート（または require）として追加します。これは、core-js がファイル自体を基準に解決される必要があり、アクセス可能でなければならないことを意味します。

@babel/polyfill は 7.4.0 で非推奨になったため、core-js を直接追加し、corejs オプションでバージョンを設定することをお勧めします。

npm
Yarn
pnpm

npm install core-js@3 --save

# or

npm install core-js@2 --save

yarn add core-js@3

# or

yarn add core-js@2

pnpm add core-js@3

# or

pnpm add core-js@2

`useBuiltIns: 'entry'`

履歴

バージョン	変更点
`v7.4.0`	`"core-js/stable"` および `"regenerator-runtime/runtime"` のエントリインポートを置き換えます
`v7.0.0`	`"@babel/polyfill"` のエントリインポートを置き換えます

ヒント

import "core-js"; はアプリケーション全体で一度だけ使用してください。

@babel/polyfill を使用している場合は、既に core-js が含まれています。それを2回インポートするとエラーが発生します。

これらのパッケージを複数回インポートまたは require すると、グローバルな衝突や、追跡が困難なその他の問題が発生する可能性があります。import ステートメントのみを含む単一のエントリファイルを作成することをお勧めします。

このオプションは、環境に基づいて異なる core-js エントリポイントへの個々のインポートで、import "core-js/stable"; および require("core-js"); ステートメントを置き換える新しいプラグインを有効にします。

入力

JavaScript
import "core-js";

出力 (環境によって異なる)

JavaScript
import "core-js/modules/es.string.pad-start";
import "core-js/modules/es.string.pad-end";

"core-js" をインポートすると、考えられるすべての ECMAScript 機能のポリフィルがロードされます。もし、それらの一部だけが必要だとわかっている場合はどうすればよいでしょうか？core-js@3 を使用する場合、@babel/preset-env はすべての単一の core-js エントリポイントとそれらの組み合わせを最適化できます。例えば、配列メソッドと新しい Math プロポーザルのみをポリフィルしたいかもしれません。

入力

JavaScript
import "core-js/es/array";
import "core-js/proposals/math-extensions";

出力 (環境によって異なる)

JavaScript
import "core-js/modules/es.array.unscopables.flat";
import "core-js/modules/es.array.unscopables.flat-map";
import "core-js/modules/esnext.math.clamp";
import "core-js/modules/esnext.math.deg-per-rad";
import "core-js/modules/esnext.math.degrees";
import "core-js/modules/esnext.math.fscale";
import "core-js/modules/esnext.math.rad-per-deg";
import "core-js/modules/esnext.math.radians";
import "core-js/modules/esnext.math.scale";

異なるエントリポイントの詳細については、core-js のドキュメントを参照してください。

注意

core-js@2 を使用している場合（corejs: "2" オプションを明示的に使用するか、暗黙的に使用する場合）、@babel/preset-env は @babel/polyfill のインポートと require も変換します。この動作は、異なる core-js バージョンで @babel/polyfill を使用することができないため、非推奨です。

`useBuiltIns: 'usage'`

各ファイルで使用されている場合に、ポリフィルの特定のインポートを追加します。バンドラーが同じポリフィルを一度だけロードするという事実を利用します。

入力

a.js
var a = new Promise();

b.js
var b = new Map();

出力 (環境がサポートしていない場合)

a.js
import "core-js/modules/es.promise";
var a = new Promise();

b.js
import "core-js/modules/es.map";
var b = new Map();

出力 (環境がサポートしている場合)

a.js
var a = new Promise();

b.js
var b = new Map();

`useBuiltIns: false`

ファイルごとにポリフィルを自動的に追加せず、import "core-js" または import "@babel/polyfill" を個々のポリフィルに変換しません。

`corejs`

追加: v7.4.0

string または { version: string, proposals: boolean }、デフォルトは "2.0"。version 文字列には、サポートされている任意の core-js バージョンを指定できます。例えば、"3.33" や "2.0" など。

このオプションは useBuiltIns: usage または useBuiltIns: entry と一緒に使用した場合にのみ効果があり、@babel/preset-env が core-js のバージョンでサポートされているポリフィルを挿入することを保証します。マイナーバージョンを指定することをお勧めします。そうしないと、"3" は最新機能のポリフィルを含まない可能性がある "3.0" として解釈される可能性があります。

デフォルトでは、安定した ECMAScript 機能のポリフィルのみが挿入されます。プロポーザルのポリフィルが必要な場合は、3つの異なるオプションがあります。

useBuiltIns: "entry" を使用する場合、プロポーザルポリフィルを直接インポートできます: import "core-js/proposals/string-replace-all"。
useBuiltIns: "usage" を使用する場合、2つの異なる代替案があります。
- shippedProposals オプションを true に設定します。これにより、ブラウザでしばらくの間出荷されているプロポーザルのポリフィルとトランスフォームが有効になります。
- corejs: { version: "3.8", proposals: true } を使用します。これにより、core-js@3.8 でサポートされているすべてのプロポーザルのポリフィルが有効になります。

`forceAllTransforms`

boolean。デフォルトは false です。

例

Babel 7 の JavaScript 設定ファイルサポートにより、env が production に設定されている場合、すべてのトランスフォームを強制的に実行できます。

babel.config.js
module.exports = function(api) {
  return {
    presets: [
      [
        "@babel/preset-env",
        {
          targets: {
            chrome: 59,
            edge: 13,
            firefox: 50,
          },
          // for uglifyjs...
          forceAllTransforms: api.env("production"),
        },
      ],
    ],
  };
};

危険

targets.uglify は非推奨であり、これを優先して次のメジャーで削除されます。

デフォルトでは、このプリセットはターゲット環境に必要なすべての変換を実行します。出力が UglifyJS または ES5 のみをサポートする環境で実行される場合に役立つ、すべての変換を強制的に実行する場合は、このオプションを有効にします。

ヒント

ES6 構文をサポートする代替ミニファイアが必要な場合は、Terser をお勧めします。

`configPath`

string、デフォルトは process.cwd()

browserslist の設定検索が開始される開始点。見つかるまでシステムのルートまで昇順に検索されます。

`ignoreBrowserslistConfig`

boolean、デフォルトは false

browserslist 設定ソースを使用するかどうかを切り替えます。これには、browserslist ファイルを検索したり、package.json 内の browserslist キーを参照したりすることが含まれます。これは、Babel でコンパイルされないファイルに browserslist 設定を使用するプロジェクトに役立ちます。

`browserslistEnv`

追加: v7.10.0 string、デフォルトは undefined

使用する Browserslist 環境。

`shippedProposals`

boolean、デフォルトは false

履歴

バージョン	変更点
`v7.14.0`	プライベートフィールドのブランドチェックを含める
`v7.12.0`	クラスの静的ブロックとインポートアサーションを含める
`v7.10.0`	クラスプロパティとプライベートメソッドを含める
`v7.9.0`	数値区切り文字を含める

ブラウザで出荷された組み込み/機能提案のサポートを有効にするかどうかを切り替えます。ターゲット環境で機能提案のネイティブサポートがある場合は、変換を実行する代わりに、一致するパーサー構文プラグインが有効になります。提案はブラウザに実装される前に変更される可能性があるため、これは@babel/preset-stage-3 と同じ変換を有効にするわけではないことに注意してください。

現在、以下がサポートされています

useBuiltIns: "usage" を使用した場合に挿入される組み込み

esnext.global-this (core-js@3 のみでサポート)
esnext.string.match-all (core-js@3 のみでサポート)

機能

具体化された機能 これらの機能は、以前の Babel バージョンでは shippedProposals フラグの背後にありました。現在では一般的に利用可能です。

プリセットオプションの設定の詳細については、こちらを参照してください

注意事項

効果のない browserslist クエリ

op_mini all は有効な browserslist クエリですが、Opera Mini のサポートデータがないため、preset-env では現在無視されています。

インストール​

どのように動作するのか？​

Browserslist の統合​

オプション​

targets​

bugfixes​

spec​

loose​

modules​

modules: "auto"​

debug​

include​

exclude​

useBuiltIns​

useBuiltIns: 'entry'​

useBuiltIns: 'usage'​

useBuiltIns: false​

corejs​

forceAllTransforms​

configPath​

ignoreBrowserslistConfig​

browserslistEnv​

shippedProposals​

注意事項​

効果のない browserslist クエリ​

インストール

どのように動作するのか？

Browserslist の統合

オプション

`targets`

`bugfixes`

`spec`

`loose`

`modules`

`modules: "auto"`

`debug`

`include`

`exclude`

`useBuiltIns`

`useBuiltIns: 'entry'`

`useBuiltIns: 'usage'`

`useBuiltIns: false`

`corejs`

`forceAllTransforms`

`configPath`

`ignoreBrowserslistConfig`

`browserslistEnv`

`shippedProposals`

注意事項

効果のない browserslist クエリ