Comment configurer les alias de chemin dans les projets frontaux de manière native

À propos des alias de chemin Les projets évoluent souvent vers des structures de répertoires complexes et imbriquées. Par conséquent, les chemins d'importation peuvent devenir plus longs et plus confus, ce qui peut affecter négativement l'apparence du code et rendre plus difficile la compréhension de l'origine du code importé. L'utilisation d'alias de chemin peut résoudre le problème en permettant la définition d'importations relatives à des répertoires prédéfinis. Cette approche résout non seulement les problèmes de compréhension des chemins d'importation, mais elle simplifie également le processus de déplacement du code lors de la refactorisation. // Without Aliases import { apiClient } from '../../../../shared/api'; import { ProductView } from '../../../../entities/product/components/ProductView'; import { addProductToCart } from '../../../add-to-cart/actions'; // With Aliases import { apiClient } from '#shared/api'; import { ProductView } from '#entities/product/components/ProductView'; import { addProductToCart } from '#features/add-to-cart/actions'; Il existe plusieurs bibliothèques disponibles pour configurer les alias de chemin dans Node.js, telles que et . Cependant, en parcourant la documentation de Node.js, j'ai découvert un moyen de configurer des alias de chemin sans avoir à recourir à des bibliothèques tierces. alias-hq tsconfig-paths De plus, cette approche permet l'utilisation d'alias sans nécessiter l'étape de génération. Dans cet article, nous discuterons et de la manière de configurer les alias de chemin en les utilisant. Nous explorerons également leur prise en charge dans l'écosystème frontal. des importations de sous-chemins Node.js Le champ des importations À partir de Node.js v12.19.0, les développeurs peuvent utiliser pour déclarer des alias de chemin dans un package npm. Cela peut être fait via le champ dans le fichier . Il n'est pas nécessaire de publier le package sur npm. Subpath Imports imports package.json Créer un fichier dans n'importe quel répertoire suffit. Par conséquent, cette méthode convient également aux projets privés. package.json Voici un fait intéressant : Node.js a introduit la prise en charge du champ en 2020 via la RFC appelée " ". Alors que cette RFC est principalement reconnue pour le champ , qui permet la déclaration des points d'entrée pour les packages npm, les champs et traitent des tâches complètement différentes, même s'ils ont des noms et une syntaxe similaires. imports Bare Module Specificer Resolution in node.js exports exports imports La prise en charge native des alias de chemin présente en théorie les avantages suivants : Il n'est pas nécessaire d'installer des bibliothèques tierces. Il n'est pas nécessaire de pré-construire ou de traiter les importations à la volée pour exécuter le code. Les alias sont pris en charge par tous les outils basés sur Node.js qui utilisent le mécanisme de résolution d'importation standard. La navigation dans le code et la saisie semi-automatique devraient fonctionner dans les éditeurs de code sans nécessiter de configuration supplémentaire. J'ai essayé de configurer des alias de chemin dans mes projets et testé ces instructions dans la pratique. Configuration des alias de chemin Prenons l'exemple d'un projet avec la structure de répertoires suivante : my-awesome-project ├── src/ │ ├── entities/ │ │ └── product/ │ │ └── components/ │ │ └── ProductView.js │ ├── features/ │ │ └── add-to-cart/ │ │ └── actions/ │ │ └── index.js │ └── shared/ │ └── api/ │ └── index.js └── package.json Pour configurer les alias de chemin, vous pouvez ajouter quelques lignes à comme décrit dans la documentation. Par exemple, si vous souhaitez autoriser les importations relatives au répertoire , ajoutez le champ suivant à : package.json src imports package.json { "name": "my-awesome-project", "imports": { "#*": "./src/*" } } Pour utiliser l'alias configuré, les importations peuvent être écrites comme ceci : import { apiClient } from '#shared/api'; import { ProductView } from '#entities/product/components/ProductView'; import { addProductToCart } from '#features/add-to-cart/actions'; À partir de la phase de configuration, nous sommes confrontés à la première limitation : les entrées dans le champ doivent commencer par le symbole . Cela garantit qu'ils sont distingués des spécificateurs de package tels que . imports # @ Je pense que cette limitation est utile car elle permet aux développeurs de déterminer rapidement quand un alias de chemin est utilisé dans une importation et où les configurations d'alias peuvent être trouvées. Pour ajouter plus d'alias de chemin pour les modules couramment utilisés, le champ peut être modifié comme suit : imports { "name": "my-awesome-project", "imports": { "#modules/*": "./path/to/modules/*", "#logger": "./src/shared/lib/logger.js", "#*": "./src/*" } } Il serait idéal de conclure l'article avec la phrase "tout le reste fonctionnera comme prévu". Cependant, en réalité, si vous envisagez d'utiliser le champ , vous pouvez rencontrer certaines difficultés. imports Limites de Node.js Si vous envisagez d'utiliser des alias de chemin avec , j'ai une mauvaise nouvelle pour vous : le code suivant ne fonctionnera pas. les modules CommonJS const { apiClient } = require('#shared/api'); const { ProductView } = require('#entities/product/components/ProductView'); const { addProductToCart } = require('#features/add-to-cart/actions'); Lorsque vous utilisez des alias de chemin dans Node.js, vous devez suivre les règles de résolution de module du monde ESM. Cela s'applique à la fois aux modules ES et aux modules CommonJS et entraîne deux nouvelles exigences qui doivent être satisfaites : Il est nécessaire de spécifier le chemin d'accès complet à un fichier, y compris l'extension de fichier. Il n'est pas autorisé de spécifier un chemin d'accès à un répertoire et de s'attendre à importer un fichier . Au lieu de cela, le chemin complet vers un fichier doit être spécifié. index.js index.js Pour permettre à Node.js de résoudre correctement les modules, les importations doivent être corrigées comme suit : const { apiClient } = require('#shared/api/index.js'); const { ProductView } = require('#entities/product/components/ProductView.js'); const { addProductToCart } = require('#features/add-to-cart/actions/index.js'); Ces limitations peuvent entraîner des problèmes lors de la configuration du champ dans un projet comportant de nombreux modules CommonJS. Cependant, si vous utilisez déjà des modules ES, votre code répond à toutes les exigences. imports De plus, si vous créez du code à l'aide d'un bundler, vous pouvez contourner ces limitations. Nous verrons comment procéder ci-dessous. Prise en charge des importations de sous-chemin dans TypeScript Pour résoudre correctement les modules importés pour la vérification de type, TypeScript doit prendre en charge le champ . Cette fonctionnalité est à partir de la version 4.8.1, mais uniquement si les limitations Node.js répertoriées ci-dessus sont remplies. imports prise en charge Pour utiliser le champ pour la résolution de module, quelques options doivent être configurées dans le fichier . imports tsconfig.json { "compilerOptions": { /* Specify what module code is generated. */ "module": "esnext", /* Specify how TypeScript looks up a file from a given module specifier. */ "moduleResolution": "nodenext" } } Cette configuration permet au champ de fonctionner de la même manière que dans Node.js. Cela signifie que si vous oubliez d'inclure une extension de fichier dans une importation de module, TypeScript générera une erreur vous en avertissant. imports // OK import { apiClient } from '#shared/api/index.js'; // Error: Cannot find module '#src/shared/api/index' or its corresponding type declarations. import { apiClient } from '#shared/api/index'; // Error: Cannot find module '#src/shared/api' or its corresponding type declarations. import { apiClient } from '#shared/api'; // Error: Relative import paths need explicit file extensions in EcmaScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './relative.js'? import { foo } from './relative'; Je ne voulais pas réécrire toutes les importations, car la plupart de mes projets utilisent un bundler pour générer du code, et je n'ajoute jamais d'extensions de fichiers lors de l'importation de modules. Pour contourner cette limitation, j'ai trouvé un moyen de configurer le projet comme suit : { "name": "my-awesome-project", "imports": { "#*": [ "./src/*", "./src/*.ts", "./src/*.tsx", "./src/*.js", "./src/*.jsx", "./src/*/index.ts", "./src/*/index.tsx", "./src/*/index.js", "./src/*/index.jsx" ] } } Cette configuration permet la manière habituelle d'importer des modules sans avoir besoin de spécifier des extensions. Cela fonctionne même lorsqu'un chemin d'importation pointe vers un répertoire. // OK import { apiClient } from '#shared/api/index.js'; // OK import { apiClient } from '#shared/api/index'; // OK import { apiClient } from '#shared/api'; // Error: Relative import paths need explicit file extensions in EcmaScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './relative.js'? import { foo } from './relative'; Il nous reste un problème concernant l'importation à l'aide d'un chemin relatif. Ce problème n'est pas lié aux alias de chemin. TypeScript génère une erreur car nous avons configuré la résolution du module pour utiliser le mode . nodenext Heureusement, un nouveau mode de résolution de module a été ajouté dans la récente qui supprime la nécessité de spécifier le chemin complet dans les importations. Pour activer ce mode, quelques options doivent être configurées dans le fichier . version de TypeScript 5.0 tsconfig.json { "compilerOptions": { /* Specify what module code is generated. */ "module": "esnext", /* Specify how TypeScript looks up a file from a given module specifier. */ "moduleResolution": "bundler" } } Une fois la configuration terminée, les importations de chemins relatifs fonctionneront comme d'habitude. // OK import { apiClient } from '#shared/api/index.js'; // OK import { apiClient } from '#shared/api/index'; // OK import { apiClient } from '#shared/api'; // OK import { foo } from './relative'; Désormais, nous pouvons utiliser pleinement les alias de chemin via le champ sans aucune limitation supplémentaire sur la manière d'écrire les chemins d'importation. imports Code de construction avec TypeScript Lors de la construction du code source à l'aide du compilateur , une configuration supplémentaire peut être nécessaire. Une limitation de TypeScript est qu'un code ne peut pas être construit au format de module CommonJS lors de l'utilisation du champ . tsc imports Par conséquent, le code doit être compilé au format ESM et le champ doit être ajouté à pour exécuter le code compilé dans Node.js. type package.json { "name": "my-awesome-project", "type": "module", "imports": { "#*": "./src/*" } } Si votre code est compilé dans un répertoire séparé, tel que , le module peut ne pas être trouvé par Node.js car l'alias de chemin pointerait vers l'emplacement d'origine, tel que . Pour résoudre ce problème, des chemins d'importation conditionnels peuvent être utilisés dans le fichier . build/ src/ package.json Cela permet d'importer du code déjà construit depuis le répertoire au lieu du répertoire . build/ src/ { "name": "my-awesome-project", "type": "module", "imports": { "#*": { "default": "./src/*", "production": "./build/*" } } } Pour utiliser une condition d'importation spécifique, Node.js doit être lancé avec l'indicateur . --conditions node --conditions=production build/index.js Prise en charge des importations de sous-chemin dans les code bundlers Les bundlers de code utilisent généralement leur propre implémentation de résolution de module, plutôt que celle intégrée à Node.js. Par conséquent, il est important pour eux de mettre en œuvre un support pour le domaine . imports J'ai testé des alias de chemin avec Webpack, Rollup et Vite dans mes projets et je suis prêt à partager mes découvertes. Voici la configuration d'alias de chemin que j'ai utilisée pour tester les bundlers. J'ai utilisé la même astuce que pour TypeScript pour éviter d'avoir à spécifier le chemin complet des fichiers à l'intérieur des importations. { "name": "my-awesome-project", "type": "module", "imports": { "#*": [ "./src/*", "./src/*.ts", "./src/*.tsx", "./src/*.js", "./src/*.jsx", "./src/*/index.ts", "./src/*/index.tsx", "./src/*/index.js", "./src/*/index.jsx" ] } } Webpack Webpack le champ à partir de la v5.0. Les alias de chemin fonctionnent sans aucune configuration supplémentaire. Voici la configuration Webpack que j'ai utilisée pour créer un projet de test avec TypeScript : prend en charge imports const config = { mode: 'development', devtool: false, entry: './src/index.ts', module: { rules: [ { test: /\.tsx?$/, use: { loader: 'babel-loader', options: { presets: ['@babel/preset-typescript'], }, }, }, ], }, resolve: { extensions: ['.ts', '.tsx', '.js', '.jsx'], }, }; export default config; Vite La prise en charge du champ a été dans Vite version 4.2.0. Cependant, un bogue important a été corrigé dans la version 4.3.3, il est donc recommandé d'utiliser au moins cette version. Dans Vite, les alias de chemin fonctionnent sans nécessiter de configuration supplémentaire dans les modes et . imports ajoutée dev build Par conséquent, j'ai construit un projet de test avec une configuration complètement vide. Cumul Bien que Rollup soit utilisé dans Vite, le champ ne fonctionne pas immédiatement. Pour l'activer, vous devez installer le version 11.1.0 ou supérieure. Voici un exemple de configuration : imports @rollup/plugin-node-resolve import { nodeResolve } from '@rollup/plugin-node-resolve'; import { babel } from '@rollup/plugin-babel'; export default [ { input: 'src/index.ts', output: { name: 'mylib', file: 'build.js', format: 'es', }, plugins: [ nodeResolve({ extensions: ['.ts', '.tsx', '.js', '.jsx'], }), babel({ presets: ['@babel/preset-typescript'], extensions: ['.ts', '.tsx', '.js', '.jsx'], }), ], }, ]; Malheureusement, avec cette configuration, les alias de chemin ne fonctionnent que dans les limites de Node.js. Cela signifie que vous devez spécifier le chemin d'accès complet au fichier, y compris l'extension. La spécification d'un tableau dans le champ ne contournera pas cette limitation, car Rollup n'utilise que le premier chemin du tableau. imports Je pense qu'il est possible de résoudre ce problème en utilisant les plugins Rollup, mais je n'ai pas essayé de le faire car j'utilise principalement Rollup pour les petites bibliothèques. Dans mon cas, il était plus facile de réécrire les chemins d'importation tout au long du projet. Prise en charge des importations de sous-chemins dans les exécuteurs de test Les testeurs sont un autre groupe d'outils de développement qui dépendent fortement du mécanisme de résolution de module. Ils utilisent souvent leur propre implémentation de résolution de module, similaire aux bundlers de code. Par conséquent, il est possible que le champ ne fonctionne pas comme prévu. imports Heureusement, les outils que j'ai testés fonctionnent bien. J'ai testé les alias de chemin avec Jest v29.5.0 et Vite v0.30.1. Dans les deux cas, les alias de chemin ont fonctionné de manière transparente sans aucune configuration ou limitation supplémentaire. Jest le champ depuis la version v29.4.0. prend en charge imports Le niveau de support dans Vitest repose uniquement sur la version de Vite, qui doit être au moins v4.2.0. Prise en charge des importations de sous-chemin dans les éditeurs de code Le champ dans les bibliothèques populaires est actuellement bien pris en charge. Mais qu'en est-il des éditeurs de code ? J'ai testé la navigation dans le code, en particulier la fonction "Aller à la définition", dans un projet qui utilise des alias de chemin. Il s'avère que la prise en charge de cette fonctionnalité dans les éditeurs de code présente quelques problèmes. imports Code VS En ce qui concerne VS Code, la version de TypeScript est cruciale. Le serveur de langage TypeScript est responsable de l'analyse et de la navigation dans le code JavaScript et TypeScript. En fonction de vos paramètres, VS Code utilisera soit la version intégrée de TypeScript, soit celle installée dans votre projet. J'ai testé la prise en charge des champs dans VS Code v1.77.3 en combinaison avec TypeScript v5.0.4. imports VS Code a les problèmes suivants avec les alias de chemin : TypeScript n'utilise pas le champ tant que le paramètre de résolution du module n'est pas défini sur ou . Par conséquent, pour l'utiliser dans VS Code, vous devez spécifier la résolution du module dans votre projet. imports nodenext bundler IntelliSense ne prend actuellement pas en charge la suggestion de chemins d'importation à l'aide du champ . Il y a un pour ce problème. imports problème ouvert Pour contourner ces deux problèmes, vous pouvez répliquer une configuration d'alias de chemin dans le fichier . Si vous n'utilisez pas TypeScript, vous pouvez faire de même dans . tsconfig.json jsconfig.json // tsconfig.json OR jsconfig.json { "compilerOptions": { "baseUrl": "./", "paths": { "#*": ["./src/*"] } } } // package.json { "name": "my-awesome-project", "imports": { "#*": "./src/*" } } Tempête Web Depuis la version 2021.3 (j'ai testé en 2022.3.4), WebStorm le champ . Cette fonctionnalité fonctionne indépendamment de la version TypeScript, car WebStorm utilise son propre analyseur de code. Cependant, WebStorm présente un ensemble de problèmes distincts concernant la prise en charge des alias de chemin : prend en charge imports L'éditeur suit strictement les restrictions imposées par Node.js sur l'utilisation des alias de chemin. La navigation dans le code ne fonctionnera pas si l'extension de fichier n'est pas explicitement spécifiée. Il en va de même pour l'importation de répertoires avec un fichier . index.js WebStorm a un bogue qui empêche l'utilisation d'un tableau de chemins dans le champ . Dans ce cas, la navigation dans le code cesse complètement de fonctionner. imports { "name": "my-awesome-project", // OK "imports": { "#*": "./src/*" }, // This breaks code navigation "imports": { "#*": ["./src/*", "./src/*.ts", "./src/*.tsx"] } } Heureusement, nous pouvons utiliser la même astuce qui résout tous les problèmes de VS Code. Plus précisément, nous pouvons répliquer une configuration d'alias de chemin dans le fichier ou . Cela permet l'utilisation d'alias de chemin sans aucune limitation. tsconfig.json jsconfig.json Configuration recommandée Sur la base de mes expériences et de mon expérience d'utilisation du champ dans divers projets, j'ai identifié les meilleures configurations d'alias de chemin pour différents types de projets. imports Sans TypeScript ni Bundler Cette configuration est destinée aux projets où le code source s'exécute dans Node.js sans nécessiter d'étapes de génération supplémentaires. Pour l'utiliser, suivez ces étapes : Configurez le champ dans un fichier . Une configuration très basique suffit dans ce cas. imports package.json Pour que la navigation dans le code fonctionne dans les éditeurs de code, il est nécessaire de configurer des alias de chemin dans un fichier . jsconfig.json // jsconfig.json { "compilerOptions": { "baseUrl": "./", "paths": { "#*": ["./src/*"] } } } // package.json { "name": "my-awesome-project", "imports": { "#*": "./src/*" } } Création de code à l'aide de TypeScript Cette configuration doit être utilisée pour les projets où le code source est écrit en TypeScript et construit à l'aide du compilateur . Il est important de configurer les éléments suivants dans cette configuration : tsc Le champ dans un fichier . Dans ce cas, il est nécessaire d'ajouter des alias de chemin conditionnels pour s'assurer que Node.js résout correctement le code compilé. imports package.json L'activation du format de package ESM dans un fichier est nécessaire car TypeScript ne peut compiler du code qu'au format ESM lors de l'utilisation du champ . package.json imports Dans un fichier , définissez le format de module ESM et . Cela permettra à TypeScript de suggérer des extensions de fichiers oubliées dans les importations. Si une extension de fichier n'est pas spécifiée, le code ne s'exécutera pas dans Node.js après la compilation. tsconfig.json moduleResolution Pour corriger la navigation dans le code dans les éditeurs de code, les alias de chemin doivent être répétés dans un fichier . tsconfig.json // tsconfig.json { "compilerOptions": { "module": "esnext", "moduleResolution": "nodenext", "baseUrl": "./", "paths": { "#*": ["./src/*"] }, "outDir": "./build" } } // package.json { "name": "my-awesome-project", "type": "module", "imports": { "#*": { "default": "./src/*", "production": "./build/*" } } } Code de construction à l'aide d'un bundler Cette configuration est destinée aux projets où le code source est regroupé. TypeScript n'est pas requis dans ce cas. S'il n'est pas présent, tous les paramètres peuvent être définis dans un fichier . jsconfig.json La principale caractéristique de cette configuration est qu'elle vous permet de contourner les limitations de Node.js concernant la spécification des extensions de fichiers dans les importations. Il est important de configurer les éléments suivants : Configurez le champ dans un fichier . Dans ce cas, vous devez ajouter un tableau de chemins à chaque alias. Cela permettra à un bundler de trouver le module importé sans avoir besoin de spécifier l'extension de fichier. imports package.json Pour corriger la navigation dans le code dans les éditeurs de code, vous devez répéter les alias de chemin dans un fichier ou . tsconfig.json jsconfig.json // tsconfig.json { "compilerOptions": { "baseUrl": "./", "paths": { "#*": ["./src/*"] } } } // package.json { "name": "my-awesome-project", "imports": { "#*": [ "./src/*", "./src/*.ts", "./src/*.tsx", "./src/*.js", "./src/*.jsx", "./src/*/index.ts", "./src/*/index.tsx", "./src/*/index.js", "./src/*/index.jsx" ] } } Conclusion La configuration des alias de chemin via le champ présente à la fois des avantages et des inconvénients par rapport à la configuration via des bibliothèques tierces. Bien que cette approche soit prise en charge par des outils de développement communs (à partir d'avril 2023), elle présente également des limites. imports Cette méthode offre les avantages suivants : Possibilité d'utiliser des alias de chemin sans avoir besoin de compiler ou de transpiler du code "à la volée". Les outils de développement les plus populaires prennent en charge les alias de chemin sans aucune configuration supplémentaire. Cela a été confirmé dans Webpack, Vite, Jest et Vitest. Cette approche favorise la configuration des alias de chemin dans un emplacement prévisible (fichier ). package.json La configuration des alias de chemin ne nécessite pas l'installation de bibliothèques tierces. Il existe cependant des inconvénients temporaires qui seront éliminés au fur et à mesure de l'évolution des outils de développement : Même les éditeurs de code populaires ont des problèmes avec la prise en charge du champ . Pour éviter ces problèmes, vous pouvez utiliser le fichier . Cependant, cela entraîne une duplication de la configuration des alias de chemin dans deux fichiers. imports jsconfig.json Certains outils de développement peuvent ne pas fonctionner avec le champ prêt à l'emploi. Par exemple, Rollup nécessite l'installation de plugins supplémentaires. imports L'utilisation du champ dans Node.js ajoute de nouvelles contraintes sur les chemins d'importation. Ces contraintes sont les mêmes que celles des modules ES, mais elles peuvent compliquer l'utilisation du champ . imports imports Les contraintes Node.js peuvent entraîner des différences d'implémentation entre Node.js et d'autres outils de développement. Par exemple, les bundlers de code peuvent ignorer les contraintes Node.js. Ces différences peuvent parfois compliquer la configuration, en particulier lors de la configuration de TypeScript. Alors, vaut-il la peine d'utiliser le champ pour configurer les alias de chemin ? Je pense que pour les nouveaux projets, oui, cette méthode vaut la peine d'être utilisée à la place des bibliothèques tierces. imports Le champ a de bonnes chances de devenir un moyen standard de configurer les alias de chemin pour de nombreux développeurs dans les années à venir, car il offre des avantages significatifs par rapport aux méthodes de configuration traditionnelles. imports Cependant, si vous avez déjà un projet avec des alias de chemin configurés, le passage au champ n'apportera pas d'avantages significatifs. imports J'espère que vous avez appris quelque chose de nouveau grâce à cet article. Merci pour la lecture! Liens utiles RFC pour la mise en œuvre des exportations et des importations Un ensemble de tests pour mieux comprendre les capacités du domaine des importations Documentation sur le champ des importations dans Node.js Limitations de Node.js sur les chemins d'importation dans les modules ES Également publié ici