Aller au contenu principal

@babel/polyfill

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 →

danger

🚨 Depuis Babel 7.4.0, ce paquet est obsolète. Préférez l'import direct de core-js/stable pour les polyfills de fonctionnalités ECMAScript :

JavaScript
import "core-js/stable";

Si vous compilez des générateurs ou fonctions asynchrones vers ES5 avec une version de @babel/core ou @babel/plugin-transform-regenerator antérieure à 7.18.0, vous devez aussi charger le paquet regenerator runtime. Il est chargé automatiquement avec @babel/preset-env via l'option useBuiltIns: "usage" ou @babel/plugin-transform-runtime.

Babel intègre un polyfill comprenant un regenerator runtime personnalisé et core-js.

Il émule un environnement ES2015+ complet (sans les propositions < Stage 4) et est conçu pour des applications plutôt que des bibliothèques/outils. (ce polyfill est chargé automatiquement avec babel-node).

Vous pouvez ainsi utiliser les nouvelles fonctionnalités comme Promise ou WeakMap, les méthodes statiques comme Array.from ou Object.assign, les méthodes d'instance comme Array.prototype.includes, et les fonctions génératrices (si vous utilisez le plugin regenerator). Le polyfill modifie le scope global et les prototypes natifs comme String pour y parvenir.

Installation​

npm install --save @babel/polyfill
info

Comme il s'agit d'un polyfill (exécuté avant votre code source), il doit être déclaré comme dependency, pas comme devDependency.

Taille​

Ce polyfill est pratique mais doit être utilisé avec @babel/preset-env et l'option useBuiltIns pour éviter d'inclure l'intégralité du polyfill inutilement. Sinon, privilégiez l'import manuel des polyfills spécifiques.

Propositions TC39​

Pour utiliser des propositions non finalisées (stade inférieur à 4), @babel/polyfill ne les importe pas automatiquement. Importez-les individuellement depuis un autre polyfill comme core-js. Cette fonctionnalité pourrait être ajoutée ultérieurement dans @babel/polyfill.

Utilisation avec Node / Browserify / Webpack​

Pour inclure le polyfill, requirez-le en tête du point d'entrée de votre application.

Assurez-vous qu'il est appelé avant tout autre code ou require !

JavaScript
require("@babel/polyfill");

Si votre point d'entrée utilise la syntaxe import d'ES6, importez plutôt le polyfill en tête du point d'entrée pour garantir son chargement initial :

JavaScript
import "@babel/polyfill";

Avec webpack, plusieurs méthodes existent pour inclure les polyfills :

  • Avec @babel/preset-env :

    • Si .babelrc spécifie useBuiltIns: 'usage' : n'incluez PAS @babel/polyfill dans webpack.config.js ni dans le code source. Notez que @babel/polyfill doit néanmoins être installé.

    • Si .babelrc spécifie useBuiltIns: 'entry' : incluez @babel/polyfill en tête du point d'entrée via require ou import comme indiqué précédemment.

    • Si .babelrc ne spécifie pas useBuiltIns ou définit useBuiltIns: false : ajoutez @babel/polyfill directement dans le tableau d'entrée de webpack.config.js.

webpack.config.js
module.exports = {
  entry: ["@babel/polyfill", "./app/js"],
};
  • Si @babel/preset-env n'est pas utilisé, ajoutez @babel/polyfill au tableau d'entrée Webpack comme discuté précédemment. Il reste possible de l'ajouter en haut du point d'entrée de l'application via import ou require, mais cette approche est déconseillée.
attention

Nous ne recommandons pas d'importer l'intégralité du polyfill directement : privilégiez soit les options useBuiltIns, soit l'import manuel des polyfills spécifiquement nécessaires (depuis ce paquet ou une autre source).

Utilisation dans le navigateur​

Disponible dans le fichier dist/polyfill.js des versions npm de @babel/polyfill. Doit être inclus avant tout votre code Babel compilé. Vous pouvez soit :

  1. Le préfixer à votre code compilé
  2. L'inclure via une balise <script> placée avant votre code

REMARQUE : Ne le require pas via browserify ou outils similaires, utilisez @babel/polyfill.

Détails​

astuce

Pour une solution sans modification des portées globales (adaptée aux outils/bibliothèques), utilisez le plugin transform-runtime. Notez que cette approche empêche l'utilisation des méthodes d'instance comme Array.prototype.includes.

Remarque : Selon les méthodes ES2015 utilisées, @babel/polyfill ou le plugin runtime peuvent être superflus. Privilégiez soit le chargement ciblé des polyfills spécifiques (ex: Object.assign), soit la documentation des polyfills requis par l'environnement d'exécution.