esbuild est un bundler et minifieur JavaScript écrit en Go par Evan Wallace. La version actuelle dans le registre npm est la 0.28.2, publiée le 8 août 2026, sous licence MIT. On le lance rarement directement aujourd'hui, car il se trouve plus souvent à l'intérieur d'autres outils, et Vite version huit l'a fait passer d'une dépendance directe à une dépendance peer optionnelle.
Ce qu'esbuild fait et ne fait pas
La bibliothèque a deux points d'entrée principaux. transform prend une seule chaîne et renvoie du code traité sans toucher au système de fichiers et sans résoudre les imports. build lit des fichiers sur le disque, résout les imports, les assemble en un ou plusieurs fichiers de sortie et écrit le résultat. S'y ajoutent les variantes synchrones transformSync et buildSync, la fonction context pour le travail incrémental, analyzeMetafile pour un rapport sur la taille de la sortie, et initialize plus stop pour contrôler le processus enfant.
Les loaders intégrés couvrent js, jsx, ts, tsx, json, css, local-css, text, base64, dataurl, file, binary, copy et empty. Les formats de sortie sont iife, cjs et esm. Le réglage platform accepte browser, node ou neutral et change en une fois les valeurs par défaut de plusieurs autres options, dont format, mainFields et conditions. C'est la première chose que je vérifie quand la sortie d'un build ne ressemble pas à ce que j'attendais.
La liste de ce qu'esbuild ne fait pas est écrite dans la documentation comme une décision plutôt que comme un backlog. L'auteur exclut du cœur : la prise en charge d'autres langages frontend, c'est-à-dire Elm, Svelte, Vue et Angular ; la vérification des types TypeScript ; une API de manipulation d'AST personnalisée ; le rechargement à chaud des modules ; et la fédération de modules. Il décrit esbuild comme un éditeur de liens (linker) pour le web : un outil qui sait transformer et regrouper JavaScript et CSS, tandis que tout ce qui se passe en amont doit être du code tiers.
Les chiffres d'usage sont trompeurs si on les lit au pied de la lettre. Durant la semaine du 13 au 19 août 2026, le paquet esbuild a enregistré 226,5 millions de téléchargements, Vite 143,0 millions, Rollup 102,6 millions et webpack 46,5 millions. Ce premier nombre témoigne de sa présence dans l'arbre de dépendances de centaines de milliers de projets, pas du nombre de personnes qui ont écrit leur propre script de build avec son API.
Version, licence et contenu du paquet publié
La licence est ici d'une cohérence inhabituelle, et cela mérite d'être dit clairement, car pour beaucoup de projets de cette collection ce n'est pas le cas. Le fichier LICENSE.md du dépôt evanw/esbuild contient le texte MIT avec la mention « Copyright (c) 2020 Evan Wallace ». Le champ license du registre npm pour le paquet esbuild indique MIT. L'archive publiée de la version 0.28.2 contient le même LICENSE.md à côté de README.md, du répertoire bin, du répertoire lib et du script install.js. Trois sources, une seule réponse.
Il y a pourtant une réserve, et elle n'apparaît qu'une fois qu'on déballe ce qui s'exécute réellement. Le paquet esbuild ne contient aucun exécutable. À la place, il déclare vingt-six dépendances optionnelles qui contiennent les binaires par plateforme, de @esbuild/darwin-arm64 à @esbuild/openharmony-arm64 en passant par @esbuild/linux-x64. L'archive @esbuild/darwin-arm64 en version 0.28.2 contient exactement trois éléments : bin/esbuild, package.json et README.md. Il n'y a pas de fichier de licence, et ce README.md fait trois phrases qui renvoient au dépôt, sans texte de licence. Les métadonnées du registre déclarent MIT, donc un scanner de dépendances verra la bonne valeur, mais l'archive qui contient le binaire ne la porte pas. Si tu assembles un fichier de texte de licences pour un produit distribué, le texte MIT doit venir du paquet parent ou du dépôt.
Le mécanisme de livraison a une autre conséquence. Le paquet esbuild exécute un script postinstall composé de node install.js, qui repère le bon binaire parmi les dépendances optionnelles, vérifie que sa version correspond et, si besoin, récupère le paquet manquant avec un appel séparé à npm install. Une installation où les scripts sont ignorés ou les dépendances optionnelles sautées laisse un outil non fonctionnel. La variable d'environnement ESBUILD_BINARY_PATH te permet de pointer vers un binaire manuellement, ce qui sauve les images de conteneur construites sans accès au réseau. Le champ engines exige Node 18 ou plus récent.
Un numéro de version inférieur à 1.0 et une sémantique inversée
Le paquet compte 482 versions publiées depuis novembre 2017 et le numéro majeur est toujours zéro. Ce n'est pas de la négligence. Dans la section sur la maturité pour la production, l'auteur qualifie esbuild de bêta avancée et donne deux raisons : le code splitting est encore primitif, et la communauté est plus petite que celle qui entoure d'autres outils JavaScript.
La conséquence pratique concerne les plages de versions et il est facile de se brûler. Dans esbuild, les versions patch sont destinées aux changements rétrocompatibles et les versions mineures aux changements non rétrocompatibles. C'est l'inverse de la lecture habituelle du versionnement sémantique, où l'incompatibilité est signalée par le numéro majeur. Écrire ^0.28.0 dans package.json donne par hasard le bon comportement, car pour les versions zéro le gestionnaire de paquets réduit de toute façon la plage aux patchs. Mais un ~0.28 interprété de façon lâche, un >=0.28.0 ou une montée manuelle vers la mineure suivante peuvent faire entrer un changement cassant. La documentation recommande de figer la version exacte ou le couple majeur et mineur.
Le deuxième risque est organisationnel. Le projet a un auteur principal, qui déclare sans détour qu'il ne mène pas de développement actif de fonctionnalités pour le moment parce que ses projets actuels n'impliquent plus une grande base de code web. Il s'engage sur la maintenance et des versions périodiques, y compris la prise en charge de la syntaxe JavaScript et TypeScript nouvellement publiée, et compte revenir à un travail plus important. Les versions continuent bien de sortir : 0.27.0 en novembre 2025, 0.28.0 en avril 2026, 0.28.2 en août 2026. Mais le plan est que l'outil atteigne un état en grande partie stable et cesse ensuite d'accumuler des fonctionnalités. Si le critère de sélection de ton organisation est le nombre de mainteneurs actifs, esbuild échoue à ce critère, et il vaut mieux le savoir avant l'adoption qu'après.
Quand utiliser esbuild directement
Le premier cas sensé est de construire une bibliothèque sans framework. Tu as un répertoire src, tu veux livrer de l'ESM et du CommonJS, les déclarations de types sont générées séparément par tsc, et les dépendances doivent rester en dehors du paquet. C'est trente lignes de script et un build qui se mesure en centaines de millisecondes.
import * as esbuild from 'esbuild'
const shared = {
entryPoints: ['src/index.ts'],
bundle: true,
platform: 'neutral',
target: ['es2022', 'node18'],
sourcemap: 'linked',
packages: 'external',
logLevel: 'info'
}
await esbuild.build({
...shared,
format: 'esm',
outfile: 'dist/index.mjs'
})
await esbuild.build({
...shared,
format: 'cjs',
outfile: 'dist/index.cjs'
})Régler packages: 'external' laisse tous les imports de paquets non résolus, donc seul ton propre code se retrouve dans le paquet. Sans cela, bundle: true fera entrer tout l'arbre de dépendances dans la sortie, ce qui, pour une bibliothèque publiée dans un registre, est presque toujours une erreur. L'alternative est de lister des noms dans external, quand certaines dépendances doivent être intégrées et d'autres non.
Le deuxième cas, ce sont les scripts rapides et les transformations ponctuelles. La fonction transform ne touche jamais au disque et convient au traitement de code en mémoire, par exemple à l'intérieur d'un outil qui compile un morceau de TypeScript avant de l'exécuter.
import * as esbuild from 'esbuild'
const source = 'const answer: number = 42\nexport default answer\n'
const result = await esbuild.transform(source, {
loader: 'ts',
format: 'esm',
target: 'node20',
minifyWhitespace: true,
sourcemap: 'inline'
})
console.log(result.code)
console.log(result.warnings.length)Le troisième cas est le packaging de fonctions pour un environnement serveur, où la taille de l'archive et le temps de démarrage à froid comptent. Ici, tu veux platform: 'node', format: 'cjs' ou esm, minify: true, et external listant les modules que le fournisseur fournit déjà dans le runtime.
Le quatrième cas est négatif et mérite sa propre phrase. Si tu travailles dans Bun ou Deno, les deux runtimes ont leurs propres chemins de build intégrés et ajouter esbuild ne fait qu'apporter un autre binaire. Il en va de même pour un projet Vite 8 : puisque l'outil est passé à Rolldown, figer esbuild à la main n'a de sens que si tu l'utilises pour autre chose que construire l'application elle-même.
Limites dures : anciens navigateurs, types et code splitting
Le réglage target accepte des noms d'environnements avec des numéros de version : chrome, deno, edge, firefox, hermes, ie, ios, node, opera, rhino, safari, ainsi que des versions du langage comme es2020. La valeur par défaut est esnext. Voir ie dans cette liste se lit facilement comme une promesse que l'outil ne tient qu'en partie. La documentation dit sans détour qu'esbuild ne peut abaisser la plupart des syntaxes récentes que jusqu'à es6, donc avec une cible es5 il signale simplement une erreur sur la construction non prise en charge. Ajoute à cela l'absence d'injection automatique de polyfills : target concerne la syntaxe, pas les API, et Promise ou Array.prototype.flat doivent être importés par toi-même, par exemple depuis core-js.
En pratique, cela signifie qu'un projet tenu de prendre en charge Internet Explorer ou de très vieux navigateurs mobiles ne se construira pas avec esbuild sans un passage supplémentaire par Babel. Pour la plupart des nouveaux projets, c'est sans importance, mais dans un système d'entreprise maintenu avec une liste de navigateurs pris en charge qui date d'une décennie, c'est un critère éliminatoire.
L'absence de vérification de types fonctionne autrement que ce que suggère l'intuition. esbuild retire les annotations de types et compile fichier par fichier, sans jamais voir tout le programme d'un coup. Un code avec une erreur de type passera dans le build sans avertissement. La vérification devient le travail d'un appel séparé à tsc --noEmit, que je traite plus en profondeur dans l'article sur TypeScript. Cette séparation a un avantage, car le build n'attend pas l'analyse de types, et un inconvénient, car un pipeline d'intégration continue doit penser aux deux étapes. Note que pratiquement tous les bundlers rapides utilisés aujourd'hui adoptent la même approche.
Le code splitting est le point le plus faible et l'auteur le décrit lui-même ainsi. Il ne fonctionne qu'avec le format esm, exige outdir plutôt que outfile, et la documentation consigne un problème connu d'ordre des instructions d'import entre les chunks générés. Sans splitting activé, une expression import() ne crée aucun fichier séparé et devient Promise.resolve().then(() => require()), ce qui conserve la sémantique asynchrone tout en faisant entrer le code dans la même sortie. Pour une application où le découpage au niveau des routes doit raccourcir de façon mesurable le premier chargement, c'est un argument en faveur de Rollup, Rolldown ou webpack.
import * as esbuild from 'esbuild'
// splitting works only with format: 'esm' and requires outdir
await esbuild.build({
entryPoints: ['src/home.ts', 'src/about.ts'],
bundle: true,
splitting: true,
format: 'esm',
outdir: 'dist',
chunkNames: 'chunks/[name]-[hash]',
entryNames: '[dir]/[name]-[hash]',
metafile: true
})Plugins, mode context et metafile
Un plugin est un objet avec un champ name et une fonction setup qui reçoit un objet build. Sur celui-ci tu enregistres onResolve, onLoad, onStart, onEnd et onDispose, et tu as accès à initialOptions, à build.resolve et à une copie complète de la bibliothèque sous build.esbuild. Les filtres dans onResolve et onLoad sont des expressions régulières exécutées côté Go, donc elles doivent utiliser une syntaxe que ce moteur prend en charge, sans lookbehind.
const envPlugin = {
name: 'env',
setup(build) {
build.onResolve({ filter: /^env$/ }, (args) => ({
path: args.path,
namespace: 'env-ns'
}))
build.onLoad({ filter: /.*/, namespace: 'env-ns' }, () => ({
contents: JSON.stringify(process.env),
loader: 'json'
}))
build.onEnd((result) => {
console.log(`errors: ${result.errors.length}`)
})
}
}
await import('esbuild').then((esbuild) =>
esbuild.build({
entryPoints: ['src/app.ts'],
bundle: true,
outfile: 'dist/app.js',
plugins: [envPlugin]
})
)La frontière est ici nette. Un plugin substitue le contenu des fichiers sous forme de chaîne et décide de la manière dont les chemins se résolvent, mais il ne reçoit jamais d'arbre syntaxique et ne peut pas en modifier un. Tout ce qui exige une transformation au niveau de l'AST doit se faire avant que le code n'arrive dans esbuild, ou dans un tout autre outil.
La fonction context renvoie un objet avec les méthodes rebuild, watch, serve, cancel et dispose. Elle conserve un état entre les exécutions, donc les builds suivants sont plus rapides, et serve démarre un simple serveur de fichiers statiques pour le travail local. Ce n'est pas un remplacement d'un serveur de développement avec rechargement à chaud des modules, car esbuild n'en a pas et n'en aura pas.
import * as esbuild from 'esbuild'
const ctx = await esbuild.context({
entryPoints: ['src/app.ts'],
bundle: true,
outdir: 'public',
sourcemap: true
})
await ctx.watch({ delay: 50 })
const { hosts, port } = await ctx.serve({ servedir: 'public', port: 8000 })
console.log(`listening on ${hosts[0]}:${port}`)
process.on('SIGINT', async () => {
await ctx.dispose()
process.exit(0)
})L'option metafile: true ajoute au résultat un objet avec des sections inputs et outputs. Pour chaque entrée, il donne la taille en octets et la liste des imports ; pour chaque sortie, la taille, la contribution en octets de chaque entrée, la liste des exports et le nom du fichier du point d'entrée. analyzeMetafile en tire un rapport texte lisible. C'est le moyen le plus simple de répondre à la question de savoir quelle dépendance explique un saut de taille du bundle, et cela fonctionne sans plugin supplémentaire.
esbuild face aux alternatives
| Caractéristique | esbuild | Rollup | Rolldown | webpack | SWC |
|---|---|---|---|---|---|
| Implémentation | Go | JavaScript avec un cœur natif Rust | Rust | JavaScript | Rust |
| Version actuelle | 0.28.2 | 4.62.5 | 1.2.5 | 5.109.2 | 1.16.1 |
| Licence | MIT | MIT | MIT | MIT | Apache 2.0 |
| Rôle | bundler et minifieur | bundler | bundler | bundler | transpileur et minifieur |
| Vérification des types | aucune | aucune | aucune | aucune | aucune |
| Code splitting | format esm uniquement | complet | complet | complet | sans objet |
| Modèle de plugins | onResolve et onLoad | hooks Rollup | hooks compatibles Rollup | loaders et plugins | plugins WebAssembly |
Le changement le plus intéressant de l'année écoulée concerne Vite. Dans la version 7.3.6, le paquet vite listait esbuild parmi ses dépendances directes à côté de rollup. Dans la version 8.2.2, la dépendance directe est rolldown en version 1.2.x, et esbuild est passé aux dépendances peer avec la plage ^0.27.0 || ^0.28.0 et une entrée optional: true. En pratique, un nouveau projet Vite 8 n'installe pas du tout esbuild, sauf si autre chose dans l'arbre de dépendances en a besoin. La direction est lisible : un seul moteur Rust gère à la fois le mode développement et les builds de production, au lieu de deux outils dont les comportements divergent.
Cela ne veut pas dire qu'esbuild cesse d'avoir du sens. Cela veut dire qu'il cesse d'être la couche par défaut sous un framework et retourne au rôle dans lequel il est le meilleur : un outil autonome et prévisible pour des builds simples. Une répartition du travail similaire apparaît ailleurs dans la chaîne d'outils, où Biome prend en charge le formatage et l'analyse statique, et Turborepo gère le cache des tâches dans un monorepo.
La direction que prend l'écosystème Vite mérite d'être connue. Rolldown est un bundler Rust avec l'interface de plugins de Rollup, conçu pour remplacer l'arrangement où le mode développement passait par esbuild et les builds de production par Rollup. Deux outils différents dans un même pipeline produisaient des sorties différentes, et c'est la vraie raison du changement, plus que la seule vitesse. Avant de l'adopter, vérifie toutefois les limites de la compatibilité avec Rollup, car une interface de plugins compatible ne signifie pas une couverture complète.
Erreurs courantes
Régler target: 'es5' dans l'espoir de prendre en charge de vieux navigateurs. Le build s'arrête avec une erreur à la première construction qu'esbuild ne peut pas abaisser en dessous d'es6. La bonne réaction est soit de relever la version minimale du navigateur, soit d'ajouter un passage séparé par Babel.
Traiter le build comme un contrôle de qualité des types. esbuild émettra un fichier valide à partir d'un code pour lequel tsc signalerait une douzaine d'erreurs. Dans un pipeline d'intégration continue, tsc --noEmit doit être une étape à part, sinon les erreurs de types n'apparaissent qu'à l'exécution.
Activer splitting: true avec le format cjs ou sans outdir. Dans les deux cas, tu obtiens une erreur de configuration plutôt qu'une sortie silencieusement moins bonne, mais le message est souvent pris pour une défaillance de l'outil.
Construire une bibliothèque avec bundle: true et sans packages: 'external' ni liste external. Le paquet publié embarque alors une copie du code de chaque dépendance, avec la taille et les conflits de versions qui en découlent pour les consommateurs.
Installer dans une image de conteneur en sautant les scripts d'installation ou les dépendances optionnelles. Sans postinstall et sans le paquet du binaire, esbuild n'a rien à exécuter. Dans un environnement hors ligne, la bonne correction est de pointer vers le binaire via ESBUILD_BINARY_PATH.
Écrire une plage de versions plus large qu'un patch, par exemple >=0.28.0. Étant donnée la sémantique inversée d'esbuild, la version mineure suivante peut contenir un changement non rétrocompatible et entrera dans le projet sans avertissement.
Ajouter esbuild à côté de Vite 8 par habitude. Cette dépendance n'est plus nécessaire pour construire l'application et ne fait qu'augmenter le nombre de binaires téléchargés à l'installation.
FAQ
esbuild est-il prêt pour la production malgré son numéro de version 0.x ?
L'auteur le qualifie de bêta avancée : stable mais incomplet. Il est utilisé en production depuis des années, entre autres à l'intérieur de Vite jusqu'à la version sept et dans Amazon CDK. Il y a une condition : fige la version exacte ou le couple majeur et mineur, car dans ce projet une montée mineure signifie une possible incompatibilité rétroactive.
esbuild vérifie-t-il les types TypeScript ?
Non, et il ne le fera pas. Il retire les annotations et compile fichier par fichier, sans jamais voir tout le programme. Tu lances la vérification des types séparément via tsc --noEmit, idéalement en parallèle du build, car les deux étapes sont indépendantes l'une de l'autre.
Comment construire une bibliothèque à la fois en ESM et en CommonJS ?
Deux appels à build avec le même ensemble d'options et des valeurs différentes pour format et outfile, avec packages: 'external' pour que les dépendances restent hors de la sortie. Les déclarations de types viennent de tsc --emitDeclarationOnly, car esbuild ne produit pas de fichiers .d.ts.
Pourquoi Vite 8 n'installe-t-il pas esbuild ?
Parce qu'à partir de cette version la dépendance directe est Rolldown, et esbuild apparaît comme dépendance peer optionnelle avec la plage ^0.27.0 || ^0.28.0. Dans Vite 7.3.6, c'était encore une dépendance simple à côté de Rollup.
esbuild gère-t-il Internet Explorer ?
Le nom ie figure dans la liste des cibles acceptées, mais l'abaissement de la syntaxe ne va pas plus loin qu'es6, et les polyfills pour les API manquantes ne sont pas ajoutés automatiquement. De façon réaliste, IE demande un passage supplémentaire par Babel et des polyfills importés à la main.
Que se passe-t-il si j'installe le paquet avec les scripts désactivés ?
Le script postinstall ne repérera ni ne vérifiera le binaire, donc l'appel à esbuild se termine par une erreur. Il y a deux corrections : autoriser le script d'installation pour ce paquet, ou pointer vers un binaire préparé avec ESBUILD_BINARY_PATH.