@babel/preset-env

@babel/preset-env — это умный пресет, который позволяет использовать новейший JavaScript без необходимости микроуправления преобразованиями синтаксиса (и, по желанию, полифиллами браузера) необходимыми для вашей целевой среды(ы). Это делает вашу жизнь проще и уменьшает размер JavaScript-пакетов!

• Установить
• Как это работает?
• Интеграция с Browserslist
• Параметры

Установить​

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 не будет включать предложения по синтаксису JavaScript с уровнем поддержки ниже Stage 3, так как на этой стадии процесса TC39 они всё равно не будут реализованы ни одним браузером. Эти предложения придётся включать вручную. Параметр shippedProposals включит предложения Stage 3, уже реализованные некоторыми браузерами.

@babel/preset-env берёт любые указанные целевые среды и проверяет их на соответствие своим сопоставлениям, чтобы скомпилировать список плагинов и передать его Babel.

Интеграция с Browserslist​

Для проектов на основе браузера или Electron рекомендуется использовать файл .browserslistrc для указания целей. У вас, возможно, уже есть этот конфигурационный файл, так как он используется многими инструментами в экосистеме, такими как autoprefixer, stylelint, eslint-plugin-compat и многие другие.

По умолчанию @babel/preset-env будет использовать источники конфигурации browserslist за исключением случаев, когда заданы параметры targets или ignoreBrowserslistConfig.

Обратите внимание, что если вы полагаетесь на запросы по умолчанию browserslist (явным образом или в отсутствии конфигурации browserslist), вам следует ознакомиться с разделом Без целей для получения информации о поведении preset-env.

Например, чтобы включить только полифиллы и преобразования кода, необходимые для пользователей, чьи браузеры имеют >0,25% доли рынка (игнорируя браузеры без обновлений безопасности, такие как IE 10 и BlackBerry):

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

> 0.25%
not dead

или

{ "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 }, по умолчанию равен верхнему параметру targets в случае отсутствия параметров, связанных с browserslist, в документации @babel/preset-env, в противном случае равен {}.

Для использования, обратитесь к документации по параметру targets.

bugfixes​

boolean, по умолчанию равен false.

Добавлен в: v7.9.0

Примечание: Эти оптимизации будут включены по умолчанию в Babel 8

По умолчанию @babel/preset-env (и плагины Babel в целом) группируют функции синтаксиса ECMAScript в коллекции тесно связанных мелких функций. Эти группы могут быть большими и включать множество исключительных случаев, например, «аргументы функции» включают деструктурированные, по умолчанию и остаточные параметры. На основании этой группированной информации Babel включает или отключает каждую группу в зависимости от целевой поддержки браузера, которую вы указываете для параметра @babel/preset-env’s targets.

При включенном этом параметре @babel/preset-env пытается скомпилировать сломанный синтаксис в наиболее близкий несломанный современный синтаксис, поддерживаемый вашими целевыми браузерами. В зависимости от вашего targets и от того, сколько вы используете современного синтаксиса, это может привести к существенному уменьшению размера скомпилированного приложения. Этот параметр объединяет функции @babel/preset-modules без необходимости использования другого пресета.

spec​

boolean, по умолчанию равен false.

Включить более совместимые с спецификацией, но потенциально более медленные, преобразования для любых плагинов в этом пресете, которые их поддерживают.

loose​

boolean, по умолчанию равен false.

Включить «слабые» преобразования для любых плагинов в этом пресете, которые их разрешают.

⚠️ Рассмотрите возможность миграции на верхнеуровневый assumptions, доступный начиная с Babel 7.13.

modules​

"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false, по умолчанию равен "auto".

Включить преобразование синтаксиса модулей ES в другой тип модуля. Обратите внимание, что cjs это просто псевдоним для commonjs.

Установка этого значения в false сохранит модули ES. Используйте это только в том случае, если вы планируете отправлять native ES Modules в браузеры. Если вы используете пакетник с Babel, по умолчанию modules: "auto" всегда предпочтительнее.

modules: "auto"​

По умолчанию @babel/preset-env использует данные caller для определения того, следует ли преобразовывать модули ES и функции модулей (например, import()) в другие типы модулей. Как правило, данные caller будут указаны в плагинах пакетника (например, babel-loader, @rollup/plugin-babel) и поэтому не рекомендуется передавать данные caller самостоятельно — переданные данные caller могут перезаписать данные от плагинов пакетника, и в будущем вы можете получить не оптимальные результаты, если пакетники поддерживают новые функции модулей.

debug​

boolean, по умолчанию равен false.

Выводит в console.log полифиллы и плагины преобразования, включённые preset-env, и, применимо, какой из ваших целевых вариантов потребовал этого.

include​

Array<string|RegExp>, по умолчанию равен [].

Массив плагинов, которые всегда необходимо включать.

Допустимые варианты включают любые:

• Плагины 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 для соответствия любому символу, а не фактический символ '.'. Также обратите внимание, что для соответствия любому символу используется .* в RegExp, а не * в формате glob.

Этот параметр полезен, если в реализации есть ошибка или сочетание неподдерживаемой функции + поддерживаемой не работает.

Например, Node 4 поддерживает native классы, но не spread. Если super используется со spread-аргументом, то преобразование @babel/plugin-transform-classes необходимо includeть, так как невозможно транскрибировать spread с super в противном случае.

ПРИМЕЧАНИЕ: Опции include и exclude только работают с плагинами, включёнными в этот пресет; поэтому, например, включение @babel/plugin-proposal-do-expressions или исключение @babel/plugin-proposal-function-bind приведёт к ошибкам. Чтобы использовать плагин, не включённый в этот пресет, добавьте его в свой "plugins" напрямую.

Исключение плагинов​

Массив плагинов, которые всегда нужно исключать/удалять, по умолчанию [].

Возможные варианты такие же, как и у опции include.

Эта опция полезна для исключения преобразования, такого как @babel/plugin-transform-regenerator, если вы не используете генераторы и не хотите включать regeneratorRuntime (при использовании useBuiltIns ) или для использования другого плагина, например, fast-async вместо асинхронных генераторов Babel.

Использование встроенных полифиллов​

"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 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​

ПРИМЕЧАНИЕ: Используйте import "core-js"; только один раз во всём приложении. Если вы используете @babel/polyfill, оно уже включает core-js; повторный импорт приведёт к ошибке. Множественные импорты или require этих пакетов могут вызвать глобальные коллизии и другие проблемы, которые трудно отследить. Рекомендуется создать один файл входа, содержащий только import операторы.

Эта опция включает новый плагин, который заменяет import "core-js/stable"; и require("core-js"); операторы отдельными импортами в разные core-js точки входа в зависимости от среды.

Вход

import "core-js";

Выход (различается в зависимости от среды)

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 предложений:

Вход

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

Выход (различается в зависимости от среды)

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 также преобразует импорты и require @babel/polyfill. Это поведение устарело, потому что использовать @babel/polyfill с разными версиями core-js невозможно.

Использование usebuiltins​

Добавляет конкретные импорты для полифиллов, когда они используются в каждом файле. Мы используем тот факт, что бандлер загрузит один и тот же полифилл только один раз.

Вход

var a = new Promise();

var b = new Map();

Выход (если среда её не поддерживает)

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

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

Выход (если среда её поддерживает)

var a = new Promise();

var b = new Map();

Отключение usebuiltins​

Автоматически не добавлять полифиллы на файл, и не преобразовывать import "core-js" или import "@babel/polyfill" в отдельные полифиллы.

core-js​

Добавлена в: v7.4.0

string или { version: string, proposals: boolean }, по умолчанию "2.0". Строка version может быть любой поддерживаемой версией core-js. Например, "3.8" или "2.0".

Эта опция действует только при использовании вместе с useBuiltIns: usage или useBuiltIns: entry, и гарантирует, что @babel/preset-env вставляет полифиллы, поддерживаемые вашей версией core-js. Рекомендуется указывать незначительную версию, иначе "3" будет интерпретировано как "3.0", что может не включать полифиллы для последних функций.

По умолчанию вводятся только полифиллы для стабильных функций ECMAScript: если вы хотите полифиллить предложения, у вас есть три различных варианта:

• При использовании useBuiltIns: "entry", вы можете напрямую импортировать полифилл для предложений: import "core-js/proposals/string-replace-all".
• При использовании useBuiltIns: "usage" у вас есть два различных варианта:
  • Установите опцию shippedProposals в true. Это включит полифиллы и преобразования для предложений, которые уже некоторое время поддерживаются браузерами.
  • Используйте corejs: { version: "3.8", proposals: true }. Это включит полифиллирование всех предложений, поддерживаемых core-js@3.8.

Принудительное выполнение всех преобразований​

boolean, по умолчанию false.

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 или ссылку на ключ browserslist внутри package.json. Это полезно для проектов, использующих конфигурацию browserslist для файлов, которые не будут компилироваться с помощью Babel.

browserslistenv​

Добавлена в: v7.10.0 string, по умолчанию undefined

Среда Browserslist для использования.

Поддержка встроенных предложений​

boolean, по умолчанию false

Включает поддержку встроенных/предложенных функций, которые были реализованы в браузерах. Если ваши целевые среды поддерживают родную реализацию предлагаемой функции, соответствующий плагин синтаксического анализатора включен вместо выполнения каких-либо преобразований. Обратите внимание, что это не включает те же преобразования, что и @babel/preset-stage-3, так как предложения могут продолжать изменяться до их внедрения в браузеры.

В настоящее время поддерживаются следующие:

Встроенные модули, вставленные при использовании useBuiltIns: "usage"

• esnext.global-this (только поддерживается core-js@3)
• esnext.string.match-all (только поддерживается core-js@3)

Особенности

• Статический блок класса
• Утверждения импорта (только для парсинга)
• Проверка бренда приватных полей

Реализованные особенности Эти функции были за экраном shippedProposals флага в более старых версиях Babel. Сейчас они доступны в общем доступе.

• Свойства класса
• Разделитель чисел
• Приватные методы

Вы можете узнать больше о конфигурировании параметров пресетов здесь

Ограничения​

Неэффективные запросы browserslist​

Хотя op_mini all является допустимым запросом browserslist, пресет-env в настоящее время игнорирует его из-за недостатка данных поддержки для Opera Mini.