Étapes pour typer un bloc React existant, sans casser les tests

Onze fichiers JavaScript, trois composants imbriqués, deux hooks personnalisés et zéro personne dans l’équipe ayant déjà mené une migration TypeScript de bout en bout : c’est le point de départ d’un bloc de configurateur de produit qui fonctionnait en production depuis plus d’un an, et qu’il fallait typer sans réécriture complète ni risque de régression.

La contrainte principale n’était pas technique mais organisationnelle : sans référent TypeScript en interne, chaque étape devait rester réversible et vérifiable par la suite de tests existante, plutôt que de reposer sur une intuition individuelle de ce qui « devrait » fonctionner.

1. Ajouter TypeScript sans migrer un seul fichier

La première étape consiste à installer les dépendances nécessaires et à configurer un fichier tsconfig.json permissif, sans convertir immédiatement de fichier .js en .tsx :

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "jsx": "react",
    "strict": false,
    "noImplicitAny": false,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

Cette configuration ne casse rien : elle prépare simplement l’outillage sans imposer de contrainte de typage aux fichiers existants.

2. Faire tourner la suite de tests avant toute conversion

Avant de toucher au moindre fichier, la suite de tests existante (basée sur @wordpress/scripts test-unit-js) doit passer intégralement, pour établir une référence fiable :

npx wp-scripts test-unit-js --coverage

Ce point de départ documenté permet de savoir, à chaque étape suivante, si une régression provient de la conversion en cours ou d’un problème préexistant.

3. Convertir les fichiers sans logique métier en premier

Les fichiers de constantes, de types partagés ou de petits composants purement présentationnels se convertissent en premier, car ils comportent peu de logique susceptible de révéler des erreurs de typage complexes :

// avant : constantes.js
export const TAILLES_DISPONIBLES = ['S', 'M', 'L', 'XL'];

// après : constantes.ts
export const TAILLES_DISPONIBLES: string[] = ['S', 'M', 'L', 'XL'];

4. S’appuyer sur les types officiels de l’écosystème WordPress

Les paquets @wordpress/blocks, @wordpress/block-editor et @wordpress/components publient leurs propres définitions de types, ce qui évite de redéfinir manuellement des interfaces déjà maintenues par le cœur du projet :

import type { BlockEditProps } from '@wordpress/blocks';

interface AttributsBlocConfigurateur {
  tailleSelectionnee: string;
  couleurSelectionnee: string;
}

function Edit( { attributes, setAttributes }: BlockEditProps<AttributsBlocConfigurateur> ) {
  // ...
}

5. Convertir un fichier, relancer les tests, committer

Chaque conversion de fichier suit la même boucle courte, sans exception :

1. Renommer le fichier de .js vers .tsx ou .ts selon son contenu ;
2. Ajouter les annotations de type minimales nécessaires pour que la compilation passe ;
3. Relancer la suite de tests unitaires ciblée sur ce fichier ;
4. Committer isolément, avec un message qui identifie clairement le fichier converti.

6. Accepter le type any temporaire, mais le tracer

Sans référent TypeScript, certaines signatures complexes (retour d’un hook personnalisé qui manipule plusieurs états liés) peuvent rester temporairement typées en any, à condition de marquer explicitement ces zones :

// TODO(typage): préciser ce type une fois la structure de retour stabilisée
function useEtatConfigurateur(): any {
  // ...
}

7. Resserrer la configuration une fois la migration achevée

Une fois l’ensemble des fichiers convertis, l’option strict peut passer à true et les occurrences de any tracées au point 6 deviennent une liste de travail résiduelle, traitée progressivement plutôt qu’en bloc.

Typer un bloc existant n’est pas un projet à part entière : c’est une succession de petits commits réversibles, chacun validé par la même suite de tests qu’avant la migration.

En résumé

Sans référent TypeScript en interne, la clé n’est pas la vitesse mais la régularité : convertir un petit nombre de fichiers chaque semaine, s’appuyer sur les types déjà fournis par l’écosystème WordPress, et ne jamais avancer sans que la suite de tests confirme l’absence de régression. Cette approche progressive diffère volontairement de l’écriture d’un bloc neuf directement en TypeScript, déjà traitée par ailleurs.