La estructura de un proyecto (4): el import que compila y no arranca
Por Dorian Chávez · cofundador y Chief Executive Officer de Hábil ·
Su alias de tsconfig.json compila y Node no arranca, porque no lee ese archivo. Qué decide tsconfig, qué decide package.json y una plantilla que lo comprueba.
La estructura de un proyecto · entrega 4 de 7 · TypeScript
Escenario: los personajes y la historia son inventados. Los datos técnicos y las citas llevan su fuente al final.
En 1 minuto
paths, la opción detsconfig.jsonpara los alias, no cambia lo que el compilador escribe. El alias sale tal cual en el JavaScript, y Node no sabe qué es [1][2].- Node no lee
tsconfig.json. Para ponerle nombre a un módulo, lee el campo"imports"depackage.json, y ese campo también lo entiende TypeScript [1][3][4]. tsconfig.jsondecide cómo TypeScript revisa el programa y cómo lo emite (emitir: escribir los archivos dedist/). No configura al Node que lo ejecuta [3].- Las pruebas y el código se compilan aparte, con un
tsconfigcada uno: asídist/no lleva pruebas y el código no puede apoyarse en ellas [7][8]. - Te llevas una plantilla que se clona y corre a la primera, con un guion que demuestra esa frontera poniéndose rojo cuando debe.
- Para el lunes: busca
pathsen tutsconfig.jsony pregunta quién resuelve esos nombres cuando el programa corre.
En este artículo
- ¿Qué pasó el martes a las 17:48?
- ¿Qué decide tsconfig.json, y qué no?
- ¿Cuáles son cinco errores frecuentes?
- Ejercicio: ¿puedes hacer que compile y no arranque?
- Para llevar
- ¿Qué sigue?
- La plantilla y el curso
- ¿Qué hace Hábil?
- Referencias
¿Qué pasó el martes a las 17:48?
Iván escribió un import que el compilador aceptó y que Node, al arrancar, no encontró.
Martes, 17:05. Piso tres.
Cuarto encargo, primero en TypeScript. El revisor otra vez, el de Go, Python y Rust, que consulta servicios por HTTP. Esta vez vivía dentro de una API, y el pedido era corto: «Que la revisión se pueda pedir también desde main».
El proyecto lo había dejado alguien más. Tenía buena cara:
src/
main.ts
revisar.ts
reporte.ts
package.json
tsconfig.jsonEn tsconfig.json, Iván encontró un renglón que le gustó:
"paths": { "@/*": ["./src/*.ts"] }Un alias. Con eso podía escribir @/revisar en lugar de contar puntos y diagonales. Lo usó en src/main.ts:
import { revisarTodos } from "@/revisar";El editor le autocompletó el nombre de la función. Compiló:
$ npx tsc -p tsconfig.build.json
$Nada. Ni un error, ni un aviso. Subió el cambio.
Martes, 17:48.
El servidor de pruebas arrancó la versión nueva con node dist/main.js. La respuesta (recortada; la ruta cambia en cada máquina):
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@/revisar' imported from …/dist/main.js¿Un paquete? Iván no había instalado ningún paquete. revisar era un archivo suyo, estaba ahí, y el compilador lo había encontrado. Abrió dist/main.js para ver qué había escrito tsc:
import { revisarTodos } from "@/revisar";Su línea, idéntica. El compilador había quitado los tipos y había dejado el alias como estaba.
A las 17:56 le escribió a Lucía, la líder técnica.
—Compila y no arranca. Dice que no encuentra @/revisar.
—¿Quién sabe dónde queda @? —contestó ella.
—El tsconfig.
—¿Y quién arranca el programa?
Iván miró el comando. node dist/main.js. En esa línea no había ningún tsconfig.
—Node.
—Node no lee ese archivo. Mañana te enseño cuál sí lee.
Iván volvió a mirar el renglón del alias. El compilador le había dado la razón. Pero el compilador no era quien iba a correr el programa.
¿Qué decide tsconfig.json, y qué no?
Decide cómo TypeScript revisa y emite el programa. No configura al Node que lo ejecuta: Node resuelve los imports al arrancar con sus propias reglas, y para un nombre con # lee package.json.
La documentación de TypeScript lo dice de paths sin rodeos, en un apartado que se llama «paths does not affect emit»: la opción no cambia la ruta del import en el código que TypeScript escribe, y por eso «it’s very easy to create path aliases that appear to work in TypeScript but will crash at runtime» [1]. Es muy fácil crear un alias que parece funcionar y truena al correr. La referencia de tsconfig dice para qué sirve entonces: para avisarle a TypeScript «that another tool has this mapping and will use it at runtime or when bundling» [2]. Que otra herramienta ya tiene ese mapa.
En el proyecto de Iván no había otra herramienta. Había Node, y la documentación de Node cierra la pinza: «Node.js ignores tsconfig.json files» [3].
Las dos documentaciones señalan la misma salida. La de TypeScript dice que el campo "imports" de package.json es «a standard replacement for convenience paths aliases» [1]. La de Node, que lo más parecido a paths son los subpath imports (nombres internos de un paquete, declarados en su package.json), «with the limitation that they need to start with #» [3].
La plantilla de esta entrega, estructura-typescript, está hecha así:
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.mdTrae el revisor como línea de comandos, sin el servidor de la API de Iván: la frontera es la misma, y sobra menos. Vamos parte por parte, con la pregunta de siempre: ¿qué problema resuelve hoy?
¿Quién lee cada archivo?
tsconfig.json lo leen el compilador y el editor. package.json lo leen los dos, y también Node.
Ésa es toda la frontera, y cabe en una tabla:
| Archivo | Lo lee tsc (y el editor) | Lo lee Node al arrancar |
|---|---|---|
tsconfig.json | Sí | No [3] |
package.json | Sí [1] | Sí [4] |
Lo que quieras que valga en los dos momentos, al compilar y al correr, tiene que estar en el archivo que leen los dos.
¿Qué sí decide tsconfig.json?
Cómo revisa TypeScript y cómo emite. La emisión son los archivos que tsc escribe. La base de la plantilla toma seis decisiones, y ninguna llega hasta Node.
{
"compilerOptions": {
"target": "es2024",
"module": "nodenext",
"strict": true,
"types": ["node"],
"rootDir": "./src",
"outDir": "./dist",
"noEmit": true
},
"include": ["src"]
}- De la revisión:
strict, ytypes, que dice qué tipos globales existen. Desde TypeScript 6 esa lista nace vacía [9]; sin"node",processno existe:error TS2591: Cannot find name 'process'(medido). - De emisión:
target(qué JavaScript sale), yrootDirconoutDir(de dónde sale y a dónde va). - De las dos:
module: nodenext. Hace que TypeScript siga las reglas de módulos de Node al revisar y al emitir. Al revisar, busca cada import como lo buscaría Node [5]: esa opción trae consigomoduleResolution: nodenext[1]. Al emitir, decide si cada archivo sale como módulo ECMAScript o como CommonJS [1]. Lo que no hace es instalar ni configurar nada en el Node que va a correr el programa.
noEmit: true hace que este archivo solo revise. Es el que abre el editor para src/.
Hay más opciones (lib, jsx, declaration, sourceMap), y todas hacen lo mismo: cambian la compilación. Ninguna cambia cómo arranca Node.
Entonces, ¿cómo se llama un módulo?
Si quieres un alias privado que funcione en Node sin cargador ni empaquetador: con un nombre que empiece con #, declarado en "imports" de package.json. Para archivos vecinos, la ruta relativa con .js sigue siendo lo más simple.
Node los llama subpath imports, nombres internos de un paquete: un campo para crear «private mappings that only apply to import specifiers from within the package itself» [4]. Un specifier, o especificador, es el texto entre comillas de un import. Privados: solo valen dentro de tu paquete. Y con una regla de forma: «Entries in the "imports" field must always start with #» [4], para no confundirse con paquetes de fuera.
En la plantilla son cuatro renglones:
"imports": {
"#config": "./dist/config.js",
"#reporte": "./dist/reporte.js",
"#revisar": "./dist/revisar.js",
"#servicio": "./dist/servicio.js"
}Y main.ts escribe import { revisarTodos } from "#revisar". Node lee el campo y carga dist/revisar.js.
¿Y TypeScript? Lee el mismo campo y llega al mismo archivo. Pero dist/revisar.js todavía no existe cuando compilas por primera vez. La documentación explica el paso extra: si el package.json es del proyecto que se está compilando, TypeScript busca el archivo fuente que va a producir esa salida, y para eso usa outDir y rootDir, «so using "imports" usually requires an explicit rootDir to be set» [1]. Por eso la base los declara. Medido: en un clon recién hecho, sin dist/, la plantilla compila a la primera.
Un solo nombre, declarado una sola vez, que significa lo mismo al compilar y al correr. No es la única forma de importar que entienden los dos: también las rutas relativas, que vienen enseguida, y los paquetes instalados. Es la que sirve cuando quieres un alias.
¿Por qué ./servicio.js, si el archivo se llama servicio.ts?
Porque entre comillas se escribe lo que Node va a cargar, y en esta plantilla TypeScript lo deja tal cual.
Entre módulos vecinos, la plantilla usa rutas relativas: import { clasificar } from "./servicio.js". La extensión desconcierta la primera vez. La regla viene de Node: en un import, «A file extension must be provided» [6]. Y de TypeScript, que explica que el especificador «is emitted as-written» [5]: sale como lo escribiste. Si Node va a cargar servicio.js, eso escribes.
Eso es lo que pasa aquí, no una ley. TypeScript tiene una opción, rewriteRelativeImportExtensions, que cambia un .ts relativo por .js en lo que emite [24]. La plantilla no la activa, así que el especificador sale intacto.
Es la misma regla del alias, vista desde otro lado. Con module: nodenext, TypeScript sí te avisa de ésta. Medido, quitando la extensión:
error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './servicio.js'?Del alias no avisa, porque paths existe justo para decirle «confía, alguien más lo resuelve».
¿Por qué las pruebas se compilan aparte?
Porque un tsconfig describe un solo programa, y el código y sus pruebas son dos: uno se entrega y el otro no.
La guía de TypeScript lo dice así: «A single tsconfig.json can only represent a single environment» [7], y pone el código de pruebas en la lista de lo que merece el suyo. Su página de project references cuenta qué pasaba con un solo archivo para src/ y test/: «It was possible for the implementation files to import the test files», y no se podían compilar juntos «without having src appear in the output folder name» [8].
Lo medimos en un proyecto de tres archivos, con "include": ["src", "test"]:
- Con
rootDir: ./src, no compila:error TS6059: File '…/test/reporte.test.ts' is not under 'rootDir'. - Sin
rootDir, compila, pero la salida cambia de forma:dist/src/main.jsydist/test/reporte.test.js. Las pruebas viajan en lo que se entrega, ynode dist/main.jscontestaError: Cannot find module '…/dist/main.js'. - Y
main.tsimportó un archivo detest/sin que nadie se quejara. Compiló y corrió.
La plantilla lo parte en tres archivos, cada uno con un trabajo:
| Archivo | Qué incluye | Qué hace |
|---|---|---|
tsconfig.json | src/ | La base: revisa, no escribe |
tsconfig.build.json | lo mismo (hereda con extends [2]) | Escribe dist/: los .js y sus .d.ts (archivos que describen tipos y no ejecutan código) |
test/tsconfig.json | test/ | Revisa las pruebas; nunca escribe |
Lo fino está en el tercero. Las pruebas importan #reporte, igual que main.ts. Pero ese tsconfig vive en otra carpeta y no incluye src/, así que TypeScript llega a dist/reporte.d.ts, el archivo de tipos que dejó la construcción. Medido: en el programa de las pruebas no entra un solo archivo de src/. Las pruebas ven lo que ve cualquiera que use lo compilado.
Tiene un costo, y la misma página lo dice: con varios tsconfig sueltos «you end up always running tsc twice» [8]. Para eso existen las project references. Con cinco archivos, correr dos veces no se nota; el README dice cuándo dar ese paso.
¿Cómo corren las pruebas?
Node las corre directo desde los .ts, quitándoles los tipos; y cargan el código ya compilado, por la misma puerta #.
Node ejecuta archivos de TypeScript que solo lleven sintaxis borrable: borra las anotaciones de tipos, pero no transforma el TypeScript que necesitaría generar JavaScript nuevo. Cambia los tipos por espacios en blanco, y «no type checking is performed» [3]. La plantilla lo usa para las pruebas, con el ejecutor que Node ya trae (node --test), sin instalar nada más. Como Node carga esos archivos tal cual, ahí los imports relativos llevan .ts: ./comun/servidor.ts. La regla no cambió: escribes lo que Node va a cargar.
npm test hace tres cosas: construye dist/, revisa los tipos de las pruebas y las corre. El informe cierra así:
ℹ tests 46
ℹ pass 46
ℹ fail 0
ℹ cancelled 0Son 46 pruebas, y se cuentan ahí. Con un patrón que no encuentra ningún archivo, node --test sale con 0 y ℹ tests 0 (medido): un verde que no probó nada.
El patrón del script, "test/**/*.test.ts", tampoco sobra. Por omisión, Node corre todo archivo que esté bajo una carpeta test/ [11]. Medido sin el patrón: el servidor de ayuda sale como una prueba más, ✔ test/comun/servidor.ts, y el informe dice 47.
Una de las pruebas, programa.test.ts, ejecuta dist/main.js en otro proceso. Es la única que ve lo que ninguna revisión de tipos ve: si Node encuentra cada módulo al arrancar.
¿Qué cuida el revisor que una plantilla no debe enseñar mal?
Un tiempo límite que cubre toda la consulta, un tope para lo que se lee y errores que nunca repiten la URL.
Lo que llega de servicios.json es unknown hasta que se revisa campo por campo: los tipos no vigilan lo que entra al correr. El cuerpo de cada respuesta se lee hasta 64 KiB y se suelta. Ningún mensaje repite una URL, que puede traer un token. Quitamos cada protección en una copia, una por una: las 26 pusieron en rojo su prueba.
¿Y dónde va el import de Iván?
En main.ts, con el nombre #revisar; y el nombre, en package.json.
El miércoles, Iván y Lucía borraron el renglón de paths. Declararon #revisar en "imports" y cambiaron una línea de main.ts. El editor siguió autocompletando. Y esta vez, lo que el compilador aceptaba era lo mismo que Node iba a buscar.
¿Cómo sé que la frontera existe?
Porque un guion la cruza a propósito en cada cambio: siembra el alias y exige que compile y que no arranque, por la razón exacta.
herramientas/probar-frontera.sh trabaja en una copia temporal. Compila y arranca el mismo programa dos veces. Entre las dos solo cambia cómo importa main.ts el módulo revisar, y quién declara ese nombre:
- Control, con el proyecto tal como está.
main.tsimporta#revisar. Tiene que compilar y arrancar. Si no, el experimento está mal montado, o tu proyecto ya trae un import que Node no resuelve, y el guion se detiene en rojo. - Violación. Se siembra
@/revisarenpathsymain.tslo importa. Tiene que compilar, con el alias intacto endist/main.js, y tiene que no arrancar, conERR_MODULE_NOT_FOUND.
Ésta es la salida real:
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 sostiene¿Por qué el control? Porque un experimento que solo espera un rojo se pone «verde» también cuando falla por la razón equivocada. Lo rompimos de siete maneras, y las siete salieron en rojo. Tres dicen mucho: con un cargador que sí resuelve el alias, ❌ ARRANCÓ; con un alias que tsc rechaza, dice que la violación no compiló y que eso «no demuestra la frontera»; con el alias sembrado en el proyecto real, se detiene en el control.
El CI de GitHub está escrito para correr los tipos, las pruebas y la frontera con la LTS más reciente de Node y con la 26.13.0, y la frontera también en macOS con el /bin/bash del sistema, en cada cambio y cada lunes. Si el repositorio público pasa 60 días sin actividad, GitHub apaga la corrida de los lunes [22].
¿Cuáles son cinco errores frecuentes?
Los cinco salen de lo mismo: creer que tsconfig.json manda donde no manda.
1. Un alias en paths que nadie resuelve al correr
Compila, el editor lo acepta, y Node no arranca.
Es el error de Iván [1][2]. paths no es un error en sí: sirve cuando un empaquetador resuelve el alias y solo hay que avisarle a TypeScript [1]. Lo que falla es usarlo solo. Lo delata ERR_MODULE_NOT_FOUND, el error de Node para un módulo que no pudo resolver [12], con Cannot find package: Node creyó que @/revisar era un paquete instalado. Para un alias privado, sin cargador ni empaquetador, la salida estándar es "imports" [1][3].
2. Rutas relativas sin extensión, con una resolución que las perdona
Con moduleResolution: bundler, TypeScript acepta ./servicio a secas; Node, no.
bundler le dice a TypeScript que un empaquetador va a resolver los imports. La guía avisa que esa opción «is infectious, allowing code that only works in bundlers to be produced» [7]. Medido en la plantilla, con bundler y un import sin extensión: compila, y al arrancar:
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '…/dist/servicio' imported from …/dist/revisar.jsSi tu programa corre en Node tal como sale de tsc, la opción es nodenext, que revisa con las reglas de Node [5][6].
3. Un solo tsconfig.json para el código y las pruebas
O las pruebas viajan en dist/, o el programa cambia de lugar, o el código acaba importando una prueba.
Son los tres síntomas medidos arriba [8]. Desde TypeScript 6, rootDir ya no se adivina: es la carpeta del tsconfig, y las notas de esa versión describen el síntoma tal cual: «files being written to ./dist/src/index.js instead of ./dist/index.js» [9]. La salida es un tsconfig por programa [7].
4. Copiar el tsconfig.json de un tutorial viejo
TypeScript 7 retiró opciones que miles de tutoriales todavía enseñan.
TypeScript 7 salió el 8 de julio de 2026 [10]. Es un compilador nuevo, y lo que la versión 6 marcaba como obsoleto ahora es un error. El anuncio lo dice de las dos opciones más copiadas: «baseUrl is no longer supported», y lo mismo de moduleResolution: node [10]. Medido con 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 era la pareja de siempre de paths. Si tu alias dependía de las dos, la mitad ya no existe. Antes de copiar un tsconfig, mira de qué año es.
5. Creer que si Node lo corrió, los tipos están bien
Node quita los tipos. No los revisa.
Que Node ejecute .ts no lo vuelve un compilador [3]. Medido con un archivo de dos líneas, const limite: number = "cinco"; y un console.log: Node imprime cinco y sale con 0. tsc, con el mismo archivo:
error TS2322: Type 'string' is not assignable to type 'number'.Son dos herramientas con dos trabajos. Por eso npm test revisa los tipos antes de correr las pruebas.
| Error | Lo que lo delata | Fuente |
|---|---|---|
1. Alias en paths sin quien lo resuelva | ERR_MODULE_NOT_FOUND: Cannot find package '@/…' al arrancar | [1][2][3] |
2. Sin extensión, con bundler | Cannot find module '…/dist/servicio' al arrancar | [5][6][7] |
3. Un tsconfig para todo | dist/src/main.js, pruebas en dist/, o TS6059 | [7][8][9] |
4. Un tsconfig de tutorial viejo | TS5102, TS5108 | [9][10] |
| 5. «Node lo corrió» | Un verde de Node con un rojo de tsc | [3] |
Ejercicio: ¿puedes hacer que compile y no arranque?
Vas a sembrar el alias de Iván, ver que el compilador lo acepta, intentar arreglarlo donde parece lógico y ver cómo el guion te avisa.
Necesitas Node 26.13 o más nuevo (node --version), que ya trae npm, más Git y bash; unos 20 minutos.
- En Linux Mint 22, no uses
apt install nodejs: Mint 22 se basa en Ubuntu 24.04 [19], que trae Node 18.19 [18], y con él las pruebas no corren:Could not find '…/test/**/*.test.ts'(medido). Instala Node connvm, como dice su README [20]:
sudo apt install curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.0/install.sh | bashAbre otra terminal (en la misma, nvm todavía no se encuentra; medido) y corre nvm install 26. La lección 1 del curso de TypeScript lo cuenta paso a paso. - En macOS, lo mismo, con nvm. - Si ya tienes nvm, nvm install 26. En Windows, usa WSL.
Paso 1. Clona y comprueba que todo está en verde.
git clone https://github.com/HabilMX/estructura-typescript
cd estructura-typescript
npm ci
npm test
bash herramientas/probar-frontera.shLo que debes ver: ℹ pass 46 con ℹ fail 0 y, al final del guion, ✅ frontera: se sostiene.
Usa este clon solo para practicar. Así, todo cambio que veas en él es del ejercicio.
Paso 2. Predice antes de tocar. Vas a declarar el alias @/revisar en tsconfig.json y a usarlo en main.ts. Anota tres cosas: ¿compila? ¿Arranca? ¿Y si además declaras @/revisar en package.json?
Paso 3. Siembra el alias. Estas dos líneas sirven igual en Linux y en macOS; dejan una copia .bak de cada archivo.
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 termina sin un solo error. node no arranca. La línea que importa:
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@/revisar' imported from …/dist/main.jsPaso 4. Arréglalo donde parece lógico. Si Node lee package.json, declara ahí el mismo nombre:
npm pkg set 'imports.@/revisar=./dist/revisar.js'
npm run build
node dist/main.js --version
bash herramientas/probar-frontera.shEl mismo ERR_MODULE_NOT_FOUND. Node solo busca en "imports" los nombres que empiezan con #; a los demás los trata como paquetes. Y el guion se pone rojo, sin llegar al segundo paso:
❌ el control NO arrancó: el programa, tal como está, no corre con node:Ése es el control trabajando: tu proyecto ya trae un import que Node no resuelve.
Paso 5. Dale el nombre que Node sí busca.
sed -i.bak 's|from "@/revisar"|from "#revisar"|' src/main.ts
npm run build
node dist/main.js --versionContesta revisor 0.1.0. El renglón de paths sigue en tsconfig.json, y no hizo falta: ya nadie lo usa.
Paso 6. Regresa solo lo que tocaste. El ejercicio cambió tres archivos. Antes de regresarlos, mira qué cambió en ellos:
git diff -- tsconfig.json src/main.ts package.jsonDebes ver dos cambios: el renglón de paths en tsconfig.json y el renglón "@/revisar" en package.json. src/main.ts no aparece: en el paso 5 quedó como estaba. Si ves algo más, es tuyo: guárdalo antes de seguir.
Si solo está lo del ejercicio, regresa esos tres archivos. git restore solo toca las rutas que le das [25]:
git restore tsconfig.json src/main.ts package.json
bash herramientas/probar-frontera.sh
git status --shortLa frontera vuelve a verde, y git status enseña lo único que queda: las copias que hizo sed.
?? src/main.ts.bak
?? tsconfig.json.bakConsérvalas hasta que estés seguro de que no las necesitas. Luego bórralas una por una, con rm -i src/main.ts.bak tsconfig.json.bak, que pregunta antes de cada una. No uses un comando que limpie toda la carpeta: se llevaría también tus notas.
Cómo sabes que lo hiciste bien: corriste siete veces y viste tres desenlaces. Verde, cuatro veces: las dos del paso 1, el programa en el paso 5 y la frontera del paso 6. Rojo de Node, ERR_MODULE_NOT_FOUND, dos veces: los pasos 3 y 4. Y el rojo del guion, «el control NO arrancó», en el paso 4. Si en el paso 3 npm run build marca TS2307, la línea de sed no encontró "outDir": "./dist", en tsconfig.json: revisa que no lo hayas editado. Si en el paso 5 sigue el error, revisa que main.ts diga "#revisar".
Para ir más lejos (opcional): el alias que Iván quería casi existe. Desde Node 24.14, un nombre puede empezar con #/ [4], y TypeScript lo entiende desde la versión 6 [9]. Corre npm pkg set 'imports.#/*=./dist/*.js', cambia el import de main.ts a "#/revisar" y vuelve a compilar. Antes, predice: ¿arranca? Respuesta: sí, revisor 0.1.0 (medido). Regresa igual que en el paso 6: git diff -- package.json src/main.ts para ver los dos cambios, y git restore package.json src/main.ts.
Para llevar
Tres preguntas para hacerle a tu repositorio esta semana.
- ¿Tu
tsconfig.jsontienepaths? Si sí, ¿qué herramienta resuelve esos nombres cuando el programa corre? Si la respuesta es «ninguna», ya sabes qué va a pasar. - ¿Qué hay dentro de tu
dist/? Si encuentras un archivo de pruebas, tu código y tus pruebas se están compilando como un solo programa. - ¿Alguna prueba arranca el programa compilado, como lo arrancaría el servidor? Si ninguna, ¿quién se entera primero de un import que Node no encuentra?
¿Qué sigue?
En Go, la frontera la vigila la herramienta; en Python, la instalación; en Rust, el compilador; en TypeScript, Node al arrancar. En Java, las fronteras ya no son archivos: son capas.
Un mes después, a Iván le tocó su primera API en Java, con Spring Boot. Cuatro carpetas con nombre de capa: api, facade, service, repository. Su cambio era un campo nuevo en una respuesta.
Tocó cuatro archivos para mover un dato.
En la facade había un método que solo llamaba a otro. ¿Para qué una capa que no hace nada? En la entrega 5: una API por capas, qué puede saber cada una de las demás, y cuándo sí y cuándo no hace falta la facade.
La plantilla y el curso
- Plantilla: github.com/HabilMX/estructura-typescript. Se usa como plantilla de GitHub o se clona [21]. El README explica cada carpeta y cada
tsconfig, lo que no trae, cuándo agregar cada cosa y cómo quitar el ejemplo. El código es MIT; el texto y las explicaciones son CC BY-SA 4.0. - Versiones: Node 26.13 o más nuevo. La 26 es la línea LTS más reciente [16]. En
engines,package.jsondeclara el mínimo que la plantilla soporta: la 26.13.0, primera LTS de esa línea. Es un mínimo, no la lista de lo probado. TypeScript 7.0.2, la vigente el 17 de noviembre [17], fija enpackage-lock.json, quenpm cirespeta sin modificarlo [13][14]. Se probó con Node 26.13.1 y 26.13.0 en macOS arm64 (también con el/bin/bashdel sistema) y en Linux arm64 (contenedorubuntu:24.04). Linux x86-64 todavía no se ha probado. Con Node 24.22.0 también corrió, con un avisoEBADENGINEdenpm(medido):enginesavisa, no impide [15]. El CI está escrito para la LTS de cada semana y la 26.13.0 en Linux, y la LTS en macOS [23]. - Curso de TypeScript de Hábil: si los módulos,
tsconfig.jsono las pruebas con Node son nuevos para ti, la lección 7 los cuenta desde cero: Curso de TypeScript · Lección 7, Módulos, pruebas y calidad.
Escribo desde lo que vemos todos los días en Hábil, donde construimos sistemas para banca, seguros y empresas en México. Si en tu trabajo o en tu escuela se topan con un repositorio que nadie sabe dónde tocar, platiquemos: habil.mx
¿Qué hace Hábil?
Enseñamos a programar con lo mismo que usamos para construir: código probado, explicado y abierto.
Esta serie nace del mismo lugar que nuestros cursos. El Curso de TypeScript parte de que los tipos no existen al ejecutar: enseña qué protegen, qué no y cómo validar los datos que llegan de fuera, y lo publicamos abierto, con licencia Creative Commons; su lección 7 cuenta los módulos, las pruebas y la calidad que usa la plantilla de este artículo. Y en el catálogo hay más cursos de programación, gratuitos y con código probado y explicado paso a paso.
Mira el Curso de TypeScript y el catálogo de Cursos de programación.
Si tu equipo hereda un sistema que nadie sabe dónde tocar, o necesita construir uno que se pueda seguir manteniendo, también lo hacemos: mira Construir su sistema a la medida. Pide tu primera conversación, sin costo. En ella revisamos si conviene configurar lo que ya tienen, usar un producto o construir, y qué recibirían en cada caso. Escríbenos por WhatsApp.
Fuentes consultadas el 17 de noviembre de 2026. Las citas en inglés se reproducen tal cual.
Referencias
- TypeScript, «Modules - Reference»: «paths», «paths does not affect emit», «package.json "imports" and self-name imports» e «Implied and enforced options», The TypeScript Handbook. https://www.typescriptlang.org/docs/handbook/modules/reference.html
- TypeScript, «TSConfig Reference»:
pathsyextends. https://www.typescriptlang.org/tsconfig/ - Node.js v26.13.1, «Modules: TypeScript»: «Type stripping» y «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» y «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» (notas de la versión): «rootDir now defaults to .», «types now defaults to []», «Deprecated: --baseUrl» y «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 de julio de 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, registro del paquete
typescript, versiónlatest: 7.0.2. https://registry.npmjs.org/typescript/latest - Launchpad (Canonical), paquete
nodejspublicado en 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
¿Su operación tiene estos desafíos?
¿Prefiere correo? Escríbanos a hola@habil.mx