TypeScript : installation et premier projet

TypeScript est JavaScript auquel on ajoute des types : le compilateur vérifie le code avant son exécution et signale les erreurs (propriété inexistante, argument du mauvais type, valeur possiblement absente). Le résultat final reste du JavaScript. Les exemples utilisent des noms génériques.

Ce que TypeScript apporte (et n’apporte pas)

Apporte	N’apporte pas
Détection d’erreurs à l’écriture	Validation des données à l’exécution (les types disparaissent à la compilation)
Complétion et refactorisation fiables dans l’éditeur	Performances supplémentaires
Contrats explicites entre fonctions et modules	Sécurité face aux données externes (réponses d’API, entrées utilisateur)

Les données qui viennent de l’extérieur (JSON reçu, formulaires, base de données) doivent être validées à l’exécution (voir Projets Node.js et web).

Prérequis

Node.js récent (voir Node.js : installation).

node --version
npm --version

Créer un projet

mkdir monprojet && cd monprojet
npm init -y
npm install -D typescript @types/node
npx tsc --version
npx tsc --init                  # génère tsconfig.json

@types/node fournit les types de l’API de Node.js (fs, process, Buffer…). Dans package.json, activer les modules ES : "type": "module".

`tsconfig.json` de départ

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src",
    "sourceMap": true
  },
  "include": ["src"]
}

Option	Rôle
`strict`	Active le groupe de vérifications strictes : à activer dès le début
`noUncheckedIndexedAccess`	`tableau[i]` vaut `T \| undefined` : oblige à tester
`module` / `moduleResolution` : `NodeNext`	Résolution des modules comme Node.js
`verbatimModuleSyntax`	Impose `import type` pour les imports de types
`skipLibCheck`	Ne vérifie pas les fichiers de déclaration des bibliothèques (gain de temps)
`outDir`, `rootDir`	Dossiers de sortie et de sources

Voir Modules et tsconfig pour le détail.

Premier fichier

src/index.ts :

interface Client {
  id: number;
  nom: string;
  email?: string;
}

function afficher(client: Client): string {
  return `${client.id} : ${client.nom} (${client.email ?? 'sans e-mail'})`;
}

const alice: Client = { id: 1, nom: 'Alice' };
console.log(afficher(alice));
console.log(afficher({ id: 2 })); // erreur : la propriété « nom » est manquante

npx tsc --noEmit

src/index.ts(13,23): error TS2345: Argument of type '{ id: number; }' is not assignable to parameter of type 'Client'.
  Property 'nom' is missing in type '{ id: number; }' but required in type 'Client'.

Compiler et exécuter

Méthode	Commande	Usage
Compilation	`npx tsc` puis `node dist/index.js`	Production
Vérification seule	`npx tsc --noEmit`	CI, hook de commit
Surveillance	`npx tsc --watch --noEmit`	Développement
Exécution directe par Node.js	`node src/index.ts`	Node.js récent (types effacés, sans vérification)
Exécution avec `tsx`	`npx tsx src/index.ts`	Développement, scripts
Rechargement	`npx tsx watch src/index.ts`	Développement

Exécuter directement avec Node.js

Les versions récentes de Node.js exécutent les fichiers TypeScript en supprimant les types (sans compiler) :

node src/index.ts

Limites : les types ne sont pas vérifiés (lancer tsc --noEmit à part), seules les syntaxes qui s’effacent sont prises en charge (pas d’enum, de namespace, ni de propriétés de paramètre dans les constructeurs, sauf option dédiée), et les imports relatifs doivent porter l’extension .ts. Avec erasableSyntaxOnly dans tsconfig.json, TypeScript signale ces syntaxes. Consulter la documentation de la version de Node.js utilisée.

Avec `tsx`

npm install -D tsx
npx tsx src/index.ts

tsx exécute du TypeScript avec une configuration minimale (via esbuild) : pratique pour les scripts et le développement, sans vérification de types.

Scripts `package.json`

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "typecheck": "tsc --noEmit",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

La vérification des types (typecheck) est une étape distincte de l’exécution : l’ajouter à l’intégration continue et aux hooks (voir ESLint : intégration continue et performance).

Éditeur

VS Code comprend TypeScript nativement (complétion, erreurs en direct, renommage). Pour utiliser la version de TypeScript du projet : commande « TypeScript : Sélectionner la version de TypeScript » > « Utiliser la version de l’espace de travail ».

Avec un framework

Astro, Vite, Next.js et Express acceptent TypeScript presque sans configuration (voir Astro : installation et structure, React : installation, Next.js : installation). Dans ces projets, tsc --noEmit (ou astro check) sert à vérifier les types.

Dépannage

Symptôme	Piste
`tsc: command not found`	`npx tsc`, ou `npm install -D typescript`
`Cannot find name 'process'` / `'console'`	`@types/node` absent, ou `lib` ne contenant pas `dom` pour les API du navigateur
`Cannot find module './x' or its corresponding type declarations`	Extension manquante avec `NodeNext` (`./x.js`) ou chemin faux
`node src/index.ts` : `ERR_UNKNOWN_FILE_EXTENSION`	Version de Node.js sans exécution de TypeScript : `tsx` ou compilation
`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`	`enum`, `namespace` ou propriétés de paramètre : les remplacer
Aucune erreur affichée dans l’éditeur	Version de TypeScript de l’éditeur différente, fichier hors de `include`

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune propre à Ubuntu : TypeScript est un paquet npm, exécuté avec Node.js. Ne pas utiliser le paquet node-typescript d’Ubuntu (souvent ancien) : installer TypeScript dans le projet pour que toute l’équipe ait la même version.

Pour aller plus loin

Documentation : typescriptlang.org
Suite : Types de base