Migrer un projet JS vers TypeScript : guide complet

Introduction

En 2024, plus de 70% des développeurs considèrent TypeScript comme un atout majeur pour la robustesse de leurs projets. Avec la complexité croissante des applications web, la migration de JavaScript vers TypeScript devient essentielle pour garantir la maintenabilité et la stabilité du code. Ce guide complet vous accompagnera pas à pas pour transformer votre code JavaScript en TypeScript de manière méthodique et sûre.

Vous découvrirez pourquoi cette migration est cruciale aujourd'hui, comment installer et configurer TypeScript, convertir progressivement votre code, gérer les types avancés, intégrer les outils de l'écosystème, et éviter les pièges courants. Que vous travailliez sur une petite bibliothèque ou une application d'entreprise, les principes présentés ici s'appliquent à tous les contextes. Suivez ce guide pour améliorer la qualité de vos projets et adopter les meilleures pratiques du développement moderne.

Pourquoi migrer vers TypeScript ?

TypeScript apporte un typage statique qui permet une meilleure vérification des erreurs à la compilation. Cela réduit les bugs dès les premières étapes de développement, bien avant que le code n'atteigne la production. TypeScript est aussi largement adopté par les grandes entreprises et les projets open source majeurs, ce qui en fait une compétence particulièrement recherchée en 2025.

Typage statique et détection précoce des erreurs

Le typage statique réduit les erreurs communes liées aux types indéterminés en JavaScript. En déclarant explicitement les types de vos variables, paramètres de fonctions et valeurs de retour, vous obtenez un retour immédiat de votre éditeur de code. Les erreurs qui auraient auparavant nécessité des heures de débogage en production sont désormais signalées directement dans l'IDE. Cela facilite la maintenance, améliore la qualité du code et accélère considérablement le cycle de développement.

Autocomplétion et productivité accrue

Grâce aux informations de type, les éditeurs comme VS Code proposent une autocomplétion intelligente, une navigation dans le code et un refactoring assisté. Les développeurs passent moins de temps à consulter la documentation et plus de temps à écrire du code fonctionnel. Sur un projet de grande taille, ce gain de productivité se chiffre en heures économisées chaque semaine.

Adoption par les entreprises et l'écosystème

Les grandes entreprises comme Microsoft, Google, Airbnb et Slack utilisent TypeScript pour ses avantages en termes de robustesse et de productivité. La demande pour cette compétence est en constante augmentation sur le marché de l'emploi. De plus, la majorité des frameworks modernes comme Angular, Next.js et Nuxt proposent un support natif de TypeScript, rendant la migration d'autant plus pertinente.

Comparatif JavaScript vs TypeScript

Étape 1 : Installation et configuration

Pour commencer la migration, installez TypeScript globalement sur votre machine. Cette installation vous donne accès au compilateur tsc en ligne de commande. Utilisez la commande suivante :

npm install -g typescript

Ensuite, initialisez un fichier tsconfig.json dans votre projet, qui stockera toute la configuration TypeScript :

tsc --init

Ce fichier permettra de personnaliser les options de compilation pour répondre aux besoins spécifiques de votre projet. Il est essentiel de le configurer correctement dès le départ pour éviter les problèmes plus tard.

Configuration recommandée du tsconfig.json

Voici une configuration de départ adaptée à la plupart des projets en cours de migration. Elle active le mode strict de manière progressive et autorise temporairement les fichiers JavaScript :

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020", "DOM"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": false,
    "allowJs": true,
    "checkJs": false,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

L'option allowJs: true est cruciale : elle permet au compilateur de traiter à la fois les fichiers .js et .ts dans le même projet. Vous pourrez ainsi migrer fichier par fichier sans bloquer le développement en cours. L'option strict: false sera activée progressivement une fois la majorité du code convertie.

Installation des types pour les dépendances

La plupart des bibliothèques populaires disposent de fichiers de définition de types disponibles via le registre @types de DefinitelyTyped. Installez-les en tant que dépendances de développement :

npm install --save-dev @types/node @types/express @types/lodash

Si une bibliothèque ne possède pas de types publiés, vous pouvez créer un fichier de déclaration personnalisé. Créez un fichier declarations.d.ts à la racine de votre projet :

declare module 'ma-bibliotheque-sans-types' {
  export function maFonction(param: string): void;
  export default maFonction;
}

Conseil important : Ne passez jamais directement à strict: true sur un projet existant de grande taille. Activez les options strictes une par une (noImplicitAny, strictNullChecks, strictFunctionTypes) au fur et à mesure que vous corrigez les erreurs. Cette approche graduelle évite de se retrouver submergé par des centaines d'erreurs de compilation dès le premier jour.

Étape 2 : Conversion progressive du code

Pour éviter les interruptions dans le développement, une migration progressive est fortement recommandée. L'objectif est de convertir les fichiers un par un, en commençant par les modules les plus simples et les plus isolés, puis en progressant vers les modules les plus complexes et interconnectés.

Stratégie de conversion fichier par fichier

Renommez progressivement vos fichiers JavaScript en TypeScript, en passant de l'extension .js à .ts. Corrigez les erreurs de typage au fur et à mesure. Voici un ordre de priorité recommandé :

1. Les fichiers utilitaires et les fonctions pures sans dépendances externes.
2. Les modèles de données et les interfaces partagées.
3. Les services et les modules métier.
4. Les contrôleurs, composants ou routes de l'application.
5. Les fichiers de configuration et les points d'entrée.

Cette approche ascendante vous permet de construire une base de types solide que les modules de plus haut niveau pourront utiliser immédiatement.

Utilisation de JSDoc comme étape intermédiaire

Avant de convertir un fichier en .ts, vous pouvez activer l'option checkJs: true dans votre tsconfig et utiliser les commentaires JSDoc pour annoter vos fichiers JavaScript. TypeScript reconnaît ces annotations et peut vérifier les types même dans les fichiers .js :

/**
 * Calcule le total TTC à partir du montant HT.
 * @param {number} montantHT - Le montant hors taxes
 * @param {number} tauxTVA - Le taux de TVA (ex: 0.20 pour 20%)
 * @returns {number} Le montant toutes taxes comprises
 */
function calculerTTC(montantHT, tauxTVA) {
  return montantHT * (1 + tauxTVA);
}

Cette technique est particulièrement utile pour les projets volumineux où la conversion immédiate de tous les fichiers n'est pas réaliste. Elle permet d'obtenir une vérification partielle des types sans modifier la structure du fichier.

Exemple concret de conversion

Prenons un module JavaScript classique et transformons-le en TypeScript. Voici le code original :

// userService.js
function getUser(id) {
  return fetch(`/api/users/${id}`).then(res => res.json());
}

function formatUserName(user) {
  return `${user.firstName} ${user.lastName}`;
}

module.exports = { getUser, formatUserName };

Et voici la version TypeScript équivalente, enrichie avec des interfaces et des types de retour explicites :

// userService.ts
interface User {
  id: number;
  firstName: string;
  lastName: string;
  email: string;
}

async function getUser(id: number): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  const data: User = await response.json();
  return data;
}

function formatUserName(user: User): string {
  return `${user.firstName} ${user.lastName}`;
}

export { getUser, formatUserName };

Remarquez comment l'interface User documente explicitement la structure des données. Tout appel incorrect sera immédiatement signalé par le compilateur.

Étape 3 : Gestion des types avancés

TypeScript exige que chaque variable et fonction ait un type bien défini. Ajoutez des annotations de type pour garantir que votre code reste clair et que les erreurs soient détectées à la compilation. Commençons par les bases avant de passer aux types plus complexes.

Types de base et annotations

let count: number = 5;
let userName: string = "Alice";
let isActive: boolean = true;
let tags: string[] = ["typescript", "migration"];
let config: Record<string, unknown> = { debug: true };

En définissant explicitement les types, vous bénéficierez d'un code plus lisible et moins sujet aux erreurs. TypeScript offre également une inférence de type puissante : lorsque le type est évident d'après la valeur assignée, vous pouvez omettre l'annotation.

Interfaces et types personnalisés

Les interfaces sont au cœur de TypeScript. Elles permettent de définir des contrats de structure que vos objets doivent respecter :

interface ApiResponse<T> {
  data: T;
  status: number;
  message: string;
  timestamp: Date;
}

interface PaginatedResponse<T> extends ApiResponse<T[]> {
  page: number;
  totalPages: number;
  totalItems: number;
}

type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";

interface RequestConfig {
  url: string;
  method: HttpMethod;
  headers?: Record<string, string>;
  body?: unknown;
}

L'utilisation des génériques (<T>) rend vos interfaces réutilisables dans de nombreux contextes. Les types union comme HttpMethod limitent les valeurs possibles et empêchent les fautes de frappe.

Gérer les valeurs nullables

L'une des sources principales de bugs en JavaScript est l'accès à des propriétés sur des valeurs null ou undefined. TypeScript résout ce problème grâce à l'option strictNullChecks :

function findUser(id: number): User | undefined {
  const users: User[] = getUsers();
  return users.find(user => user.id === id);
}

const user = findUser(42);
if (user) {
  console.log(formatUserName(user)); // Type garanti ici
}

Le compilateur vous oblige à vérifier l'existence d'une valeur avant de l'utiliser, éliminant ainsi toute une catégorie de bugs liés aux références nulles.

Étape 4 : Intégration dans la chaîne d'outils

Une migration réussie ne se limite pas à la conversion du code. Il est important d'intégrer TypeScript dans votre chaîne d'outils existante pour garantir une expérience de développement fluide.

Configuration des scripts npm

Ajoutez des scripts utiles à votre fichier package.json pour automatiser la compilation et la vérification des types :

{
  "scripts": {
    "build": "tsc",
    "build:watch": "tsc --watch",
    "type-check": "tsc --noEmit",
    "lint": "eslint src/**/*.ts",
    "dev": "ts-node src/index.ts"
  }
}

Intégration avec ESLint

Remplacez ou complétez votre configuration ESLint avec le parser TypeScript pour bénéficier de règles de linting spécifiques :

npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin

Configurez ensuite votre fichier .eslintrc.json pour utiliser le parser TypeScript. Cela vous permettra de détecter des erreurs de style et des anti-patterns propres à TypeScript en plus des vérifications de type.

Étape 5 : Compilation et tests

Une fois votre code migré vers TypeScript, compilez-le en JavaScript et testez-le rigoureusement pour vous assurer qu'il fonctionne comme prévu. Utilisez la commande suivante :

tsc

Cette commande génère les fichiers JavaScript qui peuvent être exécutés dans n'importe quel environnement JavaScript. Les fichiers de sortie respectent la cible définie dans votre tsconfig.json (ES2020 dans notre exemple).

Mise en place des tests unitaires

Si vous utilisez Jest pour vos tests, installez ts-jest pour exécuter vos tests directement en TypeScript sans étape de compilation préalable :

npm install --save-dev ts-jest @types/jest
npx ts-jest config:init

Vos fichiers de test peuvent désormais utiliser l'extension .test.ts et bénéficier du typage complet dans les assertions :

import { formatUserName } from './userService';
import type { User } from './userService';

describe('formatUserName', () => {
  it('devrait formater le nom complet', () => {
    const user: User = {
      id: 1,
      firstName: 'Jean',
      lastName: 'Dupont',
      email: 'jean@exemple.fr'
    };
    expect(formatUserName(user)).toBe('Jean Dupont');
  });
});

Activation progressive du mode strict

Une fois que la majorité de votre code est migré et testé, activez progressivement les options strictes dans votre tsconfig.json. Voici l'ordre recommandé :

1. noImplicitAny : interdit les variables sans type explicite lorsque TypeScript ne peut pas les inférer.
2. strictNullChecks : oblige à gérer les cas null et undefined.
3. strictFunctionTypes : renforce la vérification des types de paramètres dans les fonctions.
4. strict: true : active toutes les vérifications strictes d'un seul coup une fois le code entièrement nettoyé.

Pièges et erreurs courantes

Voici les erreurs les plus fréquentes rencontrées lors d'une migration vers TypeScript, accompagnées de solutions concrètes pour les éviter :

• Ne pas configurer correctement tsconfig.json : une mauvaise configuration peut mener à des erreurs de compilation inexplicables. Partez toujours d'une configuration connue et fonctionnelle.
• Abuser du type any : utiliser any partout annule tous les bénéfices de TypeScript. Préférez unknown lorsque le type réel est incertain, et affinez ensuite avec des gardes de type.
• Ignorer les erreurs de type : les supprimer avec des commentaires @ts-ignore peut masquer des bugs importants. Corrigez chaque erreur pour garantir l'intégrité du code.
• Ne pas tester le code migré : la compilation réussie ne garantit pas un fonctionnement correct. Maintenez une suite de tests complète tout au long de la migration.
• Surcharger le projet de types complexes dès le début : commencez par des types simples et introduisez les génériques et les types conditionnels uniquement lorsque le besoin se fait sentir.
• Négliger la mise à jour des dépendances : assurez-vous que les fichiers @types correspondent aux versions des bibliothèques installées pour éviter les incompatibilités.

Conclusion

Migrer un projet JavaScript vers TypeScript est un investissement stratégique qui renforce la robustesse, la lisibilité et la maintenabilité du code. Cela nécessite une approche progressive et soignée, mais les bénéfices à long terme sont considérables : moins de bugs en production, un refactoring plus sûr et une meilleure collaboration au sein des équipes de développement.

Voici les points essentiels à retenir de ce guide :

• TypeScript réduit les erreurs de type et améliore la productivité grâce à l'autocomplétion.
• Configurer tsconfig.json correctement dès le départ est crucial pour une migration réussie.
• Renommer les fichiers de .js à .ts progressivement, en commençant par les modules les plus simples.
• Utiliser des interfaces et des annotations de type pour documenter la structure du code.
• Intégrer TypeScript dans la chaîne d'outils existante : ESLint, Jest, scripts npm.
• Compiler, tester et activer le mode strict de manière progressive.

Commencez dès maintenant à migrer vos projets et profitez des avantages de TypeScript pour construire des applications plus fiables et plus maintenables.