Aller au contenu principal

Guide d'utilisation

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 →

La chaîne d'outils Babel propose plusieurs outils pour faciliter son utilisation, que vous soyez un « utilisateur final » ou que vous développiez une intégration de Babel lui-même. Ceci est une introduction rapide à ces outils, et vous pourrez en apprendre davantage dans la section « Utilisation » de la documentation.

Si vous utilisez un framework, la configuration de Babel peut différer ou être déjà prise en charge. Consultez plutôt notre guide de configuration interactive.

Vue d'ensemble​

Ce guide vous montrera comment compiler votre code d'application JavaScript utilisant la syntaxe ES2015+ en un code fonctionnel dans les navigateurs actuels. Cela impliquera à la fois la transformation de la nouvelle syntaxe et le polyfill des fonctionnalités manquantes.

Le processus complet pour mettre cela en place implique :

  1. Exécutez ces commandes pour installer les paquets :

    npm install --save-dev @babel/core @babel/cli @babel/preset-env

  2. Créez un fichier de configuration nommé babel.config.json (nécessite v7.8.0 ou supérieur) à la racine de votre projet avec ce contenu :

    babel.config.json
    {
      "presets": [
        [
          "@babel/preset-env",
          {
            "targets": {
              "edge": "17",
              "firefox": "60",
              "chrome": "67",
              "safari": "11.1"
            },
            "useBuiltIns": "usage",
            "corejs": "3.6.5"
          }
        ]
      ]
    }

    La liste des navigateurs ci-dessus n'est qu'un exemple arbitraire. Vous devrez l'adapter aux navigateurs que vous souhaitez prendre en charge. Consultez ici pour plus d'options de @babel/preset-env.

Ou babel.config.js si vous utilisez une version antérieure de Babel

babel.config.js
const presets = [
  [
    "@babel/preset-env",
    {
      targets: {
        edge: "17",
        firefox: "60",
        chrome: "67",
        safari: "11.1",
      },
      useBuiltIns: "usage",
      corejs: "3.6.4",
    },
  ],
];

module.exports = { presets };

  1. Exécutez cette commande pour compiler tout votre code du répertoire src vers lib :

    Shell
    ./node_modules/.bin/babel src --out-dir lib

    Vous pouvez utiliser le lanceur de paquets npm fourni avec npm@5.2.0 pour raccourcir cette commande en remplaçant ./node_modules/.bin/babel par npx babel

Poursuivez pour une explication étape par étape de son fonctionnement et une présentation de chacun des outils utilisés.

Utilisation de base avec l'interface CLI​

Tous les modules Babel dont vous aurez besoin sont publiés en tant que paquets npm distincts sous la portée @babel (depuis la version 7). Cette conception modulaire permet d'avoir divers outils, chacun conçu pour un cas d'utilisation spécifique. Ici, nous examinerons @babel/core et @babel/cli.

Bibliothèque principale​

La fonctionnalité principale de Babel réside dans le module @babel/core. Après l'avoir installé :

npm install --save-dev @babel/core

vous pouvez le require directement dans votre programme JavaScript et l'utiliser comme ceci :

JavaScript
const babel = require("@babel/core");

babel.transformSync("code", optionsObject);

En tant qu'utilisateur final, vous voudrez probablement installer d'autres outils qui servent d'interface à @babel/core et s'intègrent bien à votre processus de développement. Malgré cela, vous pourriez consulter sa page de documentation pour découvrir les options, dont la plupart peuvent également être définies depuis les autres outils.

Outil CLI​

@babel/cli est un outil qui vous permet d'utiliser Babel depuis le terminal. Voici la commande d'installation et un exemple d'utilisation de base :

npm install --save-dev @babel/core @babel/cli

./node_modules/.bin/babel src --out-dir lib

Cela analysera tous les fichiers JavaScript du répertoire src, appliquera les transformations que nous lui avons indiquées, et écrira chaque fichier dans le répertoire lib. Comme nous ne lui avons encore indiqué aucune transformation, le code en sortie sera identique à l'entrée (la mise en forme exacte du code n'est pas préservée). Nous pouvons spécifier les transformations souhaitées en les passant en tant qu'options.

Nous avons utilisé l'option --out-dir ci-dessus. Vous pouvez consulter les autres options acceptées par l'outil CLI en l'exécutant avec --help. Les plus importantes pour nous actuellement sont --plugins et --presets.

Plugins et presets​

Les transformations s'effectuent via des plugins, de petits programmes JavaScript qui indiquent à Babel comment transformer le code. Vous pouvez même écrire vos propres plugins pour appliquer les transformations souhaitées. Pour convertir la syntaxe ES2015+ en ES5, nous pouvons utiliser des plugins officiels comme @babel/plugin-transform-arrow-functions :

npm install --save-dev @babel/plugin-transform-arrow-functions

./node_modules/.bin/babel src --out-dir lib --plugins=@babel/plugin-transform-arrow-functions

Désormais, toutes les fonctions fléchées de notre code seront transformées en expressions de fonction compatibles ES5 :

JavaScript
const fn = () => 1;

// converted to

var fn = function fn() {
  return 1;
};

C'est un bon début ! Mais notre code contient d'autres fonctionnalités ES2015+ à transformer. Plutôt que d'ajouter les plugins un par un, nous pouvons utiliser un "preset" : un ensemble prédéfini de plugins.

Comme pour les plugins, vous pouvez créer vos propres presets pour partager des combinaisons spécifiques. Pour notre cas d'usage, le preset env est idéal.

npm install --save-dev @babel/preset-env

./node_modules/.bin/babel src --out-dir lib --presets=@babel/env

Sans configuration, ce preset inclut tous les plugins supportant le JavaScript moderne (ES2015, ES2016, etc.). Les presets acceptent également des options. Plutôt que de les passer via le terminal, voyons une autre méthode : les fichiers de configuration.

Configuration​

Il existe plusieurs méthodes pour utiliser des fichiers de configuration selon vos besoins. Consultez notre guide détaillé sur la configuration de Babel pour plus d'informations.

Pour l'instant, créons un fichier babel.config.json (nécessite v7.8.0 ou ultérieur) avec ce contenu :

babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "edge": "17",
          "firefox": "60",
          "chrome": "67",
          "safari": "11.1"
        }
      }
    ]
  ]
}

Le preset env ne chargera désormais que les plugins de transformation pour les fonctionnalités absentes de nos navigateurs cibles. La syntaxe est gérée. Passons aux polyfills.

Polyfill​

🚨 As de Babel 7.4.0, ce package est déprécié au profit de l'import direct de core-js/stable (pour polyfill les fonctionnalités ECMAScript) :

JavaScript
import "core-js/stable";

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

Le module @babel/polyfill inclut core-js et un regenerator runtime personnalisé pour émuler un environnement ES2015+ complet.

Vous pouvez ainsi utiliser de nouveaux éléments natifs comme Promise ou WeakMap, des méthodes statiques (Array.from, Object.assign), des méthodes d'instance (Array.prototype.includes), et des fonctions génératrices (avec le plugin regenerator). Le polyfill modifie le scope global et les prototypes natifs (comme String) pour cela.

Pour les auteurs de bibliothèques/outils, cette approche peut être excessive. Si vous n'avez pas besoin des méthodes d'instance comme Array.prototype.includes, évitez de polluer le scope global en utilisant le plugin transform runtime plutôt que @babel/polyfill.

Pour un contrôle précis, importez directement les polyfills nécessaires depuis core-js.

Comme nous construisons une application, installons simplement @babel/polyfill :

npm install --save @babel/polyfill

Notez l'option --save au lieu de --save-dev car il s'agit d'un polyfill qui doit s'exécuter avant votre code source.

Heureusement, nous utilisons le preset env qui propose une option "useBuiltIns". Lorsqu'elle est définie sur "usage", elle applique l'optimisation mentionnée précédemment en n'incluant que les polyfills strictement nécessaires. Avec cette option, la configuration devient :

babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "edge": "17",
          "firefox": "60",
          "chrome": "67",
          "safari": "11.1"
        },
        "useBuiltIns": "usage"
      }
    ]
  ]
}

Babel va désormais analyser votre code pour identifier les fonctionnalités absentes de vos environnements cibles, et n'inclura que les polyfills requis. Par exemple ce code :

JavaScript
Promise.resolve().finally();

serait transformé ainsi (car Edge 17 ne supporte pas Promise.prototype.finally) :

JavaScript
require("core-js/modules/es.promise.finally");

Promise.resolve().finally();

Si nous n'utilisions pas le preset env avec l'option "useBuiltIns" définie sur "usage" (valeur par défaut "false"), nous aurions dû inclure le polyfill complet une seule fois dans notre point d'entrée avant tout autre code.

Par exemple :

babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "edge": "17",
          "firefox": "60",
          "chrome": "67",
          "safari": "11.1"
        },
        "useBuiltIns": "entry"
      }
    ]
  ]
}

Then import core-js (to polyfill ECMAScript features) first, in our entry file to emulate a full ES2015+ environment since @babel/polyfill has been deprecated:

JavaScript
 import "core-js/stable";

Résumé​

Nous avons utilisé @babel/cli pour exécuter Babel en ligne de commande, @babel/polyfill pour fournir les nouvelles fonctionnalités JavaScript, et le preset env pour n'inclure que les transformations et polyfills correspondant aux fonctionnalités utilisées et absentes de nos navigateurs cibles.

Pour plus d'informations sur la configuration de Babel avec votre système de build, votre IDE et autres outils, consultez notre guide de configuration interactive.