Alias module loader (alias-loader.mjs)
Alias module loader (alias-loader.mjs)
Résolution d'alias d'import et ajout automatique du suffixe .ts pendant le build et en dev
Un guide pratique pour utiliser le chargeur d’alias lors du développement et du build : configuration, cas d’usage et diagnostics pas à pas.
Fonctionnalités couvertes
Résolution d'alias
Permet d’utiliser des alias d’import courts (ex. alias racine) pour référencer facilement des répertoires sans écrire de chemins relatifs complexes.
Ajout automatique de .ts
Si vous importez un module sans extension, le chargeur tente automatiquement d’ajouter le suffixe .ts lorsque le fichier correspondant existe.
Compatibilité pour workers et build
Fonctionne au moment de l’exécution du bundler / des workers et durant le développement pour harmoniser la résolution des imports.
Support des imports relatifs intelligents
Pour les imports relatifs sans extension, le chargeur tente les variantes usuelles (fichier.ts puis répertoire/index.ts) avant d’abandonner.
Comportement transparent
Ne modifie pas votre code source : il intervient uniquement au moment de la résolution des modules pour faciliter le dev.
Utilisation simple
S’active via les options de lancement de l’environnement de développement / worker ; pas besoin de toucher vos imports existants.
Intro Ce guide explique comment profiter du chargeur d’alias pour résoudre proprement les imports pendant le développement et le build. Vous apprendrez à l’activer, à configurer vos alias, à l’utiliser pour les workers, et à diagnostiquer les erreurs d’importation courantes. Les instructions sont orientées « comment faire » (pas d’explication interne) et adaptées à des applications SPA côté client et processus côté serveur/worker.
Workflow : Activer et configurer le chargeur d'alias en développement
Étape 1 — Vérifier votre configuration de lancement
Identifiez l’endroit où vous démarrez votre environnement de développement ou vos processus worker (commande de démarrage, configuration du runner CI ou options du processus). Le chargeur d’alias doit être référencé comme option de résolution de modules au démarrage de ces processus.
Étape 2 — Définir vos alias
Dans la section de configuration dédiée aux résolutions (ou via la structure de configuration de votre outil), déclarez des alias courts et clairs qui pointent vers les répertoires racines les plus utilisés (par exemple un alias racine pour la source). Utilisez des préfixes consistants pour éviter les collisions.
Étape 3 — Redémarrer le processus de dev/build
Après avoir activé le chargeur et défini les alias, redémarrez votre environnement de développement ou votre processus worker pour que la nouvelle résolution prenne effet.
Étape 4 — Tester les imports
Ouvrez des modules qui utilisent les alias et vérifiez que l’IDE / le bundler n’émet plus d’erreurs d’import. Testez aussi les imports sans extension pour confirmer que le suffixe .ts est bien ajouté automatiquement.
Étape 5 — Valider en workflow
Lancez un scénario courant (navigation dans l’app, exécution d’un worker, build local) pour vérifier que tout fonctionne dans les chemins réels d’utilisation.
Tip : Choisir des alias explicites
Privilégiez des alias courts mais explicites (par ex. racine-projet/ plutôt que un seul caractère). Cela réduit les risques de collision avec des packages externes et facilite la lecture des imports.
Workflow : Utiliser le chargeur avec des processus worker ou background
Étape 1 — Identifier les processus concernés
Déterminez quels processus en dehors du serveur principal (workers, tâches en arrière-plan, outils CLI) doivent également bénéficier de la résolution d’alias.
Étape 2 — Propager l'option de résolution
Assurez-vous que la même option de résolution est passée aux commandes ou au gestionnaire de processus qui lancent ces workers. Les workers exécutés séparément doivent recevoir la même configuration de résolution pour éviter des divergences.
Étape 3 — Tester en condition réelle
Démarrez vos workers et exécutez des actions qui déclenchent les imports concernés. Observez les logs et le comportement pour vérifier la cohérence.
Étape 4 — Surveiller les builds packagés
Pour les bundles produits (artefacts de build destinés à la production), vérifiez que les modules externes attendus restent gérés de manière identique ; le chargeur est principalement utile au moment du build/dev, pas nécessairement en production runtime.
Tip : Synchroniser l'IDE
Si votre éditeur de code ou votre extension TypeScript/JS ne reconnaît pas les alias, ajoutez les mêmes alias dans sa configuration de résolution de modules. Cela améliore l’auto-complétion et évite des faux positifs d’erreur dans l’éditeur.
Attention — Limites courantes
Le mécanisme d’ajout automatique du suffixe .ts dépend de l’existence effective des fichiers correspondants. Si plusieurs variantes de fichiers existent (par ex. fichier.ts et fichier.js), la résolution peut choisir la variante détectée en priorité par le runtime ; vérifiez vos conventions d’extensions pour éviter les ambiguïtés.
Workflow : Diagnostiquer et réparer les erreurs d'importation
Étape 1 — Lire l'erreur exacte
Commencez par lire attentivement le message d’erreur fourni par le bundler ou le runtime : il indique souvent le specifier non résolu et la raison (fichier introuvable, extension manquante, etc.).
Étape 2 — Vérifier l'alias déclaré
Confirmez que l’alias utilisé dans l’import correspond exactement à une entrée de la résolution (même préfixe et sensibilité à la casse). Une faute d’orthographe ou un préfixe mal placé bloque la résolution.
Étape 3 — Confirmer l'existence du fichier cible
Assurez-vous que le chemin ciblé existe dans le projet et porte l’extension attendue. Si l’import est sans extension, vérifiez la présence de la variante en .ts ou d’un index.ts dans un dossier.
Étape 4 — Tester un import relatif alternatif
Pour isoler le problème, remplacez temporairement l’import par un chemin relatif complet (avec extension) pour voir si l’erreur disparaît : cela confirme s’il s’agit d’un problème d’alias ou d’un problème de fichier manquant.
Étape 5 — Synchroniser configuration dev / workers
Si ça marche en dev mais pas pour les workers (ou inversement), revérifiez que la même configuration de résolution est appliquée aux deux environnements.
Étape 6 — Redémarrer et nettoyer le cache
Après modifications, redémarrez les processus concernés et, si nécessaire, supprimez les caches du bundler/outil pour éviter des résidus de résolution.
Étape 7 — Consulter les logs avancés
Si l’erreur persiste, activez un niveau de log plus verbeux sur le build/worker pour obtenir plus de détails sur la tentative de résolution et les chemins vérifiés.
- Approche : activer le chargeur pour la commande de dev afin d’écrire des imports propres (alias + omission d’extension).
- Avantage : code plus lisible, chemins stables.
- Tester : navigation de l’app et exécution des flows usuels.
Avant : sans chargeur d’alias
- Imports verbeux et sujets aux erreurs de chemin relatif.
- Nécessité d’ajouter manuellement les extensions dans chaque import.
- Divergences possibles entre dev, workers et build.
Après : avec chargeur d’alias
- Imports plus lisibles et maintenables via alias.
- Omission possible de l’extension .ts avec ajout automatique quand le fichier existe.
- Comportement uniforme entre environnements si bien configuré.
Tip : Règles de nommage et bonnes pratiques pour les imports
- Standardisez une convention d’alias (ex. alias-racine/) et documentez-la dans le README du projet.
- Encouragez les imports par alias dans les revues de code pour garder une base cohérente.
- Assurez une correspondance entre les alias déclarés et la configuration de l’éditeur pour éviter les faux positifs.
Piège fréquent : différences IDE vs runtime
Un import peut sembler correct dans l’éditeur (grâce à sa propre résolution) mais échouer au runtime si le processus de dev/build n’utilise pas exactement la même configuration de résolution. Toujours tester dans l’environnement d’exécution utilisé par vos CI/workers.
Checklist rapide pour corriger un import non résolu
1. Lire le message d'erreur
Repérer le specifier non résolu et l’environnement qui en fait état (dev, worker, build).
2. Vérifier la déclaration d'alias
Confirmer l’exactitude de l’alias et sa portée (global, par process, par package).
3. Confirmer l'existence du fichier .ts ou index.ts
S’assurer que la cible est présente et qu’il n’y a pas de doublons source d’ambiguïté.
4. Synchroniser l'éditeur et l'environnement
Mettre à jour la config d’IDE si nécessaire, puis redémarrer les processus.
5. Nettoyer les caches et redémarrer
Vider les caches du bundler et relancer pour forcer la nouvelle résolution.
6. Demander un second avis
Si le problème persiste, reproduisez le cas minimal et sollicitez un collègue : souvent un œil externe repère la faute d’alias ou la coquille.
Foire aux questions
Ressources & conseils pratiques
- Documentez la liste exacte d’alias autorisés dans le README du projet.
- Ajoutez une section “Resolver” dans la doc de contribution pour expliquer comment lancer les workers et le dev avec la bonne configuration.
- Standardisez l’usage des extensions (.ts) pour réduire les cas ambigus.
Besoin d'aide pour intégrer le chargeur d'alias ?
Si vous rencontrez des cas compliqués (monorepo, packages externes, imports dynamiques), collectez un exemple minimal et demandez de l’aide : un diagnostic ciblé permet une résolution rapide.