La structure d'un projet (4) : l'import qui compile et ne démarre pas
Par Dorian Chávez · cofondateur et Chief Executive Officer de Hábil ·
Votre alias de tsconfig.json compile et Node ne démarre pas : il ne lit pas ce fichier. Ce que décident tsconfig et package.json, et un modèle qui le prouve.
La structure d'un projet · épisode 4 sur 7 · TypeScript
Scénario : les personnages et l'histoire sont inventés. Les données techniques et les citations ont leur source à la fin.
En 1 minute
paths, l'option detsconfig.jsonpour les alias, ne change pas ce que le compilateur écrit. L'alias sort tel quel dans le JavaScript, et Node ne sait pas ce que c'est [1][2].- Node ne lit pas
tsconfig.json. Pour donner un nom à un module, il lit le champ"imports"depackage.json, et ce champ, TypeScript le comprend aussi [1][3][4]. tsconfig.jsondécide comment TypeScript vérifie le programme et comment il l'émet (émettre : écrire les fichiers dedist/). Il ne configure pas le Node qui l'exécute [3].- Les tests et le code se compilent à part, avec un
tsconfigchacun : ainsidist/n'emporte pas de tests et le code ne peut pas s'appuyer sur eux [7][8]. - Tu repars avec un modèle qui se clone et tourne du premier coup, avec un script qui démontre cette frontière en passant au rouge quand il le faut.
- Pour lundi : cherche
pathsdans tontsconfig.jsonet demande-toi qui résout ces noms quand le programme tourne.
Dans cet article
- Que s'est-il passé mardi à 17:48 ?
- Que décide tsconfig.json, et que ne décide-t-il pas ?
- Quelles sont cinq erreurs fréquentes ?
- Exercice : peux-tu le faire compiler sans qu'il démarre ?
- À retenir
- Et ensuite ?
- Le modèle et le cours
- Que fait Hábil ?
- Références
Que s'est-il passé mardi à 17:48 ?
Iván a écrit un import que le compilateur a accepté et que Node, au démarrage, n'a pas trouvé.
Mardi, 17:05. Troisième étage.
Quatrième mission, la première en TypeScript. Encore le vérificateur, celui de Go, de Python et de Rust, qui interroge des services en HTTP. Cette fois, il vivait à l'intérieur d'une API, et la demande était courte : « Que la vérification puisse aussi se lancer depuis main ».
Le projet avait été laissé par quelqu'un d'autre. Il avait bonne mine :
src/
main.ts
revisar.ts
reporte.ts
package.json
tsconfig.jsonDans tsconfig.json, Iván trouva une ligne qui lui plut :
"paths": { "@/*": ["./src/*.ts"] }Un alias. Avec ça, il pouvait écrire @/revisar au lieu de compter les points et les barres obliques. Il l'utilisa dans src/main.ts :
import { revisarTodos } from "@/revisar";L'éditeur lui complétait le nom de la fonction. Ça compila :
$ npx tsc -p tsconfig.build.json
$Rien. Pas une erreur, pas un avertissement. Il poussa le changement.
Mardi, 17:48.
Le serveur de test démarra la nouvelle version avec node dist/main.js. La réponse (raccourcie ; le chemin change sur chaque machine) :
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@/revisar' imported from …/dist/main.jsUn paquet ? Iván n'avait installé aucun paquet. revisar était un fichier à lui, il était là, et le compilateur l'avait trouvé. Il ouvrit dist/main.js pour voir ce qu'avait écrit tsc :
import { revisarTodos } from "@/revisar";Sa ligne, identique. Le compilateur avait retiré les types et avait laissé l'alias tel quel.
À 17:56, il écrivit à Lucía, la responsable technique.
— Ça compile et ça ne démarre pas. Il dit qu'il ne trouve pas @/revisar.
— Qui sait où se trouve @ ? répondit-elle.
— Le tsconfig.
— Et qui démarre le programme ?
Iván regarda la commande. node dist/main.js. Dans cette ligne, il n'y avait aucun tsconfig.
— Node.
— Node ne lit pas ce fichier. Demain, je te montre lequel il lit.
Iván regarda de nouveau la ligne de l'alias. Le compilateur lui avait donné raison. Mais le compilateur n'était pas celui qui allait faire tourner le programme.
Que décide tsconfig.json, et que ne décide-t-il pas ?
Il décide comment TypeScript vérifie et émet le programme. Il ne configure pas le Node qui l'exécute : Node résout les imports au démarrage avec ses propres règles, et pour un nom avec #, il lit package.json.
La documentation de TypeScript le dit de paths sans détour, dans une section intitulée « paths does not affect emit » : l'option ne change pas le chemin de l'import dans le code qu'écrit TypeScript, et c'est pourquoi « it’s very easy to create path aliases that appear to work in TypeScript but will crash at runtime » [1]. Il est très facile de créer un alias qui semble marcher et qui plante à l'exécution. La référence de tsconfig dit alors à quoi il sert : à prévenir TypeScript « that another tool has this mapping and will use it at runtime or when bundling » [2]. Qu'un autre outil a déjà cette correspondance.
Dans le projet d'Iván, il n'y avait pas d'autre outil. Il y avait Node, et la documentation de Node referme la pince : « Node.js ignores tsconfig.json files » [3].
Les deux documentations indiquent la même sortie. Celle de TypeScript dit que le champ "imports" de package.json est « a standard replacement for convenience paths aliases » [1]. Celle de Node, que ce qui ressemble le plus à paths, ce sont les subpath imports (des noms internes d'un paquet, déclarés dans son package.json), « with the limitation that they need to start with # » [3].
Le modèle de cet épisode, estructura-typescript, est construit ainsi :
estructura-typescript/
├── package.json · package-lock.json
├── tsconfig.json LA BASE: lo común. Solo revisa
├── tsconfig.build.json la base, más «escribe dist/»
├── servicios.json el ejemplo
├── src/
│ ├── main.ts EL PROGRAMA: opciones, llamada, código de salida
│ ├── servicio.ts el vocabulario. Sin red ni archivos
│ ├── config.ts lee y valida servicios.json
│ ├── revisar.ts consulta muchos servicios a la vez
│ └── reporte.ts tabla y JSON
├── test/
│ ├── tsconfig.json las pruebas, revisadas aparte
│ ├── *.test.ts
│ └── comun/servidor.ts
├── herramientas/probar-frontera.sh
├── .github/workflows/verificar.yml
└── README.md · LICENSE · LICENSE-CONTENIDO.mdIl apporte le vérificateur en ligne de commande, sans le serveur de l'API d'Iván : la frontière est la même, et il y a moins de superflu. Allons-y partie par partie, avec la question habituelle : quel problème cela résout-il aujourd'hui ?
Qui lit chaque fichier ?
tsconfig.json, ce sont le compilateur et l'éditeur qui le lisent. package.json, les deux le lisent, et Node aussi.
C'est toute la frontière, et elle tient dans un tableau :
| Fichier | Lu par tsc (et l'éditeur) | Lu par Node au démarrage |
|---|---|---|
tsconfig.json | Oui | Non [3] |
package.json | Oui [1] | Oui [4] |
Ce que tu veux voir valoir aux deux moments, à la compilation et à l'exécution, doit se trouver dans le fichier que lisent les deux.
Que décide vraiment tsconfig.json ?
Comment TypeScript vérifie et comment il émet. L'émission, ce sont les fichiers qu'écrit tsc. La base du modèle prend six décisions, et aucune n'arrive jusqu'à Node.
{
"compilerOptions": {
"target": "es2024",
"module": "nodenext",
"strict": true,
"types": ["node"],
"rootDir": "./src",
"outDir": "./dist",
"noEmit": true
},
"include": ["src"]
}- De la vérification :
strict, ettypes, qui dit quels types globaux existent. Depuis TypeScript 6, cette liste naît vide [9] ; sans"node",processn'existe pas :error TS2591: Cannot find name 'process'(mesuré). - De l'émission :
target(quel JavaScript sort), etrootDiravecoutDir(d'où il sort et où il va). - Des deux :
module: nodenext. Il fait suivre à TypeScript les règles de modules de Node pour vérifier et pour émettre. Pour vérifier, il cherche chaque import comme le chercherait Node [5] : cette option entraînemoduleResolution: nodenext[1]. Pour émettre, il décide si chaque fichier sort en module ECMAScript ou en CommonJS [1]. Ce qu'elle ne fait pas, c'est installer ou configurer quoi que ce soit dans le Node qui va faire tourner le programme.
noEmit: true fait que ce fichier ne fait que vérifier. C'est celui qu'ouvre l'éditeur pour src/.
Il y a d'autres options (lib, jsx, declaration, sourceMap), et toutes font la même chose : elles changent la compilation. Aucune ne change la façon dont Node démarre.
Alors, comment nommer un module ?
Si tu veux un alias privé qui marche dans Node sans chargeur ni bundler : avec un nom qui commence par #, déclaré dans "imports" de package.json. Pour des fichiers voisins, le chemin relatif avec .js reste le plus simple.
Node les appelle subpath imports, des noms internes d'un paquet : un champ pour créer des « private mappings that only apply to import specifiers from within the package itself » [4]. Un specifier, ou spécificateur, c'est le texte entre guillemets d'un import. Privés : ils ne valent qu'à l'intérieur de ton paquet. Et avec une règle de forme : « Entries in the "imports" field must always start with # » [4], pour ne pas se confondre avec des paquets extérieurs.
Dans le modèle, ce sont quatre lignes :
"imports": {
"#config": "./dist/config.js",
"#reporte": "./dist/reporte.js",
"#revisar": "./dist/revisar.js",
"#servicio": "./dist/servicio.js"
}Et main.ts écrit import { revisarTodos } from "#revisar". Node lit le champ et charge dist/revisar.js.
Et TypeScript ? Il lit le même champ et arrive au même fichier. Mais dist/revisar.js n'existe pas encore quand tu compiles pour la première fois. La documentation explique l'étape en plus : si le package.json est celui du projet en cours de compilation, TypeScript cherche le fichier source qui va produire cette sortie, et pour cela il utilise outDir et rootDir, « so using "imports" usually requires an explicit rootDir to be set » [1]. C'est pourquoi la base les déclare. Mesuré : dans un clone tout frais, sans dist/, le modèle compile du premier coup.
Un seul nom, déclaré une seule fois, qui signifie la même chose à la compilation et à l'exécution. Ce n'est pas la seule façon d'importer que comprennent les deux : il y a aussi les chemins relatifs, qui arrivent juste après, et les paquets installés. C'est celle qui sert quand tu veux un alias.
Pourquoi ./servicio.js, si le fichier s'appelle servicio.ts ?
Parce qu'entre guillemets, on écrit ce que Node va charger, et dans ce modèle TypeScript le laisse tel quel.
Entre modules voisins, le modèle utilise des chemins relatifs : import { clasificar } from "./servicio.js". L'extension déroute la première fois. La règle vient de Node : dans un import, « A file extension must be provided » [6]. Et de TypeScript, qui explique que le spécificateur « is emitted as-written » [5] : il sort comme tu l'as écrit. Si Node va charger servicio.js, c'est ça que tu écris.
C'est ce qui se passe ici, pas une loi. TypeScript a une option, rewriteRelativeImportExtensions, qui remplace un .ts relatif par .js dans ce qu'il émet [24]. Le modèle ne l'active pas, donc le spécificateur sort intact.
C'est la même règle que celle de l'alias, vue d'un autre côté. Avec module: nodenext, TypeScript t'avertit bien de celle-ci. Mesuré, en retirant l'extension :
error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './servicio.js'?De l'alias, il n'avertit pas, parce que paths existe justement pour lui dire « fais confiance, quelqu'un d'autre le résout ».
Pourquoi les tests sont-ils compilés à part ?
Parce qu'un tsconfig décrit un seul programme, et que le code et ses tests en font deux : l'un se livre et l'autre non.
Le guide de TypeScript le dit ainsi : « A single tsconfig.json can only represent a single environment » [7], et il met le code de test dans la liste de ce qui mérite le sien. Sa page sur les project references raconte ce qui se passait avec un seul fichier pour src/ et test/ : « It was possible for the implementation files to import the test files », et on ne pouvait pas les compiler ensemble « without having src appear in the output folder name » [8].
Nous l'avons mesuré dans un projet de trois fichiers, avec "include": ["src", "test"] :
- Avec
rootDir: ./src, ça ne compile pas :error TS6059: File '…/test/reporte.test.ts' is not under 'rootDir'. - Sans
rootDir, ça compile, mais la sortie change de forme :dist/src/main.jsetdist/test/reporte.test.js. Les tests voyagent dans ce qui se livre, etnode dist/main.jsrépondError: Cannot find module '…/dist/main.js'. - Et
main.tsa importé un fichier detest/sans que personne ne se plaigne. Ça a compilé et tourné.
Le modèle le découpe en trois fichiers, chacun avec un travail :
| Fichier | Ce qu'il inclut | Ce qu'il fait |
|---|---|---|
tsconfig.json | src/ | La base : il vérifie, il n'écrit pas |
tsconfig.build.json | la même chose (hérite avec extends [2]) | Il écrit dist/ : les .js et leurs .d.ts (des fichiers qui décrivent des types et n'exécutent pas de code) |
test/tsconfig.json | test/ | Il vérifie les tests ; il n'écrit jamais |
Le plus fin est dans le troisième. Les tests importent #reporte, comme main.ts. Mais ce tsconfig vit dans un autre dossier et n'inclut pas src/, donc TypeScript arrive à dist/reporte.d.ts, le fichier de types qu'a laissé la construction. Mesuré : dans le programme des tests n'entre pas un seul fichier de src/. Les tests voient ce que voit quiconque utilise le code compilé.
Il y a un coût, et la même page le dit : avec plusieurs tsconfig séparés, « you end up always running tsc twice » [8]. C'est pour ça qu'existent les project references. Avec cinq fichiers, lancer deux fois ne se remarque pas ; le README dit quand franchir ce pas.
Comment les tests tournent-ils ?
Node les exécute directement depuis les .ts, en leur retirant les types ; et ils chargent le code déjà compilé, par la même porte #.
Node exécute des fichiers TypeScript qui ne contiennent que de la syntaxe effaçable : il efface les annotations de types, mais il ne transforme pas le TypeScript qui aurait besoin de générer du JavaScript nouveau. Il remplace les types par des espaces, et « no type checking is performed » [3]. Le modèle s'en sert pour les tests, avec l'exécuteur que Node apporte déjà (node --test), sans rien installer de plus. Comme Node charge ces fichiers tels quels, là les imports relatifs portent .ts : ./comun/servidor.ts. La règle n'a pas changé : tu écris ce que Node va charger.
npm test fait trois choses : il construit dist/, vérifie les types des tests et les exécute. Le rapport se termine ainsi :
ℹ tests 46
ℹ pass 46
ℹ fail 0
ℹ cancelled 0Ce sont 46 tests, et ils se comptent là. Avec un motif qui ne trouve aucun fichier, node --test sort avec 0 et ℹ tests 0 (mesuré) : un vert qui n'a rien testé.
Le motif du script, "test/**/*.test.ts", n'est pas de trop non plus. Par défaut, Node exécute tout fichier qui se trouve sous un dossier test/ [11]. Mesuré sans le motif : le serveur d'aide sort comme un test de plus, ✔ test/comun/servidor.ts, et le rapport dit 47.
Un des tests, programa.test.ts, exécute dist/main.js dans un autre processus. C'est le seul qui voit ce qu'aucune vérification de types ne voit : si Node trouve chaque module au démarrage.
Que soigne le vérificateur qu'un modèle ne doit pas enseigner de travers ?
Un délai qui couvre toute la requête, un plafond pour ce qui se lit, et des erreurs qui ne répètent jamais l'URL.
Ce qui arrive de servicios.json est unknown tant qu'il n'est pas vérifié champ par champ : les types ne surveillent pas ce qui entre à l'exécution. Le corps de chaque réponse se lit jusqu'à 64 KiB et se libère. Aucun message ne répète une URL, qui peut porter un jeton. Nous avons retiré chaque protection dans une copie, une par une : les 26 ont fait passer leur test au rouge.
Et où va l'import d'Iván ?
Dans main.ts, avec le nom #revisar ; et le nom, dans package.json.
Le mercredi, Iván et Lucía effacèrent la ligne de paths. Ils déclarèrent #revisar dans "imports" et changèrent une ligne de main.ts. L'éditeur continua à compléter. Et cette fois, ce que le compilateur acceptait était ce que Node allait chercher.
Comment savoir que la frontière existe ?
Parce qu'un script la franchit exprès à chaque changement : il sème l'alias et exige que ça compile et que ça ne démarre pas, pour la raison exacte.
herramientas/probar-frontera.sh travaille dans une copie temporaire. Il compile et démarre le même programme deux fois. Entre les deux, seule change la façon dont main.ts importe le module revisar, et qui déclare ce nom :
- Contrôle, avec le projet tel qu'il est.
main.tsimporte#revisar. Ça doit compiler et démarrer. Sinon, l'expérience est mal montée, ou ton projet contient déjà un import que Node ne résout pas, et le script s'arrête en rouge. - Violation. On sème
@/revisardanspathsetmain.tsl'importe. Ça doit compiler, avec l'alias intact dansdist/main.js, et ça doit ne pas démarrer, avecERR_MODULE_NOT_FOUND.
Voici la sortie réelle :
1/2 control: el proyecto tal como está; main.ts importa «#revisar», que package.json sí declara
✅ compiló y arrancó (revisor 0.1.0): Node encontró el módulo
2/2 violación: el mismo import, como «@/revisar», declarado solo en tsconfig.json
✅ tsc compiló sin una queja y dejó el alias tal cual en dist/main.js
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@/revisar' imported from …/dist/main.js
✅ Node no arrancó: lo que solo declara tsconfig.json, Node no lo ve
✅ frontera: se sostienePourquoi le contrôle ? Parce qu'une expérience qui n'attend qu'un rouge passe aussi au « vert » quand elle échoue pour la mauvaise raison. Nous l'avons cassée de sept façons, et les sept sont sorties en rouge. Trois sont parlantes : avec un chargeur qui résout bien l'alias, ❌ ARRANCÓ ; avec un alias que tsc rejette, il dit que la violation n'a pas compilé et que cela « no demuestra la frontera » ; avec l'alias semé dans le vrai projet, il s'arrête au contrôle.
La CI de GitHub est écrite pour lancer les types, les tests et la frontière avec la LTS la plus récente de Node et avec la 26.13.0, et la frontière aussi sur macOS avec le /bin/bash du système, à chaque changement et chaque lundi. Si le dépôt public passe 60 jours sans activité, GitHub désactive l'exécution du lundi [22].
Quelles sont cinq erreurs fréquentes ?
Les cinq viennent de la même chose : croire que tsconfig.json commande là où il ne commande pas.
1. Un alias dans paths que personne ne résout à l'exécution
Ça compile, l'éditeur l'accepte, et Node ne démarre pas.
C'est l'erreur d'Iván [1][2]. paths n'est pas une erreur en soi : il sert quand un bundler résout l'alias et qu'il suffit de prévenir TypeScript [1]. Ce qui échoue, c'est de l'utiliser seul. Ce qui le trahit, c'est ERR_MODULE_NOT_FOUND, l'erreur de Node pour un module qu'il n'a pas pu résoudre [12], avec Cannot find package : Node a cru que @/revisar était un paquet installé. Pour un alias privé, sans chargeur ni bundler, la sortie standard est "imports" [1][3].
2. Des chemins relatifs sans extension, avec une résolution qui les pardonne
Avec moduleResolution: bundler, TypeScript accepte ./servicio tout court ; Node, non.
bundler dit à TypeScript qu'un bundler va résoudre les imports. Le guide prévient que cette option « is infectious, allowing code that only works in bundlers to be produced » [7]. Mesuré dans le modèle, avec bundler et un import sans extension : ça compile, et au démarrage :
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '…/dist/servicio' imported from …/dist/revisar.jsSi ton programme tourne dans Node tel qu'il sort de tsc, l'option est nodenext, qui vérifie avec les règles de Node [5][6].
3. Un seul tsconfig.json pour le code et les tests
Soit les tests voyagent dans dist/, soit le programme change de place, soit le code finit par importer un test.
Ce sont les trois symptômes mesurés plus haut [8]. Depuis TypeScript 6, rootDir n'est plus deviné : c'est le dossier du tsconfig, et les notes de cette version décrivent le symptôme tel quel : « files being written to ./dist/src/index.js instead of ./dist/index.js » [9]. La sortie, c'est un tsconfig par programme [7].
4. Copier le tsconfig.json d'un vieux tutoriel
TypeScript 7 a retiré des options que des milliers de tutoriels enseignent encore.
TypeScript 7 est sorti le 8 juillet 2026 [10]. C'est un nouveau compilateur, et ce que la version 6 marquait comme obsolète est maintenant une erreur. L'annonce le dit des deux options les plus copiées : « baseUrl is no longer supported », et la même chose de moduleResolution: node [10]. Mesuré avec 7.0.2 :
error TS5102: Option 'baseUrl' has been removed. Please remove it from your configuration.
error TS5108: Option 'moduleResolution=node10' has been removed. Please remove it from your configuration.baseUrl était le partenaire de toujours de paths. Si ton alias dépendait des deux, la moitié n'existe plus. Avant de copier un tsconfig, regarde de quelle année il date.
5. Croire que si Node l'a exécuté, les types sont bons
Node retire les types. Il ne les vérifie pas.
Que Node exécute du .ts n'en fait pas un compilateur [3]. Mesuré avec un fichier de deux lignes, const limite: number = "cinco"; et un console.log : Node affiche cinco et sort avec 0. tsc, avec le même fichier :
error TS2322: Type 'string' is not assignable to type 'number'.Ce sont deux outils avec deux travaux. C'est pourquoi npm test vérifie les types avant d'exécuter les tests.
| Erreur | Ce qui la trahit | Source |
|---|---|---|
1. Alias dans paths sans personne pour le résoudre | ERR_MODULE_NOT_FOUND: Cannot find package '@/…' au démarrage | [1][2][3] |
2. Sans extension, avec bundler | Cannot find module '…/dist/servicio' au démarrage | [5][6][7] |
3. Un tsconfig pour tout | dist/src/main.js, des tests dans dist/, ou TS6059 | [7][8][9] |
4. Un tsconfig de vieux tutoriel | TS5102, TS5108 | [9][10] |
| 5. « Node l'a exécuté » | Un vert de Node avec un rouge de tsc | [3] |
Exercice : peux-tu le faire compiler sans qu'il démarre ?
Tu vas semer l'alias d'Iván, voir que le compilateur l'accepte, essayer de le corriger là où ça paraît logique et voir comment le script te prévient.
Il te faut Node 26.13 ou plus récent (node --version), qui apporte déjà npm, plus Git et bash ; une vingtaine de minutes.
- Sous Linux Mint 22, n'utilise pas
apt install nodejs: Mint 22 est basé sur Ubuntu 24.04 [19], qui apporte Node 18.19 [18], et avec lui les tests ne tournent pas :Could not find '…/test/**/*.test.ts'(mesuré). Installe Node avecnvm, comme le dit son README [20] :
sudo apt install curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.0/install.sh | bashOuvre un autre terminal (dans le même, nvm reste introuvable ; mesuré) et lance nvm install 26. La leçon 1 du cours de TypeScript l'explique pas à pas. - Sous macOS, la même chose, avec nvm. - Si tu as déjà nvm, nvm install 26. Sous Windows, utilise WSL.
Étape 1. Clone et vérifie que tout est au vert.
git clone https://github.com/HabilMX/estructura-typescript
cd estructura-typescript
npm ci
npm test
bash herramientas/probar-frontera.shCe que tu dois voir : ℹ pass 46 avec ℹ fail 0 et, à la fin du script, ✅ frontera: se sostiene.
Utilise ce clone uniquement pour t'entraîner. Ainsi, tout changement que tu y vois vient de l'exercice.
Étape 2. Prédis avant de toucher. Tu vas déclarer l'alias @/revisar dans tsconfig.json et l'utiliser dans main.ts. Note trois choses : est-ce que ça compile ? Est-ce que ça démarre ? Et si tu déclares en plus @/revisar dans package.json ?
Étape 3. Sème l'alias. Ces deux lignes marchent pareil sous Linux et sous macOS ; elles laissent une copie .bak de chaque fichier.
sed -i.bak 's|"outDir": "./dist",|"outDir": "./dist", "paths": { "@/*": ["./src/*.ts"] },|' tsconfig.json
sed -i.bak 's|from "#revisar"|from "@/revisar"|' src/main.ts
npm run build
node dist/main.js --versionnpm run build se termine sans une seule erreur. node ne démarre pas. La ligne qui compte :
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@/revisar' imported from …/dist/main.jsÉtape 4. Corrige-le là où ça paraît logique. Si Node lit package.json, déclare-y le même nom :
npm pkg set 'imports.@/revisar=./dist/revisar.js'
npm run build
node dist/main.js --version
bash herramientas/probar-frontera.shLe même ERR_MODULE_NOT_FOUND. Node ne cherche dans "imports" que les noms qui commencent par # ; les autres, il les traite comme des paquets. Et le script passe au rouge, sans arriver à la deuxième étape :
❌ el control NO arrancó: el programa, tal como está, no corre con node:C'est le contrôle qui travaille : ton projet contient déjà un import que Node ne résout pas.
Étape 5. Donne-lui le nom que Node cherche vraiment.
sed -i.bak 's|from "@/revisar"|from "#revisar"|' src/main.ts
npm run build
node dist/main.js --versionIl répond revisor 0.1.0. La ligne de paths est toujours dans tsconfig.json, et elle n'a servi à rien : plus personne ne l'utilise.
Étape 6. Remets seulement ce que tu as touché. L'exercice a changé trois fichiers. Avant de les remettre, regarde ce qui a changé dedans :
git diff -- tsconfig.json src/main.ts package.jsonTu dois voir deux changements : la ligne de paths dans tsconfig.json et la ligne "@/revisar" dans package.json. src/main.ts n'apparaît pas : à l'étape 5, il est redevenu comme avant. Si tu vois autre chose, c'est à toi : mets-le de côté avant de continuer.
S'il n'y a que ce qui vient de l'exercice, remets ces trois fichiers. git restore ne touche que les chemins que tu lui donnes [25] :
git restore tsconfig.json src/main.ts package.json
bash herramientas/probar-frontera.sh
git status --shortLa frontière repasse au vert, et git status montre la seule chose qui reste : les copies qu'a faites sed.
?? src/main.ts.bak
?? tsconfig.json.bakGarde-les jusqu'à être sûr de ne plus en avoir besoin. Ensuite, efface-les une par une, avec rm -i src/main.ts.bak tsconfig.json.bak, qui demande avant chacune. N'utilise pas une commande qui nettoie tout le dossier : elle emporterait aussi tes notes.
Comment savoir que tu as bien fait : tu as lancé sept fois et vu trois issues. Vert, quatre fois : les deux de l'étape 1, le programme à l'étape 5 et la frontière de l'étape 6. Rouge de Node, ERR_MODULE_NOT_FOUND, deux fois : les étapes 3 et 4. Et le rouge du script, « el control NO arrancó », à l'étape 4. Si à l'étape 3 npm run build affiche TS2307, la ligne de sed n'a pas trouvé "outDir": "./dist", dans tsconfig.json : vérifie que tu ne l'as pas modifié. Si à l'étape 5 l'erreur persiste, vérifie que main.ts dit "#revisar".
Pour aller plus loin (facultatif) : l'alias que voulait Iván existe presque. Depuis Node 24.14, un nom peut commencer par #/ [4], et TypeScript le comprend depuis la version 6 [9]. Lance npm pkg set 'imports.#/*=./dist/*.js', change l'import de main.ts en "#/revisar" et recompile. Avant, prédis : est-ce que ça démarre ? Réponse : oui, revisor 0.1.0 (mesuré). Remets tout comme à l'étape 6 : git diff -- package.json src/main.ts pour voir les deux changements, et git restore package.json src/main.ts.
À retenir
Trois questions à poser à ton dépôt cette semaine.
- Ton
tsconfig.jsona-t-ilpaths? Si oui, quel outil résout ces noms quand le programme tourne ? Si la réponse est « aucun », tu sais déjà ce qui va se passer. - Qu'y a-t-il dans ton
dist/? Si tu y trouves un fichier de test, ton code et tes tests se compilent comme un seul programme. - Un de tes tests démarre-t-il le programme compilé, comme le démarrerait le serveur ? Si aucun, qui découvre en premier un import que Node ne trouve pas ?
Et ensuite ?
En Go, la frontière est surveillée par l'outil ; en Python, par l'installation ; en Rust, par le compilateur ; en TypeScript, par Node au démarrage. En Java, les frontières ne sont plus des fichiers : ce sont des couches.
Un mois plus tard, Iván eut sa première API en Java, avec Spring Boot. Quatre dossiers avec des noms de couche : api, facade, service, repository. Son changement, c'était un nouveau champ dans une réponse.
Il toucha quatre fichiers pour déplacer une donnée.
Dans la facade, il y avait une méthode qui ne faisait qu'en appeler une autre. À quoi sert une couche qui ne fait rien ? Dans l'épisode 5 : une API en couches, ce que chacune peut savoir des autres, et quand la facade est nécessaire et quand elle ne l'est pas.
Le modèle et le cours
- Modèle : github.com/HabilMX/estructura-typescript. Il s'utilise comme modèle GitHub ou se clone [21]. Le README explique chaque dossier et chaque
tsconfig, ce qu'il n'inclut pas, quand ajouter chaque chose et comment retirer l'exemple. Le code est sous MIT ; le texte et les explications, sous CC BY-SA 4.0. - Versions : Node 26.13 ou plus récent. La 26 est la ligne LTS la plus récente [16]. Dans
engines,package.jsondéclare le minimum que le modèle prend en charge : la 26.13.0, première LTS de cette ligne. C'est un minimum, pas la liste de ce qui a été testé. TypeScript 7.0.2, la version en vigueur le 17 novembre [17], figée danspackage-lock.json, quenpm cirespecte sans le modifier [13][14]. Il a été testé avec Node 26.13.1 et 26.13.0 sur macOS arm64 (aussi avec le/bin/bashdu système) et sur Linux arm64 (conteneurubuntu:24.04). Linux x86-64 n'a pas encore été testé. Avec Node 24.22.0, il a aussi tourné, avec un avertissementEBADENGINEdenpm(mesuré) :enginesprévient, il n'empêche pas [15]. La CI est écrite pour la LTS de chaque semaine et la 26.13.0 sous Linux, et la LTS sous macOS [23]. - Cours de TypeScript de Hábil : si les modules,
tsconfig.jsonou les tests avec Node sont nouveaux pour toi, la leçon 7 les présente depuis zéro : Cours de TypeScript · Leçon 7, Modules, tests et qualité.
J'écris à partir de ce que nous voyons tous les jours chez Hábil, où nous construisons des systèmes pour la banque, l'assurance et les entreprises au Mexique. Si, au travail ou à l'école, ton équipe tombe sur un dépôt que personne ne sait par où prendre, parlons-en : habil.mx
Que fait Hábil ?
Nous enseignons la programmation avec ce que nous utilisons pour construire : du code testé, expliqué et ouvert.
Cette série naît du même endroit que nos cours. Le Cours de TypeScript part de ce que les types n'existent plus à l'exécution : il enseigne ce qu'ils protègent, ce qu'ils ne protègent pas et comment valider les données venues de l'extérieur, et nous le publions en accès ouvert, sous licence Creative Commons ; sa leçon 7 présente les modules, les tests et la qualité qu'utilise le modèle de cet article. Et le catalogue compte d'autres cours de programmation, gratuits, avec du code testé et expliqué pas à pas.
Découvre le Cours de TypeScript et le catalogue des Cours de programmation.
Si ton équipe hérite d'un système que personne ne sait par où prendre, ou doit en construire un qui puisse continuer à être maintenu, nous le faisons aussi : découvre Construire votre système sur mesure. Demande ton premier échange, sans frais. Nous y examinons s'il vaut mieux configurer ce que ton équipe a déjà, utiliser un produit ou construire, et ce qu'elle recevrait dans chaque cas. Écris-nous sur WhatsApp.
Sources consultées le 17 novembre 2026. Les citations en anglais sont reproduites telles quelles.
Références
- TypeScript, « Modules - Reference » : « paths », « paths does not affect emit », « package.json "imports" and self-name imports » et « Implied and enforced options », The TypeScript Handbook. https://www.typescriptlang.org/docs/handbook/modules/reference.html
- TypeScript, « TSConfig Reference » :
pathsetextends. https://www.typescriptlang.org/tsconfig/ - Node.js v26.13.1, « Modules: TypeScript » : « Type stripping » et « Paths aliases ». https://nodejs.org/api/typescript.html
- Node.js v26.13.1, « Modules: Packages » : « Subpath imports ». https://nodejs.org/api/packages.html
- TypeScript, « Modules - Theory » : « Module specifiers are not transformed by default » et « Module resolution », The TypeScript Handbook. https://www.typescriptlang.org/docs/handbook/modules/theory.html
- Node.js v26.13.1, « Modules: ECMAScript modules » : « Mandatory file extensions ». https://nodejs.org/api/esm.html
- TypeScript, « Modules - Choosing Compiler Options », The TypeScript Handbook. https://www.typescriptlang.org/docs/handbook/modules/guides/choosing-compiler-options.html
- TypeScript, « Project References », The TypeScript Handbook. https://www.typescriptlang.org/docs/handbook/project-references.html
- TypeScript, « TypeScript 6.0 » (notes de version) : « rootDir now defaults to . », « types now defaults to [] », « Deprecated: --baseUrl » et « Subpath Imports Starting with #/ ». https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html
- Daniel Rosenwasser, « Announcing TypeScript 7.0 », TypeScript Blog (Microsoft), 8 juillet 2026. https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/
- Node.js v26.13.1, « Test runner » : « Running tests from the command line ». https://nodejs.org/api/test.html
- Node.js v26.13.1, « Errors » :
ERR_MODULE_NOT_FOUND. https://nodejs.org/api/errors.html - npm Docs, « npm-ci ». https://docs.npmjs.com/cli/v11/commands/npm-ci
- npm Docs, « package-lock.json ». https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json
- npm Docs, « package.json » :
engines. https://docs.npmjs.com/cli/v11/configuring-npm/package-json - Node.js, « Node.js Releases ». https://nodejs.org/en/about/previous-releases
- npm, registre du paquet
typescript, versionlatest: 7.0.2. https://registry.npmjs.org/typescript/latest - Launchpad (Canonical), paquet
nodejspublié dans Ubuntu 24.04 « noble » : 18.19.1. https://api.launchpad.net/1.0/ubuntu/+archive/primary?ws.op=getPublishedSources&source_name=nodejs&exact_match=true&distro_series=https://api.launchpad.net/1.0/ubuntu/noble - Linux Mint, « Linux Mint 22 Release Notes » (« Linux Mint 22.x is based on Ubuntu 24.04 »), linuxmint.com. https://www.linuxmint.com/rel_wilma.php
- nvm-sh, « Node Version Manager », README : « Install & Update Script », GitHub. https://github.com/nvm-sh/nvm
- GitHub Docs, « Creating a template repository ». https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository
- GitHub Docs, « Disabling and enabling a workflow ». https://docs.github.com/en/actions/how-tos/manage-workflow-runs/disable-and-enable-workflows
- GitHub Actions, « actions/setup-node », README, GitHub. https://github.com/actions/setup-node
- TypeScript, « TSConfig Option: rewriteRelativeImportExtensions ». https://www.typescriptlang.org/tsconfig/rewriteRelativeImportExtensions.html
- Git, « git-restore » (« Restore specified paths in the working tree »). https://git-scm.com/docs/git-restore
Votre activité fait face à ces défis ?
Vous préférez l'e-mail ? Écrivez-nous à hola@habil.mx