Pour ceux qui le ne sauraient pas, le fichier tsconfig.json est un fichier à mettre à la racine de son projet, qui permet de configurer le compilateur TypeScript (tsc). Basiquement, ce fichier permet d'indiquer au compilateur comment nos fichiers .ts doivent être transformés en JavaScript. En clair, il est au cœur de tout projet TypeScript !
Dans cet article FAQ, nous verrons comment créer le fichier tsconfig.json, et comment le personnaliser avec des options clés, telles que "include", "exclude", "outDir", "module", et "target". Car oui : créer un fichier tsconfig.json n'est pas tout, il faut le configurer ensuite ! C'est donc ce que je vous propose de découvrir ici 🙂
Remarque : pour voir des paramétrages concrets de "tsconfig.json", n'hésitez pas à faire un saut dans la rubrique "Projets". Ainsi, vous verrez tout un tas d'exemples pratiques, avec des configurations parfois différentes, selon les usages !
Salut ! Bienvenue sur LeCoinTS, où je partage des tutos TypeScript gratuits et sans pub. Envie de me soutenir dans cette aventure, avec un café ? ☕
Les étapes pour créer un fichier tsconfig.json
Alors, pour créer un fichier tsconfig.json, vous avez 2 moyens de faire :
- soit créer vous même ce fichier tsconfig.json, avec un simple éditeur de texte ou de code
- soit faire un
tsc --initou équivalent au niveau de votre terminal (une commande que je vous détaillerai un peu plus bas, dans ce paragraphe), ce qui génèrera automatiquement un fichier "tsconfig.json" avec des options par défaut, avec tout un tas de commentaires explicatifs
À noter que ce fichier devra être créé à la racine de votre projet, pour rappel, afin qu'il puisse caractériser l'ensemble de votre projet (en indiquant notamment quels sont les répertoires à prendre en compte et ceux à exclure de la compilation TS, par exemple).
Pour que ce soit plus parlant pour vous, voici un exemple de fichier tsconfig.json, que j'ai créé manuellement pour l'un de mes projets :
{
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"outDir": "./dist",
"strict": true,
"esModuleInterop": true,
"moduleResolution": "node",
"noImplicitAny": true
},
"include": ["src"],
"exclude": ["dist", "node_modules"]
}Et voici ce que génère la commande "tsc --init", histoire de comparer les 2 méthodes :
{
"compilerOptions": {
/* Visit https://aka.ms/tsconfig to read more about this file */
/* Projects */
// "incremental": true, /* Save .tsbuildinfo files to allow for incremental compilation of projects. */
// "composite": true, /* Enable constraints that allow a TypeScript project to be used with project references. */
// "tsBuildInfoFile": "./.tsbuildinfo", /* Specify the path to .tsbuildinfo incremental compilation file. */
// "disableSourceOfProjectReferenceRedirect": true, /* Disable preferring source files instead of declaration files when referencing composite projects. */
// "disableSolutionSearching": true, /* Opt a project out of multi-project reference checking when editing. */
// "disableReferencedProjectLoad": true, /* Reduce the number of projects loaded automatically by TypeScript. */
/* Language and Environment */
"target": "es2016", /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
// "lib": [], /* Specify a set of bundled library declaration files that describe the target runtime environment. */
// "jsx": "preserve", /* Specify what JSX code is generated. */
// "libReplacement": true, /* Enable lib replacement. */
// "experimentalDecorators": true, /* Enable experimental support for legacy experimental decorators. */
// "emitDecoratorMetadata": true, /* Emit design-type metadata for decorated declarations in source files. */
// "jsxFactory": "", /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */
// "jsxFragmentFactory": "", /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
// "jsxImportSource": "", /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */
// "reactNamespace": "", /* Specify the object invoked for 'createElement'. This only applies when targeting 'react' JSX emit. */
// "noLib": true, /* Disable including any library files, including the default lib.d.ts. */
// "useDefineForClassFields": true, /* Emit ECMAScript-standard-compliant class fields. */
// "moduleDetection": "auto", /* Control what method is used to detect module-format JS files. */
/* Modules */
"module": "commonjs", /* Specify what module code is generated. */
// "rootDir": "./", /* Specify the root folder within your source files. */
// "moduleResolution": "node10", /* Specify how TypeScript looks up a file from a given module specifier. */
// "baseUrl": "./", /* Specify the base directory to resolve non-relative module names. */
// "paths": {}, /* Specify a set of entries that re-map imports to additional lookup locations. */
// "rootDirs": [], /* Allow multiple folders to be treated as one when resolving modules. */
// "typeRoots": [], /* Specify multiple folders that act like './node_modules/@types'. */
// "types": [], /* Specify type package names to be included without being referenced in a source file. */
// "allowUmdGlobalAccess": true, /* Allow accessing UMD globals from modules. */
// "moduleSuffixes": [], /* List of file name suffixes to search when resolving a module. */
// "allowImportingTsExtensions": true, /* Allow imports to include TypeScript file extensions. Requires '--moduleResolution bundler' and either '--noEmit' or '--emitDeclarationOnly' to be set. */
// "rewriteRelativeImportExtensions": true, /* Rewrite '.ts', '.tsx', '.mts', and '.cts' file extensions in relative import paths to their JavaScript equivalent in output files. */
// "resolvePackageJsonExports": true, /* Use the package.json 'exports' field when resolving package imports. */
// "resolvePackageJsonImports": true, /* Use the package.json 'imports' field when resolving imports. */
// "customConditions": [], /* Conditions to set in addition to the resolver-specific defaults when resolving imports. */
// "noUncheckedSideEffectImports": true, /* Check side effect imports. */
// "resolveJsonModule": true, /* Enable importing .json files. */
// "allowArbitraryExtensions": true, /* Enable importing files with any extension, provided a declaration file is present. */
// "noResolve": true, /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
/* JavaScript Support */
// "allowJs": true, /* Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files. */
// "checkJs": true, /* Enable error reporting in type-checked JavaScript files. */
// "maxNodeModuleJsDepth": 1, /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
/* Emit */
// "declaration": true, /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
// "declarationMap": true, /* Create sourcemaps for d.ts files. */
// "emitDeclarationOnly": true, /* Only output d.ts files and not JavaScript files. */
// "sourceMap": true, /* Create source map files for emitted JavaScript files. */
// "inlineSourceMap": true, /* Include sourcemap files inside the emitted JavaScript. */
// "noEmit": true, /* Disable emitting files from a compilation. */
// "outFile": "./", /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
// "outDir": "./", /* Specify an output folder for all emitted files. */
// "removeComments": true, /* Disable emitting comments. */
// "importHelpers": true, /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
// "downlevelIteration": true, /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
// "sourceRoot": "", /* Specify the root path for debuggers to find the reference source code. */
// "mapRoot": "", /* Specify the location where debugger should locate map files instead of generated locations. */
// "inlineSources": true, /* Include source code in the sourcemaps inside the emitted JavaScript. */
// "emitBOM": true, /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
// "newLine": "crlf", /* Set the newline character for emitting files. */
// "stripInternal": true, /* Disable emitting declarations that have '@internal' in their JSDoc comments. */
// "noEmitHelpers": true, /* Disable generating custom helper functions like '__extends' in compiled output. */
// "noEmitOnError": true, /* Disable emitting files if any type checking errors are reported. */
// "preserveConstEnums": true, /* Disable erasing 'const enum' declarations in generated code. */
// "declarationDir": "./", /* Specify the output directory for generated declaration files. */
/* Interop Constraints */
// "isolatedModules": true, /* Ensure that each file can be safely transpiled without relying on other imports. */
// "verbatimModuleSyntax": true, /* Do not transform or elide any imports or exports not marked as type-only, ensuring they are written in the output file's format based on the 'module' setting. */
// "isolatedDeclarations": true, /* Require sufficient annotation on exports so other tools can trivially generate declaration files. */
// "erasableSyntaxOnly": true, /* Do not allow runtime constructs that are not part of ECMAScript. */
// "allowSyntheticDefaultImports": true, /* Allow 'import x from y' when a module doesn't have a default export. */
"esModuleInterop": true, /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
// "preserveSymlinks": true, /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
"forceConsistentCasingInFileNames": true, /* Ensure that casing is correct in imports. */
/* Type Checking */
"strict": true, /* Enable all strict type-checking options. */
// "noImplicitAny": true, /* Enable error reporting for expressions and declarations with an implied 'any' type. */
// "strictNullChecks": true, /* When type checking, take into account 'null' and 'undefined'. */
// "strictFunctionTypes": true, /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
// "strictBindCallApply": true, /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */
// "strictPropertyInitialization": true, /* Check for class properties that are declared but not set in the constructor. */
// "strictBuiltinIteratorReturn": true, /* Built-in iterators are instantiated with a 'TReturn' type of 'undefined' instead of 'any'. */
// "noImplicitThis": true, /* Enable error reporting when 'this' is given the type 'any'. */
// "useUnknownInCatchVariables": true, /* Default catch clause variables as 'unknown' instead of 'any'. */
// "alwaysStrict": true, /* Ensure 'use strict' is always emitted. */
// "noUnusedLocals": true, /* Enable error reporting when local variables aren't read. */
// "noUnusedParameters": true, /* Raise an error when a function parameter isn't read. */
// "exactOptionalPropertyTypes": true, /* Interpret optional property types as written, rather than adding 'undefined'. */
// "noImplicitReturns": true, /* Enable error reporting for codepaths that do not explicitly return in a function. */
// "noFallthroughCasesInSwitch": true, /* Enable error reporting for fallthrough cases in switch statements. */
// "noUncheckedIndexedAccess": true, /* Add 'undefined' to a type when accessed using an index. */
// "noImplicitOverride": true, /* Ensure overriding members in derived classes are marked with an override modifier. */
// "noPropertyAccessFromIndexSignature": true, /* Enforces using indexed accessors for keys declared using an indexed type. */
// "allowUnusedLabels": true, /* Disable error reporting for unused labels. */
// "allowUnreachableCode": true, /* Disable error reporting for unreachable code. */
/* Completeness */
// "skipDefaultLibCheck": true, /* Skip type checking .d.ts files that are included with TypeScript. */
"skipLibCheck": true /* Skip type checking all .d.ts files. */
}
}Comme vous pouvez le remarquer, faire un "tsc --init" a des avantages et des inconvénients. Des avantages car on a la liste de toutes les options de base du compilateur, avec un texte explicatif à côté ; et des inconvénients, car on a un fichier qui manque de clarté, du fait que tout plein d'options inutiles sont présentes dessus ! Du coup, à vous de voir si vous préférez avoir toutes les options décrites pour en faire le tri ensuite, comme c'est le cas ici, ou simplement écrire vous-même le fichier tsconfig.json, avec seulement les options qui comptent pour vous dedans !
Remarque : pour créer un fichier package.json avec la commande tsc --init, il y a là deux façon de faire (selon si vous avez installé le package typescript de manière globale, ou localement dans votre projet). Alors :
- si vous avez installé le package "typescript" de façon globale sur votre ordi, en ayant tapé la commande npm install -g typescript dans votre terminal, alors il vous suffira de taper la commande tsc --init à la racine de votre projet, pour générer un fichier package.json automatiquement, avec les paramètres par défaut
- si vous avez installé le package "typescript" de façon locale dans votre projet, en ayant tapé la commande npm install -D typescript dans votre terminal, alors il vous suffira de taper la commande ./node_modules/.bin/tsc --init à la racine de votre projet (ou la commande npx tsc --init, si elle fonctionne !)
Configurer les répertoires de son projet, avec "include", "exclude", et "outDir"
Dans les projets TypeScript simples, on a souvent l'habitude d'organiser les répertoires de son projet ainsi :
- on mettra tous les fichiers sources (
.ts) dans un répertoire nommé src ("src" voulant dire "source") - on demandera au compilateur que tous les fichiers compilés (
.js) soit mis dans un répertoire nommé dist ("dist" voulant dire "distribution")
Ça, c'est la base (bien sûr, cela peut grandement varier, selon la richesse de votre projet).
Du coup, il faut donc indiquer au compilateur qu'il doit se cantonner à l'analyse des fichiers contenus dans le répertoire "src", et stocker tous les fichiers générés (compilés) dans le répertoire "dist". Qui plus est, par sécurité, on a tendance à préciser au compilateur tsc qu'il ne doit en aucun cas analyser le répertoire node_modules, car celui-ci contient des packages "externes" au projet (d'autant plus qu'il y a parfois/souvent des fichiers sources ".ts" dedans !) ; et ce, bien que le répertoire "node_module" ne se situe jamais dans le répertoire "src" et que donc, en toute logique, il ne devrait jamais être parcouru par le compilateur. C'est en fait une sorte de "double sécurité", pour dire au compilateur de ne jamais pénétrer le répertoire "node_modules".
Eh bien tout cela se fait simplement, en mettant par exemple les lignes suivantes dans le fichier tsconfig.json (c'est d'ailleurs ce que je vous avais montré tout en haut, dans le tout premier exemple de fichier "tsconfig.json") :
"compilerOptions": {
"outDir": "./dist"
},
"include": ["src/**/*"],
"exclude": ["node_modules"]Si je résume : on a donc "outDir": "./dist" pour demander au compilateur tsc de loger tous les fichiers qu'il va générer dans un répertoire nommé dist. Et les include et exclude sont là pour dire au compilateur tsc quels répertoires/fichiers il doit analyser puis compiler, et ce qu'il doit exclure. Ainsi, tout est clair, et bien définit à l'avance ; du coup, pas de mauvaise surprise, car le compilateur saura quoi prendre en considération, et où envoyer ses fichiers compilés.
Point technique : vous noterez que je n'ai pas écrit "include" : ["src"] (comme dans le tout premier exemple, tout en haut), mais bien "include": ["src/**/*"]. Tout d'abord, il faut savoir que ces 2 écritures sont correctes, mais n'ont pas la même portée (la 1ère inclus seulement les fichiers présents dans src, et la 2ème inclus ces fichiers là, ainsi que tous les autres présents dans les sous-répertoires de src). En effet, vous remarquerez la présence d'astérisques ici (aussi nommé jokers, ou wildcards en anglais), qui permettent en fait de soumettre un motif (pattern) de sélection au compilateur, afin que non seulement le compilateur prenne en charge les fichiers présent dans le répertoire src, mais également tous les sous-répertoires (quelque soit la profondeur) et fichiers contenus dans ces sous-répertoires, pour la compilation. Plus précisément :
- le / sépare les niveaux dans le chemin
- puis ** signifie "tous les sous-dossiers, peu importe la profondeur"
- et le * final signifie "n’importe quel nom de fichier ou dossier" à un niveau donné
Donc, en résumé : src/**/* inclut tous les fichiers et sous-dossiers présents dans src, et ce, de manière récursive. Du coup, par exemple, les fichiers suivants seraient inclus : src/index.ts, src/utils/decode.ts, src/deep/nested/fichier.ts, … (exemples fictifs, pour que vous compreniez bien). À l'inverse, si vous aviez seulement eu des fichiers .ts stockés dans src, sans sous-répertoire aucun, alors ["src"] aurait suffit dans ce cas là.
Vous aimez cet article ? LeCoinTS reste gratuit et sans pub grâce à vos dons.
Motivez-moi à en faire plus ! ☕
Configurer les propriétés "target" et "module", pour la compilation
Quand vous configurez un fichier tsconfig.json, vous avez deux autres options essentielles ("target" et "module"), qui définissent comment votre code TypeScript sera transformé en JavaScript. Mais ces options ne sont pas forcément faciles à appréhender au début, car il faut avoir un minimum de connaissance, au sujet des différentes version et évolutions de TypeScript à travers le temps, sans quoi les choix "es5", "es6", "esnext", ou "commonjs" ne vous parleront certainement pas ! Du coup, voyons tout ça en détail (tout en restant simple), car c'est vraiment important.
Qu'est-ce que "target", et que mettre à ce niveau ?
L’option "target" permet d'indiquer au compilateur TypeScript (tsc) quelle version de JavaScript il devra produire. Et on est obligé de s'y intéresser, car tous les navigateurs internet ne sont pas forcément compatibles avec telle ou telle version de Javascript (sans quoi votre programme pourrait très bien fonctionner de votre côté, mais planter lorsque vos utilisateurs l'utiliseront !). Bien sûr, au final, tout est question de choix, selon le niveau de compatibilité souhaité.
Pour être plus précis, d'un point de vue plus technique, il faut savoir que JavaScript a évolué selon des normes, appelées ECMAScript (abrégées ES) ; et que chacune de ces normes a ajouté de nouvelles fonctionnalités à javascript. Or, comme évoqué précédemment, certains navigateurs web sont plus ou moins compatibles, selon la norme adoptée. Du coup, il faut bien réfléchir au choix de norme qu'on fait au niveau du fichier "tsconfig.json".
Parmi les normes, que l'on peut choisir avec target, on retrouve couramment :
- "es5", qui est une version assez ancienne de Javascript (norme de 2009), actuellement compatible avec presque tous les navigateurs (y compris les vieux, comme Internet Explorer !). Ce choix est très utile si vous cherchez à avoir un maximum de compatibilité, notamment avec les anciens environnements.
- "es6", aussi appelée ES2015, qui est une version plus moderne de JavaScript (norme de 2015), avec des fonctionnalités telles que
let,const, ou les fonctions fléchées (du style() => { }). Au niveau compatibilité, ES6 est pris en charge par "tous" les navigateurs récents (tels que Chrome et Firefox, par exemple), et Node.js depuis de la version 8. En fait, ES6 est très bon choix pour la plupart des projets modernes, si l'on a que faire des "vieux navigateurs web" ! - "esnext", qui est une version "future" de JavaScript, incluant des fonctionnalités expérimentales qui ne sont pas encore standardisées. Mon avis : à n'utiliser que si vous travaillez sur des projets "de pointe", car tous les environnements ne les supportent pas encore.
Conseil pour débutants : choisissez "es6" pour être tranquille, sauf si votre projet doit fonctionner sur de très vieux navigateurs 🙂
Qu'est-ce que "module", et que mettre à ce niveau ?
L’option "module" définit comment les modules doivent être gérés par TypeScript, ou plus concrètement, comment vos fichiers sont liés entre eux (via require ou import/export, par exemple). Comme vous l'aurez compris, cela dépend donc de l’environnement où votre code devra s’exécuter (Node.js, navigateurs, ou autre). Au niveau des choix possibles pour définir la propriété target, voici ce qu'on retrouve le plus couramment :
- "commonjs", le système de modules standard pour Node.js. Dans ce cas, le code compilé contiendra des "require" (par exemple :
const module = require("./module")). Mon avis : choisissez "commonjs" si vous développez une application NodeJS sans "outils" récents. - "es6" (ou "esmodule"), un système moderne pour les navigateurs web et NodeJS version 13.2+ (en sachant que là on est au moins à la version 22 de NodeJS !). Dans ce cas, le code compilé contiendra des "imports" (par exemple :
import module from "./module"). Mon avis : es6 est idéal pour les projets web modernes, ou des frameworks comme React/Vite. - "esnext", similaire à "es6", mais incluant des fonctionnalités de modules expérimentaux. Mon avis : réservez-le aux projets avant-gardistes, et laissez cela de côté, si vous débutez en JS/TS !
Conseil pour débutants : choisissez également "es6" ici pour être tranquille, sauf si votre projet nécessite des require plutôt que des import/export.
Du reste, voici un exemple de fichier tsconfig.json avec "target" et "module" configurés, pour bien situer les choses :
{
"compilerOptions": {
"target": "es6", // Pour que du JavaScript moderne soit généré
"module": "commonjs" // Pour des require dans NodeJS, par exemple
}
}Mais si vous travaillez sur une appli web, choisissez plutôt du "module": "es6", car c'est bien plus moderne (avec des import/export).
Exemple complet et pratique de fichier "tsconfig.json"
Du coup, si je résume tout ce que nous avons vu précédemment, voici un exemple classique de fichier tsconfig.json :
{
"compilerOptions": {
"target": "es6", // Compile selon norme ES6
"module": "commonjs", // Modules pour Node.js (avec des require)
"outDir": "./dist", // Sortie des fichiers .js dans répertoire "dist"
"rootDir": "./src", // Source des fichiers .ts dans "src"
"strict": true // Vérifications strictes (très utile, pour se mettre des garde-fous)
},
"include": ["src/**/*"], // Compile tous les fichiers présents dans "src", y compris ceux présents dans les éventuels sous-répertoires (prise en compte récursive)
"exclude": ["node_modules"] // Ignore le dossier "node_modules"
}Avec ce fichier là, si vous créez par exemple un fichier src/index.ts contenant un simple console.log("Salut à tous !") dedans, et que vous exécutez tsc pour compiler le tout, alors vous obtiendrez un fichier javascript dans le répertoire "dist" (dist/index.js). Voici ce que ça donne, en image :
Et si vous faites un code plus complexe, le résultat sera conforme à la norme ES6 (puisque demandé dans "target"), tout en utilisant des require pour les modules (vu qu'on a pris l'option commonjs dans "module").
Voilà ! Tout doit être plus clair à présent ! Enfin… je l'espère 😉
Remarque technique : si vous créez un projet avec juste un fichier tsconfig.json et un fichier src/index.ts dedans, il se peut que le compilateur tsc génère un fichier dist/index.js vide. Si cela arrive, ce peut être dû à un problème de cache ou autre au niveau de tsc ; dans ce cas, faites un tsc --listFiles pour forcer tsc à scanner explicitement tous les fichiers inclus dans tsconfig.json, ce qui va réinitialiser son état interne, en quelque sorte, débloquant ainsi la situation ! Cela étant dit, après, dans un projet plus fourni, il est rare qu'il y ait ce genre de problème !
Pour aller plus loin
Si vous souhaitez aller plus loin, et par exemple comprendre l'utilité du "strict": true que j'ai mis juste au dessus, je vous invite à lire les pièges 4 et 5 de cet article, qui vous montrent ce qui pourrait se passer sans cela ! Ça l'illustre bien, vous verrez 🙂
Sinon, vous pouvez toujours consulter la doc officielle TypeScript concernant "tsconfig.json", pour découvrir toutes les autres options possibles, pour le compilateur "tsc".
Du reste, je vous ai fait un guide complet des normes ECMAScript, de ES5 à ESNext, afin que vous puissiez encore mieux appréhender JavaScript et TypeScript, et tous leurs secrets ! Et si tout mon travail vous plaît, n'hésitez pas à me le faire savoir, en m'offrant un café ! (cf. bouton jaune ci-dessous)
Merci beaucoup,
Jérôme.
Merci d’avoir lu cet article ! LeCoinTS reste gratuit et sans pub grâce à vous.
Un petit don pour soutenir le site ? ☕
JEROME
Passionné par tout ce qui touche à la programmation informatique en TypeScript, sans toutefois en être expert, j'ai à coeur de vous partager ici, peu à peu, tout ce que j'ai appris, découvert, réalisé, et testé jusqu'à présent ! En espérant que tout cela puisse vous servir, ainsi qu'au plus grand nombre de francophones possible !
(*) Mis à jour le 20/04/2025
