@babel/plugin-transform-runtime

Плагин, который позволяет повторно использовать инжектированный Babel код помощников, чтобы сэкономить размер кода.

ПРИМЕЧАНИЕ: Методы экземпляра, такие как "foobar".includes("foo"), будут работать только с core-js@3. Если вам нужно их полифилить, вы можете напрямую импортировать "core-js" или использовать опцию @babel/preset-env's useBuiltIns.

Установка​

Установите его как зависимость разработки.

npm install --save-dev @babel/plugin-transform-runtime

yarn add --dev @babel/plugin-transform-runtime

pnpm add --save-dev @babel/plugin-transform-runtime

и @babel/runtime в качестве производственной зависимости (так как она предназначена для «времени выполнения»).

npm install --save @babel/runtime

yarn add @babel/runtime

pnpm add @babel/runtime

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

При включении этого плагина опция useBuiltIns в @babel/preset-env должна быть отключена. В противном случае этот плагин может не полностью изолировать среду.

Почему?​

Babel использует очень маленькие помощники для общих функций, таких как _extend. По умолчанию это будет добавлено в каждый файл, который его требует. Эта дубликация иногда не нужна, особенно когда ваше приложение распределено по нескольким файлам.

Именно здесь и вступает в игру плагин @babel/plugin-transform-runtime: все помощники будут ссылаться на модуль @babel/runtime, чтобы избежать дублирования в вашем скомпилированном выводе. Модуль времени выполнения будет скомпилирован в ваш сборник.

Другая цель этого преобразователя — создать изолированную среду для вашего кода. Если вы напрямую импортируете core-js или @babel/polyfill и встроенные функции, которые он предоставляет, такие как Promise, Set и Map, они загрязнят глобальную область видимости. Хотя это может подойти для приложения или инструмента командной строки, это становится проблемой, если ваш код является библиотекой, которую вы намереваетесь опубликовать для других пользователей, или если вы не можете точно контролировать среду, в которой будет выполняться ваш код.

Преобразователь переименует эти встроенные функции на core-js, чтобы вы могли использовать их без проблем, без необходимости подключать полифил.

Дополнительную информацию о том, как это работает и какие преобразования происходят, см. в разделе «Технические подробности».

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

С конфигурационным файлом (Рекомендуется)​

Без опций:

{
  "plugins": ["@babel/plugin-transform-runtime"]
}

С опциями (и их значениями по умолчанию):

{
  "plugins": [
    [
      "@babel/plugin-transform-runtime",
      {
        "absoluteRuntime": false,
        "corejs": false,
        "helpers": true,
        "regenerator": true,
        "version": "7.0.0-beta.0"
      }
    ]
  ]
}

Плагин по умолчанию предполагает, что все полифильные API будут предоставлены пользователем. В противном случае необходимо указать опцию corejs.

Через командную строку​

babel --plugins @babel/plugin-transform-runtime script.js

Через API Node​

require("@babel/core").transformSync("code", {
  plugins: ["@babel/plugin-transform-runtime"],
});

Опции​

corejs​

false, 2, 3 или { version: 2 | 3, proposals: boolean }, по умолчанию false.

Например, ['@babel/plugin-transform-runtime', { corejs: 3 }],

Указание числа перепишет помощников, которым необходимы полифильные API, чтобы они ссылались на помощников из этой (главной) версии core-js вместо нее. Обратите внимание, что corejs: 2 поддерживает только глобальные переменные (например, Promise) и статические свойства (например, Array.from), в то время как corejs: 3 также поддерживает свойства экземпляров (например, [].includes).

По умолчанию @babel/plugin-transform-runtime не полифилит предложения. Если вы используете corejs: 3, вы можете включить это, используя опцию proposals: true.

Для этой опции необходимо изменить зависимость, используемую для предоставления необходимых помощников времени выполнения:

helpers​

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

Включает или отключает замену встроенных помощников Babel (classCallCheck, extends, и т. д.) вызовами к moduleName.

Для получения дополнительной информации см. Переименование помощников.

polyfill​

Эта опция была удалена в версии 7.

regenerator​

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

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

Для получения дополнительной информации см. Переименование генераторов.

useBuiltIns​

Эта опция была удалена в версии 7.

useESModules​

⚠️ Эта опция устарела: начиная с версии 7.13.0, @babel/runtime's package.json использует опцию "exports" для автоматического выбора между помощниками CJS и ESM.

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

При включении преобразование будет использовать помощников, которые не проходят через @babel/plugin-transform-modules-commonjs. Это позволяет создавать более компактные сборки в системах модулей, таких как webpack, так как им не нужно сохранять семантику CommonJS.

Например, вот помощник classCallCheck с отключенной опцией useESModules:

exports.__esModule = true;

exports.default = function(instance, Constructor) {
  if (!(instance instanceof Constructor)) {
    throw new TypeError("Cannot call a class as a function");
  }
};

И, с включенной опцией:

export default function(instance, Constructor) {
  if (!(instance instanceof Constructor)) {
    throw new TypeError("Cannot call a class as a function");
  }
}

absoluteRuntime​

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

Это позволяет пользователям широко использовать transform-runtime в рамках всего проекта. По умолчанию transform-runtime импортирует из @babel/runtime/foo напрямую, но это работает только если @babel/runtime находится в node_modules файла, который компилируется. Это может быть проблемой для вложенных node_modules, модулей, связанных с npm, или командных строк, которые находятся вне проекта пользователя, среди других случаев. Чтобы избежать необходимости беспокоиться о том, как решается расположение модуля времени выполнения, это позволяет пользователям решать расположение времени выполнения один раз и затем вставлять абсолютные пути к времени выполнения в выходной код.

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

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

version​

По умолчанию преобразователь времени выполнения предполагает, что @babel/runtime@7.0.0 установлен. Если у вас установлены более поздние версии @babel/runtime (или их аналоги corejs, например, @babel/runtime-corejs3) или они перечислены как зависимости, преобразователь времени выполнения может использовать более продвинутые возможности.

Например, если вы зависите от @babel/runtime-corejs2@7.7.4, вы можете транспилировать свой код с помощью

{
  "plugins": [
    [
      "@babel/plugin-transform-runtime",
      {
        "absoluteRuntime": false,
        "corejs": 2,
        "version": "^7.7.4"
      }
    ]
  ]
}

что приводит к уменьшению размера сборки.

Технические подробности​

Плагин преобразования transform-runtime выполняет три действия:

• Автоматически подключает @babel/runtime/regenerator при использовании функций генераторов/асинхронных функций (включается/выключается опцией regenerator).
• Может использовать core-js для помощников, если необходимо, вместо того, чтобы предполагать, что они будут полифилированы пользователем (включается/выключается опцией corejs).
• Автоматически удаляет встроенные помощники Babel и использует модуль @babel/runtime/helpers вместо них (включается/выключается опцией helpers).

Что это на самом деле означает? В основном вы можете использовать встроенные функции, такие как Promise, Set, Symbol, и т. д., а также все возможности Babel, которые требуют полифила, без загрязнения глобальной области видимости, что делает его очень подходящим для библиотек.

Убедитесь, что вы включили @babel/runtime в качестве зависимости.

Переименование генераторов​

Всякий раз, когда вы используете функцию-генератор или асинхронную функцию:

function* foo() {}

генерируется следующее:

"use strict";

var _marked = [foo].map(regeneratorRuntime.mark);

function foo() {
  return regeneratorRuntime.wrap(
    function foo$(_context) {
      while (1) {
        switch ((_context.prev = _context.next)) {
          case 0:
          case "end":
            return _context.stop();
        }
      }
    },
    _marked[0],
    this
  );
}

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

Однако, с преобразователем runtime, он компилируется в:

"use strict";

var _regenerator = require("@babel/runtime/regenerator");

var _regenerator2 = _interopRequireDefault(_regenerator);

function _interopRequireDefault(obj) {
  return obj && obj.__esModule ? obj : { default: obj };
}

var _marked = [foo].map(_regenerator2.default.mark);

function foo() {
  return _regenerator2.default.wrap(
    function foo$(_context) {
      while (1) {
        switch ((_context.prev = _context.next)) {
          case 0:
          case "end":
            return _context.stop();
        }
      }
    },
    _marked[0],
    this
  );
}

Это означает, что вы можете использовать исполняемый файл regenerator runtime, не загрязняя текущую среду.

core-js алиасинг​

Иногда вам может потребоваться использовать новые встроенные функции, такие как Map, Set, Promise и т. д. Обычно единственный способ использовать их — включить глобально загрязняющую полизаполняющую.

Это с опцией corejs.

Плагин преобразует следующее:

var sym = Symbol();

var promise = Promise.resolve();

var check = arr.includes("yeah!");

console.log(arr[Symbol.iterator]());

в следующее:

import _getIterator from "@babel/runtime-corejs3/core-js/get-iterator";
import _includesInstanceProperty from "@babel/runtime-corejs3/core-js-stable/instance/includes";
import _Promise from "@babel/runtime-corejs3/core-js-stable/promise";
import _Symbol from "@babel/runtime-corejs3/core-js-stable/symbol";

var sym = _Symbol();

var promise = _Promise.resolve();

var check = _includesInstanceProperty(arr).call(arr, "yeah!");

console.log(_getIterator(arr));

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

ПРИМЕЧАНИЕ: Методы экземпляров, такие как "foobar".includes("foo"), будут работать только при использовании corejs: 3.

Helper алиасинг​

Обычно Babel размещает вспомогательные функции в начале вашего файла для выполнения общих задач, чтобы избежать дублирования кода в текущем файле. Иногда эти вспомогательные функции могут стать немного громоздкими и добавлять ненужное дублирование в файлы. Преобразователь runtime заменяет все вызовы вспомогательных функций на модуль.

Это означает, что следующий код:

class Person {}

обычно преобразуется в:

"use strict";

function _classCallCheck(instance, Constructor) {
  if (!(instance instanceof Constructor)) {
    throw new TypeError("Cannot call a class as a function");
  }
}

var Person = function Person() {
  _classCallCheck(this, Person);
};

Преобразователь runtime , однако, преобразует это в:

"use strict";

var _classCallCheck2 = require("@babel/runtime/helpers/classCallCheck");

var _classCallCheck3 = _interopRequireDefault(_classCallCheck2);

function _interopRequireDefault(obj) {
  return obj && obj.__esModule ? obj : { default: obj };
}

var Person = function Person() {
  (0, _classCallCheck3.default)(this, Person);
};