"lib"

Choisit les types intégrés de l’environnement : la version de JavaScript, les API du navigateur et les nouveautés individuelles du langage.

Sur cette page

Exemple

#
JSON
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2023", "DOM", "DOM.Iterable"]
  }
}

Définition et utilisation

#

L’option lib indique quels ensembles de déclarations de types intégrées le compilateur connaît : les objets JavaScript (Array, Map, Promise) d’une version donnée du langage, les API du navigateur (document, fetch) ou certaines nouveautés. Elle n’ajoute aucun code à votre programme, elle décrit seulement ce qui existe dans l’environnement.

Sans lib, le compilateur choisit un ensemble d’après l’option target et ajoute les types du navigateur. Lorsque vous fournissez vous-même lib, vous remplacez cet ensemble par défaut : dans un projet de navigateur, vous devez donc ajouter DOM et en général DOM.Iterable. Dans un projet Node.js, les types de l’environnement viennent du paquet @types/node, et il vaut mieux omettre DOM.

lib n’ajoute pas de polyfills. Si vous ajoutez ES2023, le compilateur vous laissera utiliser toReversed(), mais dans un navigateur dépourvu de cette méthode, le programme lèvera quand même une erreur. Choisissez des valeurs adaptées à l’environnement dans lequel le code s’exécute réellement.

Syntaxe

#
Syntaxe
"lib": ["ES2022", "DOM", "DOM.Iterable"]

Valeurs les plus courantes

#
  • ES2022, ES2023, …

    Les types du langage d’une version donnée, par exemple Array.prototype.at() en ES2022 et toSorted() en ES2023. Chaque version inclut aussi toutes les précédentes.
  • ESNext

    Les fonctionnalités les plus récentes, y compris celles qui ne font pas encore partie d’une version officielle du langage, par exemple les types de la déclaration using.
  • DOM

    Les API du navigateur : window, document, éléments HTML, événements et fetch.
  • DOM.Iterable

    L’itération sur les collections DOM, par exemple une boucle for...of sur le résultat de querySelectorAll().
  • WebWorker

    Les types de l’environnement d’un Web Worker, utilisés à la place de DOM dans les fichiers de workers.
  • esnext.disposable

    Un exemple de fragment isolé : les types Symbol.dispose et Disposable pour using. De telles valeurs ajoutent une seule nouveauté sans faire monter toute la version.

Plus d’exemples

#
Types hors des bibliothèques choisies
TypeScript
// "lib": ["ES2022"]
const scores = [72, 95, 88]
const reversed = scores.toReversed()
// Erreur : Property 'toReversed' does not exist on type 'number[]'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2023' or later.

const title = document.querySelector('h1')
// Erreur : Cannot find name 'document'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'.
DOM.Iterable manquant
TypeScript
// "lib": ["ES2023", "DOM"]
const items = document.querySelectorAll('li')
for (const item of items) item.classList.add('done')
// Erreur : Type 'NodeListOf<HTMLLIElement>' must have a '[Symbol.iterator]()' method that returns an iterator.

Bonnes pratiques

#
  • Sans raison précise, ne définissez pas lib du tout. L’ensemble par défaut pour le target choisi contient déjà les types du navigateur.
  • Le message « Do you need to change your target library? » signifie que le code utilise une API en dehors des bibliothèques choisies. N’ajoutez la valeur indiquée que si l’environnement la prend vraiment en charge.
  • Vous pouvez activer des nouveautés isolées sans faire monter toute la version, par exemple "esnext.disposable" pour la déclaration using.

Entrées associées

#

Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.