@babel/plugin-transform-runtime

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

Un plugin que permite reutilizar el código auxiliar inyectado por Babel para reducir el tamaño del código.

nota

Los métodos de instancia como "foobar".includes("foo") solo funcionarán con core-js@3. Si necesitas aplicar polyfills, puedes importar directamente "core-js" o usar la opción useBuiltIns de @babel/preset-env.

Instalación

Instálalo como dependencia de desarrollo.

npm
Yarn
pnpm
Bun

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

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

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

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

y @babel/runtime como dependencia de producción (ya que es para el "runtime").

npm
Yarn
pnpm
Bun

npm install --save @babel/runtime

yarn add @babel/runtime

pnpm add @babel/runtime

bun add @babel/runtime

El plugin de transformación se usa típicamente solo en desarrollo, pero el runtime en sí será requerido por tu código en producción. Consulta los ejemplos a continuación para más detalles.

peligro

Cuando este plugin está habilitado, la opción useBuiltIns en @babel/preset-env NO debe configurarse. De lo contrario, este plugin podría no lograr aislar completamente el entorno.

¿Por qué?

Babel utiliza ayudantes muy pequeños para funciones comunes como _extend. Por defecto, esto se añade a cada archivo que lo requiera. Esta duplicación a veces es innecesaria, especialmente cuando tu aplicación está distribuida en múltiples archivos.

Aquí es donde entra el plugin @babel/plugin-transform-runtime: todos los ayudantes harán referencia al módulo @babel/runtime para evitar duplicación en tu salida compilada. El runtime se incluirá en tu compilación.

Otro propósito de este transformador es crear un entorno aislado para tu código. Si importas directamente core-js o @babel/polyfill y los built-ins que proporciona como Promise, Set y Map, estos contaminarán el ámbito global. Si bien esto podría ser aceptable para una aplicación o herramienta de línea de comandos, se convierte en un problema si tu código es una biblioteca que planeas publicar para que otros la usen o si no controlas exactamente el entorno donde se ejecutará tu código.

El transformador creará alias de estos built-ins a core-js para que puedas usarlos sin problemas sin requerir el polyfill.

Consulta la sección de detalles técnicos para más información sobre cómo funciona y los tipos de transformaciones que ocurren.

Uso

Mediante un archivo de configuración (Recomendado)

Sin opciones:

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

Con opciones (y sus valores por defecto):

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

El plugin asume por defecto que el usuario proporcionará todas las APIs que pueden recibir polyfills. De lo contrario, debe especificarse la opción corejs.

Mediante la CLI

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

Mediante la API de Node

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

Opciones

`absoluteRuntime`

boolean o string, por defecto false.

Esto permite a los usuarios ejecutar transform-runtime ampliamente en todo un proyecto. Por defecto, transform-runtime importa desde @babel/runtime/foo directamente, pero esto solo funciona si @babel/runtime está en el node_modules del archivo que se está compilando. Esto puede ser problemático para node_modules anidados, módulos enlazados con npm, o CLIs que residen fuera del proyecto del usuario, entre otros casos. Para evitar preocuparse por cómo se resuelve la ubicación del módulo runtime, esta opción permite resolver el runtime una vez inicialmente e insertar rutas absolutas al runtime en el código de salida.

El uso de rutas absolutas no es deseable si los archivos se compilan para usarse posteriormente, pero en contextos donde un archivo se compila y luego se consume inmediatamente, pueden ser bastante útiles.

consejo

Puedes leer más sobre cómo configurar opciones de plugins aquí

`corejs`

false, 2, 3 or { version: 2 | 3, proposals: boolean }, defaults to false.

e.g. ['@babel/plugin-transform-runtime', { corejs: 3 }],

History

Version	Changes
`v7.4.0`	Supports `{ proposals: boolean }`

Specifying a number will rewrite the helpers that need polyfillable APIs to reference helpers from that (major) version of core-js instead Please note that corejs: 2 only supports global variables (e.g. Promise) and static properties (e.g. Array.from), while corejs: 3 also supports instance properties (e.g. [].includes).

By default, @babel/plugin-transform-runtime doesn't polyfill proposals. If you are using corejs: 3, you can opt into this by enabling using the proposals: true option.

This option requires changing the dependency used to provide the necessary runtime helpers:

`corejs` option	Install command
`false`	`npm install --save @babel/runtime`
`2`	`npm install --save @babel/runtime-corejs2`
`3`	`npm install --save @babel/runtime-corejs3`

precaución

The corejs option will be removed in Babel 8. To inject polyfills, you can use babel-plugin-polyfill-corejs3 or babel-plugin-polyfill-corejs2 directly.

`helpers`

boolean, defaults to true.

Toggles whether or not inlined Babel helpers (classCallCheck, extends, etc.) are replaced with calls to @babel/runtime (or equivalent package).

For more information, see Helper aliasing.

precaución

The helpers option will be removed in Babel 8, as this plugin will only be used to inject helpers (including regeneratorRuntime, which will be handled as any other Babel helper).

`moduleName`

History

Version	Changes
`v7.24.0`	Added `moduleName` option

string, por defecto @babel/runtime.

Esta opción controla qué paquete de helpers usará @babel/plugin-transform-runtime al inyectar imports. Usa la siguiente prioridad:

La opción moduleName, si se especifica
Módulo de helpers sugerido por cualquier plugin babel-plugin-polyfill-*
- babel-plugin-polyfill-corejs3 sugiere @babel/runtime-corejs3
- babel-plugin-polyfill-corejs2 sugiere @babel/runtime-corejs2
Fallback a @babel/runtime

Nota que especificar la opción corejs habilita internamente el plugin babel-plugin-polyfill-corejs* correspondiente, afectando así el nombre final del módulo.

`regenerator`

boolean, defaults to true.

In older Babel version, this option used to toggles whether or not generator functions were transformed to use a regenerator runtime that does not pollute the global scope.

For more information, see Regenerator aliasing.

precaución

The regenerator option will be removed in Babel 8, as it will not be necessary anymore.

`useESModules`

boolean, defaults to false.

History

Version	Changes
`v7.13.0`	This option has been deprecated

When enabled, the transform will use helpers that do not get run through @babel/plugin-transform-modules-commonjs. This allows for smaller builds in module systems like webpack, since it doesn't need to preserve commonjs semantics.

For example, here is the classCallCheck helper with useESModules disabled:

JavaScript
exports.__esModule = true;

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

And, with it enabled:

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

precaución

The useESModules option has been deprecated and will be removed in Babel 8: starting from version 7.13.0, @babel/runtime's package.json uses "exports" option to automatically choose between CJS and ESM helpers.

`version`

Por defecto transform-runtime asume que @babel/runtime@7.0.0 está instalado. Si tienes versiones posteriores de @babel/runtime (o sus contrapartes corejs como @babel/runtime-corejs3) instaladas o listadas como dependencias, transform-runtime puede usar características más avanzadas.

Por ejemplo, si dependes de @babel/runtime@^7.24.0 puedes transpilar tu código con:

babel.config.json
{
  "plugins": [
    ["@babel/plugin-transform-runtime", {
      "version": "^7.24.0"
    }]
  ]
}

lo que resulta en un tamaño de paquete más reducido.

Detalles técnicos

El plugin transformador transform-runtime realiza tres funciones:

Requiere automáticamente @babel/runtime/regenerator al usar generadores/funciones asíncronas (configurable con la opción regenerator).
Puede usar core-js para helpers si es necesario, en lugar de asumir que será polirellenado por el usuario (configurable con la opción corejs)
Elimina automáticamente los helpers de Babel en línea y usa el módulo @babel/runtime/helpers en su lugar (configurable con la opción helpers).

¿Qué significa esto en la práctica? Básicamente, puedes usar built-ins como Promise, Set, Symbol, etc., así como todas las características de Babel que requieren un polyfill de forma transparente, sin contaminación global, lo que lo hace extremadamente adecuado para bibliotecas.

Asegúrate de incluir @babel/runtime como dependencia.

Alias para regenerator

Cuando usas funciones generadoras o asíncronas:

JavaScript
function* foo() {}

se genera lo siguiente:

JavaScript
"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
  );
}

Esto no es ideal porque depende del runtime de regenerator que contamina el ámbito global.

Sin embargo, con el transformador runtime, se compila a:

JavaScript
"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
  );
}

Esto permite usar el runtime de regenerator sin contaminar tu entorno actual.

Alias para `core-js`

A veces necesitas usar nuevos built-ins como Map, Set, Promise, etc. Normalmente, la única forma de usarlos es incluyendo un polyfill que contamina el ámbito global.

Esto se logra con la opción corejs.

El plugin transforma lo siguiente:

JavaScript
var sym = Symbol();

var promise = Promise.resolve();

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

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

en:

JavaScript
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));

Esto permite usar estos built-ins y métodos nativos de forma transparente sin preocuparte por su origen.

NOTA: Los métodos de instancia como "foobar".includes("foo") solo funcionarán cuando se use corejs: 3.

Alias para helpers

Normalmente, Babel coloca helpers en la parte superior de tu archivo para realizar tareas comunes y evitar duplicar código. A veces estos helpers pueden volverse voluminosos y crear duplicaciones innecesarias entre archivos. El transformador runtime reemplaza todas las llamadas a helpers por un módulo.

Esto significa que el siguiente código:

JavaScript
class Person {}

normalmente se convierte en:

JavaScript
"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);
};

sin embargo, el transformador runtime lo convierte en:

JavaScript
"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);
};

Opciones eliminadas

Las siguientes opciones se eliminaron en Babel 7.0.0:

useBuiltIns
polyfill

Instalación​

¿Por qué?​

Uso​

Mediante un archivo de configuración (Recomendado)​

Mediante la CLI​

Mediante la API de Node​

Opciones​

absoluteRuntime​

corejs​

helpers​

moduleName​

regenerator​

useESModules​

version​

Detalles técnicos​

Alias para regenerator​

Alias para core-js​

Alias para helpers​

Opciones eliminadas​

Instalación

¿Por qué?

Uso

Mediante un archivo de configuración (Recomendado)

Mediante la CLI

Mediante la API de Node

Opciones

`absoluteRuntime`

`corejs`

`helpers`

`moduleName`

`regenerator`

`useESModules`

`version`

Detalles técnicos

Alias para regenerator

Alias para `core-js`

Alias para helpers

Opciones eliminadas