Saltar al contenido
Arquitectura y backend18 min

La estructura de un proyecto (4): el import que compila y no arranca

Por · 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 de tsconfig.json para 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" de package.json, y ese campo también lo entiende TypeScript [1][3][4].
  • tsconfig.json decide cómo TypeScript revisa el programa y cómo lo emite (emitir: escribir los archivos de dist/). No configura al Node que lo ejecuta [3].
  • Las pruebas y el código se compilan aparte, con un tsconfig cada 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 paths en tu tsconfig.json y pregunta quién resuelve esos nombres cuando el programa corre.

En este artículo

  1. ¿Qué pasó el martes a las 17:48?
  2. ¿Qué decide tsconfig.json, y qué no?
  3. ¿Cuáles son cinco errores frecuentes?
  4. Ejercicio: ¿puedes hacer que compile y no arranque?
  5. Para llevar
  6. ¿Qué sigue?
  7. La plantilla y el curso
  8. ¿Qué hace Hábil?
  9. 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.json

En 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.md

Trae 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:

Ésa es toda la frontera, y cabe en una tabla
ArchivoLo lee tsc (y el editor)Lo lee Node al arrancar
tsconfig.jsonSíNo [3]
package.jsonSí [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, y types, que dice qué tipos globales existen. Desde TypeScript 6 esa lista nace vacía [9]; sin "node", process no existe: error TS2591: Cannot find name 'process' (medido).
  • De emisión: target (qué JavaScript sale), y rootDir con outDir (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 consigo moduleResolution: 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.js y dist/test/reporte.test.js. Las pruebas viajan en lo que se entrega, y node dist/main.js contesta Error: Cannot find module '…/dist/main.js'.
  • Y main.ts importó un archivo de test/ sin que nadie se quejara. Compiló y corrió.

La plantilla lo parte en tres archivos, cada uno con un trabajo:

La plantilla lo parte en tres archivos, cada uno con un trabajo
ArchivoQué incluyeQué hace
tsconfig.jsonsrc/La base: revisa, no escribe
tsconfig.build.jsonlo mismo (hereda con extends [2])Escribe dist/: los .js y sus .d.ts (archivos que describen tipos y no ejecutan código)
test/tsconfig.jsontest/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 0

Son 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:

  1. Control, con el proyecto tal como está. main.ts importa #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.
  2. Violación. Se siembra @/revisar en paths y main.ts lo importa. Tiene que compilar, con el alias intacto en dist/main.js, y tiene que no arrancar, con ERR_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.js

Si 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.

5. Creer que si Node lo corrió, los tipos están bien
ErrorLo que lo delataFuente
1. Alias en paths sin quien lo resuelvaERR_MODULE_NOT_FOUND: Cannot find package '@/…' al arrancar[1][2][3]
2. Sin extensión, con bundlerCannot find module '…/dist/servicio' al arrancar[5][6][7]
3. Un tsconfig para tododist/src/main.js, pruebas en dist/, o TS6059[7][8][9]
4. Un tsconfig de tutorial viejoTS5102, 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 con nvm, como dice su README [20]:
  sudo apt install curl
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.0/install.sh | bash

Abre 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.sh

Lo 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 --version

npm 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.js

Paso 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.sh

El 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 --version

Contesta 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.json

Debes 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 --short

La frontera vuelve a verde, y git status enseña lo único que queda: las copias que hizo sed.

?? src/main.ts.bak
?? tsconfig.json.bak

Consé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.

  1. ¿Tu tsconfig.json tiene paths? Si sí, ¿qué herramienta resuelve esos nombres cuando el programa corre? Si la respuesta es «ninguna», ya sabes qué va a pasar.
  2. ¿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.
  3. ¿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.json declara 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 en package-lock.json, que npm ci respeta sin modificarlo [13][14]. Se probó con Node 26.13.1 y 26.13.0 en macOS arm64 (también con el /bin/bash del sistema) y en Linux arm64 (contenedor ubuntu:24.04). Linux x86-64 todavía no se ha probado. Con Node 24.22.0 también corrió, con un aviso EBADENGINE de npm (medido): engines avisa, 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.json o 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

  1. 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
  2. TypeScript, «TSConfig Reference»: paths y extends. https://www.typescriptlang.org/tsconfig/
  3. Node.js v26.13.1, «Modules: TypeScript»: «Type stripping» y «Paths aliases». https://nodejs.org/api/typescript.html
  4. Node.js v26.13.1, «Modules: Packages»: «Subpath imports». https://nodejs.org/api/packages.html
  5. 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
  6. Node.js v26.13.1, «Modules: ECMAScript modules»: «Mandatory file extensions». https://nodejs.org/api/esm.html
  7. TypeScript, «Modules - Choosing Compiler Options», The TypeScript Handbook. https://www.typescriptlang.org/docs/handbook/modules/guides/choosing-compiler-options.html
  8. TypeScript, «Project References», The TypeScript Handbook. https://www.typescriptlang.org/docs/handbook/project-references.html
  9. 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
  10. Daniel Rosenwasser, «Announcing TypeScript 7.0», TypeScript Blog (Microsoft), 8 de julio de 2026. https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/
  11. Node.js v26.13.1, «Test runner»: «Running tests from the command line». https://nodejs.org/api/test.html
  12. Node.js v26.13.1, «Errors»: ERR_MODULE_NOT_FOUND. https://nodejs.org/api/errors.html
  13. npm Docs, «npm-ci». https://docs.npmjs.com/cli/v11/commands/npm-ci
  14. npm Docs, «package-lock.json». https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json
  15. npm Docs, «package.json»: engines. https://docs.npmjs.com/cli/v11/configuring-npm/package-json
  16. Node.js, «Node.js Releases». https://nodejs.org/en/about/previous-releases
  17. npm, registro del paquete typescript, versión latest: 7.0.2. https://registry.npmjs.org/typescript/latest
  18. Launchpad (Canonical), paquete nodejs publicado 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
  19. 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
  20. nvm-sh, «Node Version Manager», README: «Install & Update Script», GitHub. https://github.com/nvm-sh/nvm
  21. GitHub Docs, «Creating a template repository». https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository
  22. GitHub Docs, «Disabling and enabling a workflow». https://docs.github.com/en/actions/how-tos/manage-workflow-runs/disable-and-enable-workflows
  23. GitHub Actions, «actions/setup-node», README, GitHub. https://github.com/actions/setup-node
  24. TypeScript, «TSConfig Option: rewriteRelativeImportExtensions». https://www.typescriptlang.org/tsconfig/rewriteRelativeImportExtensions.html
  25. Git, «git-restore» («Restore specified paths in the working tree»). https://git-scm.com/docs/git-restore