TS Import Extractor : quels composants de votre bibliothèque sont importés ?

Savoir quels projets dépendent d’un composant du kit UI

Vous maintenez une bibliothèque de composants React partagée entre plusieurs applications. Avant de changer l’API d’une modale, une question arrive : quels projets l’importent encore ? Le package.json indique qu’une application dépend du kit UI, sans donner le détail des composants qu’elle importe. Chercher à la main dans chaque dépôt devient répétitif.

J’ai créé TS Import Extractor pour répondre à ce besoin d’inventaire. Ce petit script Python parcourt des projets locaux, relève les imports nommés d’une bibliothèque dans les fichiers TypeScript et TSX, puis les rassemble dans un CSV. Le besoin de départ, documenté dans le dépôt, concerne un kit UI utilisé par plusieurs projets front-end. Le nom de la dépendance est configurable.

Le résultat donne un point de départ pour préparer une migration de design system ou examiner l’adoption d’un composant. Il permet de passer d’une dépendance déclarée à une liste de symboles importés, avec les limites d’une recherche textuelle.

Préparer une migration et repérer les consommateurs à vérifier

Si un composant change de propriétés, le CSV aide à identifier les projets dans lesquels chercher les adaptations. On peut filtrer sur son nom dans un tableur et rapprocher ce relevé de la version du kit UI déclarée par chaque application. Une équipe peut ainsi préparer des tâches de migration par projet, puis retrouver les fichiers concernés dans son éditeur.

L’inventaire peut aussi éclairer une discussion sur le maintien d’un ancien composant. Un symbole peu importé devient un candidat à examiner. Sa suppression exige encore de vérifier les consommateurs hors du périmètre analysé et les formes d’import que le script ne reconnaît pas. Un rapport vide ne prouve donc pas qu’un composant est inutilisé.

Pour suivre une évolution, on peut conserver deux exports datés et comparer leurs lignes, à périmètre identique. Le script fournit les relevés ; il ne calcule ni progression de migration ni priorité métier. Le nombre d’imports reste un indice technique à relire avec les parcours concernés.

Analyser une bibliothèque TypeScript dans plusieurs projets locaux

Le README annonce Python 3.8 ou plus récent et des projets présents sur votre machine. Le script utilise uniquement la bibliothèque standard de Python : aucune installation de paquet Python n’est nécessaire. Dans le dépôt, le fichier à lancer s’appelle main.py.

git clone https://github.com/dokor/ts_import_extractor.git
cd ts_import_extractor

Dans main.py, remplacer dependance_to_analyze par le nom du paquet et renseigner projects_input avec les racines des projets. Voici une configuration fictive pour une bibliothèque nommée @exemple/ui ; les chemins doivent être adaptés à votre machine.

dependance_to_analyze = '@exemple/ui'

projects_input = {
    'portail': '/chemin/vers/portail',
    'administration': '/chemin/vers/administration',
}

Le parcours est récursif et ne prévoit pas d’exclusion de dossiers. Une racine contenant node_modules, des fichiers générés ou des tests les inclura s’ils portent une extension .ts ou .tsx. Pour un premier inventaire, choisir une copie ciblée conservant le package.json racine et les sources souhaitées, ou un clone avant installation des dépendances. Consigner ce périmètre pour pouvoir comparer les exports.

python3 main.py

# Sous Windows, si le lanceur Python est installé :
# py -3 main.py

Le fichier analyse_kitui.csv est écrit dans le répertoire courant et remplacé à chaque exécution. Son séparateur est le point-virgule et son encodage UTF-8 comporte un BOM, pour faciliter l’ouverture dans Excel. Le traitement lit les sources locales sans appel réseau et ne les modifie pas.

Lire le CSV : un import n’est pas un affichage du composant

Prenons un exemple fictif. Dans le portail, une page importe Button et Modal, renommé Dialog. Elle utilise Button trois fois dans son JSX. Dans l’administration, deux fichiers importent chacun Button. Les extraits suivants servent à expliquer le comptage à partir du code du script ; ils ne décrivent pas un projet réel ni une mesure de production.

// portail/src/Page.tsx
import { Button, Modal as Dialog } from '@exemple/ui';

export function Page() {
  return <Dialog><Button /><Button /><Button /></Dialog>;
}

// administration/src/Entete.tsx
import { Button } from '@exemple/ui';

// administration/src/Actions.tsx
import { Button } from '@exemple/ui';

Avec les versions fictives ci-dessous dans les package.json, les lignes attendues sont les suivantes. L’alias Dialog est ramené au nom importé Modal. Button compte une fois dans le portail et deux fois dans l’administration.

Project Name;Project Version;KitUI Version;Component;Usage Count
portail;1.4.0;^2.3.0;Button;1
portail;1.4.0;^2.3.0;Modal;1
administration;0.9.0;~2.2.0;Button;2

Project Version vient du champ version du package.json racine. KitUI Version reprend la déclaration trouvée dans dependencies ou, à défaut, devDependencies. Une plage comme ^2.3.0 reste une plage : le script ne lit pas le fichier de verrouillage pour retrouver la version effectivement installée. Une version absente ou un package.json illisible donne N/A. Un projet sans import reconnu n’a pas de ligne dans le CSV.

Les syntaxes et les fichiers à contrôler avant de décider

La version consultée le 2 novembre 2026 recherche les imports avec une expression régulière. Elle reconnaît la forme import { Button } from '@exemple/ui';, y compris sur plusieurs lignes, et traite les alias écrits avec as. Elle attend un point-virgule après la chaîne du module. Le nom du paquet est inséré tel quel dans l’expression : des caractères spéciaux de regex dans ce nom peuvent fausser la correspondance.

• Les imports par défaut, les imports d’espace de noms et les chargements dynamiques ne sont pas relevés.
• La forme import type { ... } et les réexports export { ... } from ne sont pas reconnus. La forme import { type Theme } est comptée sous le nom type Theme, sans normalisation. Les sous-chemins du paquet ne sont pas agrégés avec son nom racine.
• Les commentaires et les chaînes ne sont pas analysés comme du TypeScript. Un texte ressemblant à un import peut produire un faux positif.
• Le rapport ne fournit pas les chemins des fichiers sources et ne suit pas les usages des symboles après leur import. Il faut revenir au code pour préparer la modification.

Avant d’interpréter un CSV vide, vérifier les chemins configurés : un chemin inexistant peut produire uniquement l’en-tête, sans message d’erreur. Une erreur de lecture d’un fichier source peut interrompre l’analyse. Ces situations demandent de contrôler le périmètre avant de conclure à une absence d’imports.

Pour un audit exhaustif, ces limites peuvent justifier une analyse fondée sur l’arbre syntaxique TypeScript. Pour essayer ce mini-outil, choisir d’abord un composant dont vous connaissez les consommateurs, vérifier quelques imports à la main, puis comparer avec le CSV. Ce premier contrôle permet de juger si le relevé est adapté à votre projet avant d’en tirer une décision de migration.

Sources et liens utiles

• TS Import Extractor : récupérer le script sur GitHub
• README : usages, prérequis et limites, consulté le 2 novembre 2026
• main.py : extraction, comptage et export CSV dans la version examinée
• Mes produits et mes outils personnels
• Évaluer le besoin et le coût d’adoption d’un outil
• Préparer une pull request de migration facile à relire