Pular para o conteúdo
Arquitetura e backend18 min

A estrutura de um projeto (4): o import que compila e não inicia

Por · cofundador e Chief Executive Officer da Hábil ·

O alias do tsconfig.json compila e o Node não inicia, porque não lê esse arquivo. O que o tsconfig decide, o que o package.json decide e um template.

A estrutura de um projeto · entrega 4 de 7 · TypeScript

Cenário: os personagens e a história são inventados. Os dados técnicos e as citações levam a fonte no final.

Em 1 minuto

  • paths, a opção do tsconfig.json para os aliases, não muda o que o compilador escreve. O alias sai tal qual no JavaScript, e o Node não sabe o que é [1][2].
  • O Node não lê o tsconfig.json. Para dar nome a um módulo, lê o campo "imports" do package.json, e esse campo o TypeScript também entende [1][3][4].
  • O tsconfig.json decide como o TypeScript verifica o programa e como o emite (emitir: escrever os arquivos de dist/). Não configura o Node que o executa [3].
  • Os testes e o código são compilados à parte, com um tsconfig cada: assim o dist/ não leva testes e o código não pode se apoiar neles [7][8].
  • Daqui sai um template que se clona e roda de primeira, com um script que demonstra essa fronteira ficando vermelho quando deve.
  • Para segunda-feira: procure paths no tsconfig.json do projeto e pergunte quem resolve esses nomes quando o programa roda.

Neste artigo

  1. O que aconteceu na terça às 17:48?
  2. O que o tsconfig.json decide, e o que não?
  3. Quais são cinco erros frequentes?
  4. Exercício: dá para fazer compilar e não iniciar?
  5. Para levar
  6. O que vem depois?
  7. O template e o curso
  8. O que a Hábil faz?
  9. Referências

O que aconteceu na terça às 17:48?

O Iván escreveu um import que o compilador aceitou e que o Node, ao iniciar, não encontrou.

Terça-feira, 17:05. Terceiro andar.

Quarta tarefa, a primeira em TypeScript. O verificador outra vez, o do Go, do Python e do Rust, que consulta serviços por HTTP. Desta vez ele vivia dentro de uma API, e o pedido era curto: «Que a verificação também possa ser pedida a partir de main».

O projeto tinha sido deixado por outra pessoa. Tinha boa cara:

src/
  main.ts
  revisar.ts
  reporte.ts
package.json
tsconfig.json

No tsconfig.json, o Iván encontrou uma linha de que gostou:

"paths": { "@/*": ["./src/*.ts"] }

Um alias. Com isso podia escrever @/revisar em vez de contar pontos e barras. Usou no src/main.ts:

import { revisarTodos } from "@/revisar";

O editor completou o nome da função. Compilou:

$ npx tsc -p tsconfig.build.json
$

Nada. Nem um erro, nem um aviso. Subiu a mudança.

Terça-feira, 17:48.

O servidor de testes iniciou a versão nova com node dist/main.js. A resposta (recortada; o caminho muda em cada máquina):

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@/revisar' imported from …/dist/main.js

Um pacote? O Iván não tinha instalado pacote nenhum. revisar era um arquivo dele, estava ali, e o compilador o tinha encontrado. Abriu o dist/main.js para ver o que o tsc tinha escrito:

import { revisarTodos } from "@/revisar";

A linha dele, idêntica. O compilador tinha tirado os tipos e deixado o alias como estava.

Às 17:56 ele escreveu para a Lucía, a líder técnica.

— Compila e não inicia. Diz que não encontra @/revisar.

— Quem sabe onde fica o @? — respondeu ela.

— O tsconfig.

— E quem inicia o programa?

O Iván olhou o comando. node dist/main.js. Naquela linha não havia nenhum tsconfig.

— O Node.

— O Node não lê esse arquivo. Amanhã mostro qual ele lê.

O Iván voltou a olhar a linha do alias. O compilador tinha dado razão a ele. Mas o compilador não era quem ia rodar o programa.

O que o tsconfig.json decide, e o que não?

Decide como o TypeScript verifica e emite o programa. Não configura o Node que o executa: o Node resolve os imports ao iniciar com as próprias regras, e para um nome com # lê o package.json.

A documentação do TypeScript diz isso de paths sem rodeios, numa seção chamada «paths does not affect emit»: a opção não muda o caminho do import no código que o TypeScript escreve, e por isso «it’s very easy to create path aliases that appear to work in TypeScript but will crash at runtime» [1]. É muito fácil criar um alias que parece funcionar e quebra ao rodar. A referência do tsconfig diz, então, para que serve: para avisar ao TypeScript «that another tool has this mapping and will use it at runtime or when bundling» [2]. Que outra ferramenta já tem esse mapa.

No projeto do Iván não havia outra ferramenta. Havia o Node, e a documentação do Node fecha a pinça: «Node.js ignores tsconfig.json files» [3].

As duas documentações apontam a mesma saída. A do TypeScript diz que o campo "imports" do package.json é «a standard replacement for convenience paths aliases» [1]. A do Node, que o mais parecido com paths são os subpath imports (nomes internos de um pacote, declarados no package.json dele), «with the limitation that they need to start with #» [3].

O template desta entrega, estructura-typescript, é feito assim:

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

Traz o verificador como linha de comando, sem o servidor da API do Iván: a fronteira é a mesma, e sobra menos. Vamos parte por parte, com a pergunta de sempre: que problema isso resolve hoje?

Quem lê cada arquivo?

O tsconfig.json é lido pelo compilador e pelo editor. O package.json é lido pelos dois, e também pelo Node.

Essa é a fronteira inteira, e cabe numa tabela:

Essa é a fronteira inteira, e cabe numa tabela
ArquivoLido pelo tsc (e pelo editor)Lido pelo Node ao iniciar
tsconfig.jsonSimNão [3]
package.jsonSim [1]Sim [4]

O que tiver de valer nos dois momentos, ao compilar e ao rodar, precisa estar no arquivo que os dois leem.

O que o tsconfig.json decide?

Como o TypeScript verifica e como emite. A emissão são os arquivos que o tsc escreve. A base do template toma seis decisões, e nenhuma chega até o Node.

{
  "compilerOptions": {
    "target": "es2024",
    "module": "nodenext",
    "strict": true,
    "types": ["node"],
    "rootDir": "./src",
    "outDir": "./dist",
    "noEmit": true
  },
  "include": ["src"]
}
  • Da verificação: strict, e types, que diz quais tipos globais existem. Desde o TypeScript 6 essa lista nasce vazia [9]; sem "node", process não existe: error TS2591: Cannot find name 'process' (medido).
  • Da emissão: target (que JavaScript sai), e rootDir com outDir (de onde sai e para onde vai).
  • Das duas: module: nodenext. Faz o TypeScript seguir as regras de módulos do Node ao verificar e ao emitir. Ao verificar, procura cada import como o Node procuraria [5]: essa opção traz consigo moduleResolution: nodenext [1]. Ao emitir, decide se cada arquivo sai como módulo ECMAScript ou como CommonJS [1]. O que ela não faz é instalar nem configurar nada no Node que vai rodar o programa.

noEmit: true faz este arquivo só verificar. É o que o editor abre para src/.

Há mais opções (lib, jsx, declaration, sourceMap), e todas fazem o mesmo: mudam a compilação. Nenhuma muda como o Node inicia.

Então, como se dá nome a um módulo?

Para um alias privado que funcione no Node sem carregador nem empacotador: com um nome que comece com #, declarado em "imports" do package.json. Para arquivos vizinhos, o caminho relativo com .js continua sendo o mais simples.

O Node os chama de subpath imports, nomes internos de um pacote: um campo para criar «private mappings that only apply to import specifiers from within the package itself» [4]. Um specifier, ou especificador, é o texto entre aspas de um import. Privados: só valem dentro do próprio pacote. E com uma regra de forma: «Entries in the "imports" field must always start with #» [4], para não serem confundidos com pacotes de fora.

No template são quatro linhas:

"imports": {
  "#config": "./dist/config.js",
  "#reporte": "./dist/reporte.js",
  "#revisar": "./dist/revisar.js",
  "#servicio": "./dist/servicio.js"
}

E o main.ts escreve import { revisarTodos } from "#revisar". O Node lê o campo e carrega dist/revisar.js.

E o TypeScript? Lê o mesmo campo e chega ao mesmo arquivo. Mas dist/revisar.js ainda não existe na primeira compilação. A documentação explica o passo extra: se o package.json é do projeto que está sendo compilado, o TypeScript procura o arquivo-fonte que vai produzir essa saída, e para isso usa outDir e rootDir, «so using "imports" usually requires an explicit rootDir to be set» [1]. Por isso a base os declara. Medido: num clone recém-feito, sem dist/, o template compila de primeira.

Um único nome, declarado uma única vez, que significa o mesmo ao compilar e ao rodar. Não é a única forma de importar que os dois entendem: também os caminhos relativos, que vêm a seguir, e os pacotes instalados. É a que serve quando se quer um alias.

Por que ./servicio.js, se o arquivo se chama servicio.ts?

Porque entre aspas se escreve o que o Node vai carregar, e neste template o TypeScript deixa tal qual.

Entre módulos vizinhos, o template usa caminhos relativos: import { clasificar } from "./servicio.js". A extensão desconcerta na primeira vez. A regra vem do Node: num import, «A file extension must be provided» [6]. E do TypeScript, que explica que o especificador «is emitted as-written» [5]: sai como foi escrito. Se o Node vai carregar servicio.js, é isso que se escreve.

É o que acontece aqui, não uma lei. O TypeScript tem uma opção, rewriteRelativeImportExtensions, que troca um .ts relativo por .js no que emite [24]. O template não a ativa, então o especificador sai intacto.

É a mesma regra do alias, vista do outro lado. Com module: nodenext, o TypeScript avisa desta. Medido, tirando a extensão:

error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './servicio.js'?

Do alias não avisa, porque paths existe justamente para dizer a ele «confie, outro resolve».

Por que os testes são compilados à parte?

Porque um tsconfig descreve um único programa, e o código e os testes são dois: um é entregue e o outro não.

O guia do TypeScript diz assim: «A single tsconfig.json can only represent a single environment» [7], e põe o código de testes na lista do que merece o próprio. A página de project references conta o que acontecia com um único arquivo para src/ e test/: «It was possible for the implementation files to import the test files», e não era possível compilá-los juntos «without having src appear in the output folder name» [8].

Medimos isso num projeto de três arquivos, com "include": ["src", "test"]:

  • Com rootDir: ./src, não compila: error TS6059: File '…/test/reporte.test.ts' is not under 'rootDir'.
  • Sem rootDir, compila, mas a saída muda de forma: dist/src/main.js e dist/test/reporte.test.js. Os testes viajam no que é entregue, e node dist/main.js responde Error: Cannot find module '…/dist/main.js'.
  • E o main.ts importou um arquivo de test/ sem que ninguém reclamasse. Compilou e rodou.

O template divide isso em três arquivos, cada um com um trabalho:

O template divide isso em três arquivos, cada um com um trabalho
ArquivoO que incluiO que faz
tsconfig.jsonsrc/A base: verifica, não escreve
tsconfig.build.jsono mesmo (herda com extends [2])Escreve dist/: os .js e os .d.ts (arquivos que descrevem tipos e não executam código)
test/tsconfig.jsontest/Verifica os testes; nunca escreve

O detalhe fino está no terceiro. Os testes importam #reporte, igual ao main.ts. Mas esse tsconfig vive em outra pasta e não inclui src/, então o TypeScript chega a dist/reporte.d.ts, o arquivo de tipos que a construção deixou. Medido: no programa dos testes não entra um único arquivo de src/. Os testes veem o que vê qualquer um que use o compilado.

Tem um custo, e a mesma página diz: com vários tsconfig soltos «you end up always running tsc twice» [8]. Para isso existem as project references. Com cinco arquivos, rodar duas vezes não se nota; o README diz quando dar esse passo.

Como os testes rodam?

O Node os roda direto dos .ts, tirando os tipos; e eles carregam o código já compilado, pela mesma porta #.

O Node executa arquivos de TypeScript que só tenham sintaxe apagável: apaga as anotações de tipos, mas não transforma o TypeScript que precisaria gerar JavaScript novo. Troca os tipos por espaços em branco, e «no type checking is performed» [3]. O template usa isso para os testes, com o executor que o Node já traz (node --test), sem instalar mais nada. Como o Node carrega esses arquivos tal qual, ali os imports relativos levam .ts: ./comun/servidor.ts. A regra não mudou: escreve-se o que o Node vai carregar.

npm test faz três coisas: constrói o dist/, verifica os tipos dos testes e os roda. O relatório fecha assim:

ℹ tests 46
ℹ pass 46
ℹ fail 0
ℹ cancelled 0

São 46 testes, e eles se contam ali. Com um padrão que não encontra nenhum arquivo, node --test sai com 0 e ℹ tests 0 (medido): um verde que não testou nada.

O padrão do script, "test/**/*.test.ts", também não sobra. Por padrão, o Node roda todo arquivo que esteja sob uma pasta test/ [11]. Medido sem o padrão: o servidor de ajuda sai como mais um teste, ✔ test/comun/servidor.ts, e o relatório diz 47.

Um dos testes, programa.test.ts, executa dist/main.js em outro processo. É o único que vê o que nenhuma verificação de tipos vê: se o Node encontra cada módulo ao iniciar.

O que o verificador cuida que um template não deve ensinar errado?

Um tempo limite que cobre a consulta inteira, um teto para o que se lê e erros que nunca repetem a URL.

O que chega de servicios.json é unknown até ser verificado campo por campo: os tipos não vigiam o que entra ao rodar. O corpo de cada resposta é lido até 64 KiB e solto. Nenhuma mensagem repete uma URL, que pode trazer um token. Tiramos cada proteção numa cópia, uma por uma: as 26 deixaram o teste correspondente em vermelho.

E onde vai o import do Iván?

No main.ts, com o nome #revisar; e o nome, no package.json.

Na quarta-feira, o Iván e a Lucía apagaram a linha de paths. Declararam #revisar em "imports" e mudaram uma linha do main.ts. O editor continuou completando. E desta vez, o que o compilador aceitava era o mesmo que o Node ia procurar.

Como saber que a fronteira existe?

Porque um script a cruza de propósito a cada mudança: planta o alias e exige que compile e que não inicie, pela razão exata.

herramientas/probar-frontera.sh trabalha numa cópia temporária. Compila e inicia o mesmo programa duas vezes. Entre as duas só muda como o main.ts importa o módulo revisar, e quem declara esse nome:

  1. Controle, com o projeto tal como está. O main.ts importa #revisar. Tem que compilar e iniciar. Se não, o experimento está mal montado, ou o projeto já traz um import que o Node não resolve, e o script para em vermelho.
  2. Violação. Planta-se @/revisar em paths e o main.ts o importa. Tem que compilar, com o alias intacto em dist/main.js, e tem que não iniciar, com ERR_MODULE_NOT_FOUND.

Esta é a saída 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 que o controle? Porque um experimento que só espera um vermelho fica «verde» também quando falha pela razão errada. Quebramos de sete maneiras, e as sete saíram em vermelho. Três dizem muito: com um carregador que resolve o alias, ❌ ARRANCÓ; com um alias que o tsc rejeita, diz que a violação não compilou e que isso «no demuestra la frontera»; com o alias plantado no projeto real, para no controle.

O CI do GitHub está escrito para rodar os tipos, os testes e a fronteira com a LTS mais recente do Node e com a 26.13.0, e a fronteira também no macOS com o /bin/bash do sistema, a cada mudança e toda segunda-feira. Se o repositório público passar 60 dias sem atividade, o GitHub desliga a execução das segundas [22].

Quais são cinco erros frequentes?

Os cinco saem da mesma coisa: acreditar que o tsconfig.json manda onde não manda.

1. Um alias em paths que ninguém resolve ao rodar

Compila, o editor aceita, e o Node não inicia.

É o erro do Iván [1][2]. paths não é um erro em si: serve quando um empacotador resolve o alias e só é preciso avisar ao TypeScript [1]. O que falha é usá-lo sozinho. Quem denuncia é ERR_MODULE_NOT_FOUND, o erro do Node para um módulo que não conseguiu resolver [12], com Cannot find package: o Node achou que @/revisar era um pacote instalado. Para um alias privado, sem carregador nem empacotador, a saída padrão é "imports" [1][3].

2. Caminhos relativos sem extensão, com uma resolução que os perdoa

Com moduleResolution: bundler, o TypeScript aceita ./servicio puro; o Node, não.

bundler diz ao TypeScript que um empacotador vai resolver os imports. O guia avisa que essa opção «is infectious, allowing code that only works in bundlers to be produced» [7]. Medido no template, com bundler e um import sem extensão: compila, e ao iniciar:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '…/dist/servicio' imported from …/dist/revisar.js

Se o programa roda no Node tal como sai do tsc, a opção é nodenext, que verifica com as regras do Node [5][6].

3. Um único tsconfig.json para o código e os testes

Ou os testes viajam no dist/, ou o programa muda de lugar, ou o código acaba importando um teste.

São os três sintomas medidos acima [8]. Desde o TypeScript 6, rootDir não é mais adivinhado: é a pasta do tsconfig, e as notas dessa versão descrevem o sintoma tal qual: «files being written to ./dist/src/index.js instead of ./dist/index.js» [9]. A saída é um tsconfig por programa [7].

4. Copiar o tsconfig.json de um tutorial velho

O TypeScript 7 retirou opções que milhares de tutoriais ainda ensinam.

O TypeScript 7 saiu em 8 de julho de 2026 [10]. É um compilador novo, e o que a versão 6 marcava como obsoleto agora é um erro. O anúncio diz isso das duas opções mais copiadas: «baseUrl is no longer supported», e o mesmo de moduleResolution: node [10]. Medido com 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 o par de sempre de paths. Se o alias dependia dos dois, metade já não existe. Antes de copiar um tsconfig, veja de que ano ele é.

5. Acreditar que, se o Node rodou, os tipos estão certos

O Node tira os tipos. Não os verifica.

Executar .ts não transforma o Node num compilador [3]. Medido com um arquivo de duas linhas, const limite: number = "cinco"; e um console.log: o Node imprime cinco e sai com 0. O tsc, com o mesmo arquivo:

error TS2322: Type 'string' is not assignable to type 'number'.

São duas ferramentas com dois trabalhos. Por isso npm test verifica os tipos antes de rodar os testes.

5. Acreditar que, se o Node rodou, os tipos estão certos
ErroO que o denunciaFonte
1. Alias em paths sem quem o resolvaERR_MODULE_NOT_FOUND: Cannot find package '@/…' ao iniciar[1][2][3]
2. Sem extensão, com bundlerCannot find module '…/dist/servicio' ao iniciar[5][6][7]
3. Um tsconfig para tudodist/src/main.js, testes no dist/, ou TS6059[7][8][9]
4. Um tsconfig de tutorial velhoTS5102, TS5108[9][10]
5. «O Node rodou»Um verde do Node com um vermelho do tsc[3]

Exercício: dá para fazer compilar e não iniciar?

O exercício planta o alias do Iván, mostra que o compilador o aceita, tenta consertá-lo onde parece lógico e deixa ver como o script avisa.

É preciso o Node 26.13 ou mais novo (node --version), que já traz o npm, mais Git e bash; uns 20 minutos.

  • No Linux Mint 22, não use apt install nodejs: o Mint 22 se baseia no Ubuntu 24.04 [19], que traz o Node 18.19 [18], e com ele os testes não rodam: Could not find '…/test/**/*.test.ts' (medido). Instale o Node com o nvm, como diz o README dele [20]:
  sudo apt install curl
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.0/install.sh | bash

Abra outro terminal (no mesmo, o nvm ainda não é encontrado; medido) e rode nvm install 26. A lição 1 do curso de TypeScript explica passo a passo. - No macOS, o mesmo, com o nvm. - Com o nvm já instalado, nvm install 26. No Windows, use o WSL.

Passo 1. Clone e confira que tudo está verde.

git clone https://github.com/HabilMX/estructura-typescript
cd estructura-typescript
npm ci
npm test
bash herramientas/probar-frontera.sh

O que deve aparecer: ℹ pass 46 com ℹ fail 0 e, no fim do script, ✅ frontera: se sostiene.

Use este clone só para praticar. Assim, toda mudança que aparecer nele é do exercício.

Passo 2. Preveja antes de mexer. O passo seguinte declara o alias @/revisar no tsconfig.json e o usa no main.ts. Anote três coisas: compila? Inicia? E se além disso @/revisar for declarado no package.json?

Passo 3. Plante o alias. Estas duas linhas servem igual no Linux e no macOS; deixam uma cópia .bak de cada arquivo.

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 sem um único erro. O node não inicia. A linha que importa:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@/revisar' imported from …/dist/main.js

Passo 4. Conserte onde parece lógico. Se o Node lê o package.json, declare ali o mesmo nome:

npm pkg set 'imports.@/revisar=./dist/revisar.js'
npm run build
node dist/main.js --version
bash herramientas/probar-frontera.sh

O mesmo ERR_MODULE_NOT_FOUND. O Node só procura em "imports" os nomes que começam com #; os demais, trata como pacotes. E o script fica vermelho, sem chegar ao segundo passo:

❌ el control NO arrancó: el programa, tal como está, no corre con node:

Esse é o controle trabalhando: o projeto já traz um import que o Node não resolve.

Passo 5. Dê o nome que o Node procura.

sed -i.bak 's|from "@/revisar"|from "#revisar"|' src/main.ts
npm run build
node dist/main.js --version

Responde revisor 0.1.0. A linha de paths continua no tsconfig.json, e não fez falta: ninguém mais a usa.

Passo 6. Desfaça só o que foi mexido. O exercício mudou três arquivos. Antes de desfazer, veja o que mudou neles:

git diff -- tsconfig.json src/main.ts package.json

Devem aparecer duas mudanças: a linha de paths no tsconfig.json e a linha "@/revisar" no package.json. src/main.ts não aparece: no passo 5 ficou como estava. Se aparecer algo mais, não é do exercício: guarde antes de seguir.

Se só estiver o que é do exercício, restaure esses três arquivos. git restore só mexe nos caminhos indicados [25]:

git restore tsconfig.json src/main.ts package.json
bash herramientas/probar-frontera.sh
git status --short

A fronteira volta ao verde, e o git status mostra a única coisa que resta: as cópias que o sed fez.

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

Guarde-as até ter certeza de que não fazem falta. Depois apague uma por uma, com rm -i src/main.ts.bak tsconfig.json.bak, que pergunta antes de cada uma. Não use um comando que limpe a pasta inteira: levaria junto as anotações que estiverem ali.

Como saber que deu certo: foram sete execuções e três desfechos. Verde, quatro vezes: as duas do passo 1, o programa no passo 5 e a fronteira do passo 6. Vermelho do Node, ERR_MODULE_NOT_FOUND, duas vezes: os passos 3 e 4. E o vermelho do script, «el control NO arrancó», no passo 4. Se no passo 3 npm run build marcar TS2307, a linha do sed não encontrou "outDir": "./dist", no tsconfig.json: confira que ele não foi editado. Se no passo 5 o erro continuar, confira que o main.ts diz "#revisar".

Para ir mais longe (opcional): o alias que o Iván queria quase existe. Desde o Node 24.14, um nome pode começar com #/ [4], e o TypeScript o entende desde a versão 6 [9]. Rode npm pkg set 'imports.#/*=./dist/*.js', mude o import do main.ts para "#/revisar" e compile de novo. Antes, preveja: inicia? Resposta: sim, revisor 0.1.0 (medido). Desfaça igual ao passo 6: git diff -- package.json src/main.ts para ver as duas mudanças, e git restore package.json src/main.ts.

Para levar

Três perguntas para fazer ao repositório esta semana.

  1. O tsconfig.json do projeto tem paths? Se tiver, que ferramenta resolve esses nomes quando o programa roda? Se a resposta for «nenhuma», já se sabe o que vai acontecer.
  2. O que há dentro do dist/? Se aparecer um arquivo de testes, o código e os testes estão sendo compilados como um único programa.
  3. Algum teste inicia o programa compilado, como o servidor o iniciaria? Se nenhum, quem fica sabendo primeiro de um import que o Node não encontra?

O que vem depois?

No Go, a fronteira é vigiada pela ferramenta; no Python, pela instalação; no Rust, pelo compilador; no TypeScript, pelo Node ao iniciar. No Java, as fronteiras já não são arquivos: são camadas.

Um mês depois, o Iván pegou a primeira API dele em Java, com Spring Boot. Quatro pastas com nome de camada: api, facade, service, repository. A mudança era um campo novo numa resposta.

Mexeu em quatro arquivos para mover um dado.

Na facade havia um método que só chamava outro. Para que uma camada que não faz nada? Na entrega 5: uma API por camadas, o que cada uma pode saber das outras, e quando a facade faz falta e quando não.

O template e o curso

  • Template: github.com/HabilMX/estructura-typescript. Usa-se como template do GitHub ou se clona [21]. O README explica cada pasta e cada tsconfig, o que não traz, quando acrescentar cada coisa e como tirar o exemplo. O código é MIT; o texto e as explicações são CC BY-SA 4.0.
  • Versões: Node 26.13 ou mais novo. A 26 é a linha LTS mais recente [16]. Em engines, o package.json declara o mínimo que o template suporta: a 26.13.0, primeira LTS dessa linha. É um mínimo, não a lista do que foi testado. TypeScript 7.0.2, a vigente em 17 de novembro [17], fixada no package-lock.json, que o npm ci respeita sem modificar [13][14]. Foi testado com Node 26.13.1 e 26.13.0 no macOS arm64 (também com o /bin/bash do sistema) e no Linux arm64 (contêiner ubuntu:24.04). O Linux x86-64 ainda não foi testado. Com o Node 24.22.0 também rodou, com um aviso EBADENGINE do npm (medido): engines avisa, não impede [15]. O CI está escrito para a LTS de cada semana e a 26.13.0 no Linux, e a LTS no macOS [23].
  • Curso de TypeScript da Hábil: se módulos, tsconfig.json ou testes com o Node forem novidade, a lição 7 explica tudo do zero: Curso de TypeScript · Lição 7, Módulos, testes e qualidade.

Escrevo a partir do que vemos todos os dias na Hábil, onde construímos sistemas para bancos, seguradoras e empresas no México. Se no trabalho ou na faculdade aparecer um repositório em que ninguém sabe onde mexer, vamos conversar: habil.mx

O que a Hábil faz?

Ensinamos a programar com o mesmo que usamos para construir: código testado, explicado e aberto.

Esta série nasce do mesmo lugar que os nossos cursos. O Curso de TypeScript parte de que os tipos não existem na execução: ensina o que protegem, o que não protegem e como validar os dados que chegam de fora, e o publicamos aberto, com licença Creative Commons; a lição 7 explica os módulos, os testes e a qualidade que o template deste artigo usa. E no catálogo há mais cursos de programação, gratuitos e com código testado e explicado passo a passo.

Veja o Curso de TypeScript e o catálogo de Cursos de programação.

Se a equipe herdar um sistema em que ninguém sabe onde mexer, ou precisar construir um que possa continuar sendo mantido, também fazemos isso: veja Construir um sistema sob medida. Peça a primeira conversa, sem custo. Nela avaliamos se convém configurar o que a equipe já tem, usar um produto ou construir, e o que ela receberia em cada caso. Escreva para nós pelo WhatsApp.

Fontes consultadas em 17 de novembro de 2026. As citações em inglês são reproduzidas tal como estão.

Referências

  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 e extends. https://www.typescriptlang.org/tsconfig/
  3. Node.js v26.13.1, «Modules: TypeScript»: «Type stripping» e «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» e «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 da versão): «rootDir now defaults to .», «types now defaults to []», «Deprecated: --baseUrl» e «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 julho 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 do pacote typescript, versão latest: 7.0.2. https://registry.npmjs.org/typescript/latest
  18. Launchpad (Canonical), pacote nodejs publicado no 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