@babel/plugin-transform-runtime

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

Un plugin permettant de réutiliser le code d'assistance injecté par Babel pour réduire la taille du code.

note

Les méthodes d'instance comme "foobar".includes("foo") fonctionneront uniquement avec core-js@3. Si vous avez besoin de les polyfill, vous pouvez importer directement "core-js" ou utiliser l'option useBuiltIns de @babel/preset-env.

Installation

Installez-le en tant que dépendance de développement.

npm

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

Yarn

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

pnpm

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

Bun

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

et @babel/runtime en tant que dépendance de production (puisqu'il s'agit du "runtime").

npm

npm install --save @babel/runtime

Yarn

yarn add @babel/runtime

pnpm

pnpm add @babel/runtime

Bun

bun add @babel/runtime

Le plugin de transformation est généralement utilisé uniquement en développement, mais le runtime lui-même sera une dépendance de votre code déployé. Consultez les exemples ci-dessous pour plus de détails.

danger

Lorsque ce plugin est activé, l'option useBuiltIns de @babel/preset-env ne doit pas être définie. Sinon, ce plugin pourrait ne pas pouvoir isoler complètement l'environnement.

Pourquoi ?

Babel utilise de petits helpers pour des fonctions communes comme _extend. Par défaut, ils sont ajoutés à chaque fichier qui en a besoin. Cette duplication est parfois inutile, surtout lorsque votre application est répartie sur plusieurs fichiers.

C'est là qu'intervient le plugin @babel/plugin-transform-runtime : tous les helpers référenceront le module @babel/runtime pour éviter les duplications dans votre sortie compilée. Le runtime sera compilé dans votre build.

Un autre objectif de ce transformateur est de créer un environnement isolé (sandbox) pour votre code. Si vous importez directement core-js ou @babel/polyfill et les built-ins fournis comme Promise, Set et Map, ceux-ci pollueront la portée globale. Bien que cela soit acceptable pour une application ou un outil en ligne de commande, cela pose problème si votre code est une bibliothèque destinée à être publiée ou si vous ne contrôlez pas précisément l'environnement d'exécution.

Le transformateur aliasera ces built-ins vers core-js pour une utilisation transparente sans nécessiter le polyfill.

Consultez la section détails techniques pour plus d'informations sur le fonctionnement et les types de transformations appliquées.

Utilisation

Avec un fichier de configuration (Recommandé)

Sans options :

babel.config.json

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

Avec options (et leurs valeurs par défaut) :

babel.config.json

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

Le plugin suppose par défaut que toutes les API polyfillables seront fournies par l'utilisateur. Sinon, l'option corejs doit être spécifiée.

Via CLI

Shell

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

Via l'API Node

JavaScript

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

Options

absoluteRuntime

boolean ou string, par défaut false.

Permet d'exécuter transform-runtime à grande échelle sur un projet entier. Par défaut, transform-runtime importe directement depuis @babel/runtime/foo, mais cela ne fonctionne que si @babel/runtime est dans les node_modules du fichier compilé. Ceci peut poser problème avec des node_modules imbriqués, des modules npm linkés, ou des CLI externes au projet. Pour éviter les problèmes de résolution d'emplacement du runtime, cette option permet de résoudre le runtime une fois, puis d'insérer des chemins absolus vers celui-ci dans le code généré.

Les chemins absolus ne sont pas souhaitables pour des fichiers compilés pour une utilisation ultérieure, mais ils sont utiles lorsque les fichiers sont compilés puis immédiatement consommés.

astuce

Vous pouvez en savoir plus sur la configuration des options de plugin ici

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

attention

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.

attention

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, par défaut @babel/runtime.

Contrôle quel package de helpers sera utilisé par @babel/plugin-transform-runtime pour injecter les imports, avec la priorité suivante :

• L'option moduleName si spécifiée

• Le module de helpers suggéré par tout plugin babel-plugin-polyfill-*

  • babel-plugin-polyfill-corejs3 suggère @babel/runtime-corejs3
  • babel-plugin-polyfill-corejs2 suggère @babel/runtime-corejs2

• Retour à @babel/runtime

Notez que spécifier l'option corejs activera en interne le plugin babel-plugin-polyfill-corejs* correspondant, influençant ainsi le nom final du module.

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.

attention

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

attention

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

Par défaut, transform-runtime suppose que @babel/runtime@7.0.0 est installé. Si vous avez des versions ultérieures de @babel/runtime (ou leurs équivalents corejs comme @babel/runtime-corejs3) installées ou listées comme dépendances, transform-runtime peut utiliser des fonctionnalités plus avancées.

Par exemple, si vous dépendez de @babel/runtime@^7.24.0, vous pouvez transpiler votre code avec :

babel.config.json

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

ce qui réduit la taille du bundle.

Détails techniques

Le plugin transformateur transform-runtime effectue trois actions :

• Importe automatiquement @babel/runtime/regenerator lors de l'utilisation de générateurs/fonctions asynchrones (configurable via l'option regenerator).
• Peut utiliser core-js pour les fonctions utilitaires si nécessaire au lieu de supposer son polyfill par l'utilisateur (configurable via l'option corejs).
• Supprime automatiquement les fonctions utilitaires inline de Babel et utilise à la place le module @babel/runtime/helpers (configurable via l'option helpers).

Qu'est-ce que cela signifie concrètement ? En substance, vous pouvez utiliser des fonctionnalités natives comme Promise, Set, Symbol, etc., ainsi que toutes les fonctionnalités Babel nécessitant un polyfill, sans pollution globale de l'environnement - particulièrement adapté pour les bibliothèques.

Assurez-vous d'inclure @babel/runtime comme dépendance.

Alias pour le régénérateur

Lorsque vous utilisez une fonction génératrice ou asynchrone :

JavaScript

function* foo() {}

le code généré est :

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

Cette approche n'est pas idéale car elle dépend du runtime regenerator inclus, qui pollue la portée globale.

Avec le transformateur runtime, le code devient :

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

Ceci permet d'utiliser le runtime regenerator sans polluer votre environnement.

Alias pour core-js

Pour utiliser les nouvelles fonctionnalités natives comme Map, Set, Promise, l'approche classique nécessite un polyfill global polluant.

L'option corejs résout ce problème. Le plugin transforme :

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

Permettant ainsi d'utiliser ces fonctionnalités natives sans se préoccuper de leur provenance.

NOTE : Les méthodes d'instance comme "foobar".includes("foo") ne fonctionnent qu'avec corejs: 3.

Alias pour les fonctions utilitaires

Habituellement, Babel place les fonctions utilitaires en haut des fichiers pour éviter la duplication de code. Ces utilitaires peuvent parfois devenir volumineux et entraîner des duplications inutiles entre fichiers. Le transformateur runtime remplace tous les appels d'utilitaires par des références à un module.

Ainsi, le code suivant :

JavaScript

class Person {}

génère normalement :

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

tandis qu'avec runtime, il devient :

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

Options supprimées

Les options suivantes ont été supprimées dans Babel 7.0.0 :

• useBuiltIns

• polyfill