@babel/plugin-transform-runtime

Traduzione Beta Non Ufficiale

Questa pagina è stata tradotta da PageTurner AI (beta). Non ufficialmente approvata dal progetto. Hai trovato un errore? Segnala problema →

Un plugin che abilita il riutilizzo del codice helper iniettato da Babel per ridurre le dimensioni del codice.

nota

I metodi di istanza come "foobar".includes("foo") funzioneranno solo con core-js@3. Se è necessario utilizzare polyfill, è possibile importare direttamente "core-js" o usare l'opzione useBuiltIns di @babel/preset-env.

Installazione

Installa il plugin come dipendenza di sviluppo.

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

e @babel/runtime come dipendenza di produzione (dato che serve per il "runtime").

npm
Yarn
pnpm
Bun

npm install --save @babel/runtime

yarn add @babel/runtime

pnpm add @babel/runtime

bun add @babel/runtime

Il plugin di trasformazione viene tipicamente utilizzato solo in fase di sviluppo, mentre il runtime stesso sarà necessario nel codice distribuito. Consulta gli esempi seguenti per maggiori dettagli.

pericolo

Quando questo plugin è abilitato, l'opzione useBuiltIns in @babel/preset-env non deve essere impostata. Altrimenti, questo plugin potrebbe non riuscire a isolare completamente l'ambiente.

Perché?

Babel utilizza piccoli helper per funzioni comuni come _extend. Per impostazione predefinita, questi vengono aggiunti in ogni file che ne richiede l'uso. Questa duplicazione è talvolta superflua, specialmente quando l'applicazione è distribuita su più file.

È qui che entra in gioco il plugin @babel/plugin-transform-runtime: tutti gli helper faranno riferimento al modulo @babel/runtime per evitare duplicazioni nell'output compilato. Il runtime verrà incluso nella build.

Un altro scopo di questo trasformatore è creare un ambiente sandbox per il tuo codice. Importando direttamente core-js o @babel/polyfill e le funzionalità integrate che fornisce come Promise, Set e Map, queste inquineranno lo scope globale. Sebbene ciò possa essere accettabile per un'app o uno strumento da riga di comando, diventa problematico se il codice è una libreria destinata alla pubblicazione o se non si ha pieno controllo sull'ambiente di esecuzione.

Il trasformatore aliasserà queste funzionalità integrate a core-js, consentendone l'uso senza dover richiedere esplicitamente i polyfill.

Consulta la sezione dettagli tecnici per maggiori informazioni sul funzionamento e sui tipi di trasformazioni applicate.

Utilizzo

Con un file di configurazione (Consigliato)

Senza opzioni:

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

Con le opzioni (e i relativi valori predefiniti):

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

Il plugin presuppone per impostazione predefinita che tutte le API polifillabili siano fornite dall'utente. Altrimenti è necessario specificare l'opzione corejs.

Tramite CLI

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

Tramite Node API

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

Opzioni

`absoluteRuntime`

boolean o string, predefinito false.

Consente di eseguire transform-runtime su un intero progetto. Per impostazione predefinita, transform-runtime importa direttamente da @babel/runtime/foo, ma ciò funziona solo se @babel/runtime si trova nei node_modules del file in compilazione. Ciò può causare problemi con node_modules annidati, moduli collegati via npm o CLI esterne al progetto. Per evitare problemi di risoluzione del percorso del modulo runtime, questa opzione consente di risolvere il percorso una sola volta e inserire percorsi assoluti nel codice generato.

L'uso di percorsi assoluti non è desiderabile quando i file vengono compilati per un uso successivo, ma risulta utile quando il file viene compilato e consumato immediatamente.

consiglio

Maggiori informazioni sulla configurazione delle opzioni del plugin sono disponibili qui

`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`

attenzione

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.

attenzione

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, predefinito a @babel/runtime.

Questa opzione controlla quale pacchetto di helper @babel/plugin-transform-runtime utilizzerà durante l'iniezione degli import. Segue questa priorità:

Opzione moduleName, se specificata
Modulo helper suggerito da qualsiasi plugin babel-plugin-polyfill-*
- babel-plugin-polyfill-corejs3 suggerisce @babel/runtime-corejs3
- babel-plugin-polyfill-corejs2 suggerisce @babel/runtime-corejs2
Fallback su @babel/runtime

Nota che specificare l'opzione corejs abiliterà internamente il corrispondente plugin babel-plugin-polyfill-corejs*, influenzando così il nome del modulo finale.

`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.

attenzione

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

attenzione

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`

Per impostazione predefinita, transform-runtime assume che sia installato @babel/runtime@7.0.0. Se disponi di versioni successive di @babel/runtime (o delle loro controparti corejs come @babel/runtime-corejs3) installate o elencate come dipendenza, transform-runtime può utilizzare funzionalità più avanzate.

Ad esempio, se dipendi da @babel/runtime@^7.24.0 puoi transpilare il tuo codice con:

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

il che si traduce in dimensioni del bundle più contenute.

Dettagli tecnici

Il plugin trasformatore transform-runtime esegue tre operazioni:

Richiede automaticamente @babel/runtime/regenerator quando si utilizzano generatori/funzioni asincrone (attivabile/disattivabile con l'opzione regenerator).
Può utilizzare core-js per gli helper se necessario, invece di presupporre che verrà fornito un polyfill dall'utente (attivabile/disattivabile con l'opzione corejs)
Rimuove automaticamente gli helper Babel inline e utilizza invece il modulo @babel/runtime/helpers (attivabile/disattivabile con l'opzione helpers).

Cosa significa effettivamente? Fondamentalmente, puoi utilizzare built-in come Promise, Set, Symbol, ecc., nonché tutte le funzionalità Babel che richiedono un polyfill in modo trasparente, senza inquinamento globale, rendendolo estremamente adatto per le librerie.

Assicurati di includere @babel/runtime come dipendenza.

Aliasing del rigeneratore

Ogni volta che usi una funzione generatore o una funzione asincrona:

JavaScript
function* foo() {}

viene generato il seguente codice:

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

Questa soluzione non è ideale perché dipende dal runtime rigeneratore incluso, che inquina l'ambito globale.

Con il trasformatore runtime, tuttavia, viene compilato in:

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

Ciò significa che puoi utilizzare il runtime rigeneratore senza inquinare l'ambiente corrente.

Aliasing di `core-js`

A volte potresti voler utilizzare nuovi built-in come Map, Set, Promise, ecc. L'unico modo per utilizzarli è solitamente includere un polyfill che inquina globalmente.

Questo avviene con l'opzione corejs.

Il plugin trasforma il seguente codice:

JavaScript
var sym = Symbol();

var promise = Promise.resolve();

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

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

nel seguente:

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

Ciò significa che puoi utilizzare in modo trasparente questi built-in e metodi nativi senza preoccuparti della loro provenienza.

NOTA: I metodi delle istanze come "foobar".includes("foo") funzioneranno solo utilizzando corejs: 3.

Aliasing degli helper

Normalmente Babel posiziona gli helper all'inizio del file per svolgere attività comuni ed evitare di duplicare il codice nel file corrente. A volte questi helper possono diventare un po' ingombranti e aggiungere una duplicazione non necessaria tra i file. Il trasformatore runtime sostituisce tutte le chiamate agli helper con un modulo.

Ciò significa che il seguente codice:

JavaScript
class Person {}

di solito si trasforma in:

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

tuttavia, il trasformatore runtime lo trasforma in:

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

Opzioni rimosse

Le seguenti opzioni sono state rimosse in Babel 7.0.0:

useBuiltIns
polyfill

Installazione​

Perché?​

Utilizzo​

Con un file di configurazione (Consigliato)​

Tramite CLI​

Tramite Node API​

Opzioni​

absoluteRuntime​

corejs​

helpers​

moduleName​

regenerator​

useESModules​

version​

Dettagli tecnici​

Aliasing del rigeneratore​

Aliasing di core-js​

Aliasing degli helper​

Opzioni rimosse​

Installazione

Perché?

Utilizzo

Con un file di configurazione (Consigliato)

Tramite CLI

Tramite Node API

Opzioni

`absoluteRuntime`

`corejs`

`helpers`

`moduleName`

`regenerator`

`useESModules`

`version`

Dettagli tecnici

Aliasing del rigeneratore

Aliasing di `core-js`

Aliasing degli helper

Opzioni rimosse