Skip to content
Architecture and backend18 min

The structure of a project (4): the import that compiles and doesn't start

By · co-founder and Chief Executive Officer of Hábil ·

Your tsconfig.json alias compiles and Node won't start, because Node never reads that file. What tsconfig decides, what package.json decides, and a template.

The structure of a project · installment 4 of 7 · TypeScript

Scenario: the characters and the story are made up. The technical data and the quotes carry their source at the end.

In 1 minute

  • paths, the tsconfig.json option for aliases, doesn't change what the compiler writes. The alias comes out as is in the JavaScript, and Node doesn't know what it is [1][2].
  • Node doesn't read tsconfig.json. To give a module a name, it reads the "imports" field of package.json, and TypeScript understands that field too [1][3][4].
  • tsconfig.json decides how TypeScript checks the program and how it emits it (emit: write the files in dist/). It doesn't configure the Node that runs it [3].
  • The tests and the code are compiled separately, with a tsconfig each: that way dist/ carries no tests and the code can't lean on them [7][8].
  • You take away a template that clones and runs on the first try, with a script that proves that boundary by turning red when it should.
  • For Monday: search for paths in your tsconfig.json and ask who resolves those names when the program runs.

In this article

  1. What happened on Tuesday at 17:48?
  2. What does tsconfig.json decide, and what doesn't it?
  3. What are five frequent mistakes?
  4. Exercise: can you make it compile and not start?
  5. Key takeaways
  6. What's next?
  7. The template and the course
  8. What does Hábil do?
  9. References

What happened on Tuesday at 17:48?

Iván wrote an import that the compiler accepted and that Node, on startup, didn't find.

Tuesday, 17:05. Third floor.

Fourth assignment, the first in TypeScript. The checker again, the one from Go, Python and Rust, which queries services over HTTP. This time it lived inside an API, and the request was short: "Make it possible to request the check from main too."

Someone else had left the project. It looked good:

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

In tsconfig.json, Iván found a line he liked:

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

An alias. With it he could write @/revisar instead of counting dots and slashes. He used it in src/main.ts:

import { revisarTodos } from "@/revisar";

The editor autocompleted the function's name. It compiled:

$ npx tsc -p tsconfig.build.json
$

Nothing. Not an error, not a warning. He pushed the change.

Tuesday, 17:48.

The test server started the new version with node dist/main.js. The answer (trimmed; the path changes on every machine):

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

A package? Iván hadn't installed any package. revisar was a file of his own, it was right there, and the compiler had found it. He opened dist/main.js to see what tsc had written:

import { revisarTodos } from "@/revisar";

His line, identical. The compiler had stripped the types and left the alias as it was.

At 17:56 he wrote to Lucía, the tech lead.

"It compiles and doesn't start. It says it can't find @/revisar."

"Who knows where @ is?" she answered.

"The tsconfig."

"And who starts the program?"

Iván looked at the command. node dist/main.js. There was no tsconfig anywhere in that line.

"Node."

"Node doesn't read that file. Tomorrow I'll show you which one it does read."

Iván looked at the alias line again. The compiler had told him he was right. But the compiler wasn't the one who was going to run the program.

What does tsconfig.json decide, and what doesn't it?

It decides how TypeScript checks and emits the program. It doesn't configure the Node that runs it: Node resolves imports at startup with its own rules, and for a name with # it reads package.json.

The TypeScript documentation says it about paths without beating around the bush, in a section called «paths does not affect emit»: the option doesn't change the import path in the code TypeScript writes, and that's why «it’s very easy to create path aliases that appear to work in TypeScript but will crash at runtime» [1]. It's very easy to create an alias that seems to work and blows up when it runs. The tsconfig reference says what it's for, then: to tell TypeScript «that another tool has this mapping and will use it at runtime or when bundling» [2]. That another tool already has that map.

In Iván's project there was no other tool. There was Node, and the Node documentation closes the pincer: «Node.js ignores tsconfig.json files» [3].

Both documentations point to the same way out. TypeScript's says that the "imports" field of package.json is «a standard replacement for convenience paths aliases» [1]. Node's, that the closest thing to paths is subpath imports (a package's internal names, declared in its package.json), «with the limitation that they need to start with #» [3].

This installment's template, estructura-typescript, is built like this:

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

It brings the checker as a command-line tool, without the server of Iván's API: the boundary is the same, and there's less left over. Let's go part by part, with the usual question: what problem does it solve today?

Who reads each file?

tsconfig.json is read by the compiler and the editor. package.json is read by both of them, and by Node too.

That's the whole boundary, and it fits in a table:

That's the whole boundary, and it fits in a table
FileRead by tsc (and the editor)Read by Node on startup
tsconfig.jsonYesNo [3]
package.jsonYes [1]Yes [4]

Whatever you want to hold at both moments, when compiling and when running, has to be in the file both of them read.

What does tsconfig.json decide?

How TypeScript checks and how it emits. The emit is the files tsc writes. The template's base makes six decisions, and none of them reaches Node.

{
  "compilerOptions": {
    "target": "es2024",
    "module": "nodenext",
    "strict": true,
    "types": ["node"],
    "rootDir": "./src",
    "outDir": "./dist",
    "noEmit": true
  },
  "include": ["src"]
}
  • About checking: strict, and types, which says which global types exist. Since TypeScript 6 that list starts empty [9]; without "node", process doesn't exist: error TS2591: Cannot find name 'process' (measured).
  • About emit: target (which JavaScript comes out), and rootDir with outDir (where it comes from and where it goes).
  • About both: module: nodenext. It makes TypeScript follow Node's module rules when checking and when emitting. When checking, it looks up each import the way Node would [5]: that option brings moduleResolution: nodenext with it [1]. When emitting, it decides whether each file comes out as an ECMAScript module or as CommonJS [1]. What it doesn't do is install or configure anything in the Node that's going to run the program.

noEmit: true makes this file only check. It's the one the editor opens for src/.

There are more options (lib, jsx, declaration, sourceMap), and they all do the same thing: they change the compilation. None of them changes how Node starts.

So how do you name a module?

If you want a private alias that works in Node with no loader or bundler: with a name that starts with #, declared in "imports" of package.json. For neighboring files, the relative path with .js is still the simplest.

Node calls them subpath imports, a package's internal names: a field to create «private mappings that only apply to import specifiers from within the package itself» [4]. A specifier is the text between quotes in an import. Private: they only count inside your package. And with a rule of form: «Entries in the "imports" field must always start with #» [4], so they're not confused with outside packages.

In the template it's four lines:

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

And main.ts writes import { revisarTodos } from "#revisar". Node reads the field and loads dist/revisar.js.

And TypeScript? It reads the same field and reaches the same file. But dist/revisar.js doesn't exist yet when you compile for the first time. The documentation explains the extra step: if the package.json belongs to the project being compiled, TypeScript looks for the source file that's going to produce that output, and for that it uses outDir and rootDir, «so using "imports" usually requires an explicit rootDir to be set» [1]. That's why the base declares them. Measured: in a freshly made clone, with no dist/, the template compiles on the first try.

A single name, declared once, that means the same thing when compiling and when running. It's not the only way of importing that both understand: so do relative paths, which come next, and installed packages. It's the one that works when you want an alias.

Why ./servicio.js, if the file is called servicio.ts?

Because between the quotes you write what Node is going to load, and in this template TypeScript leaves it as is.

Between neighboring modules, the template uses relative paths: import { clasificar } from "./servicio.js". The extension is puzzling the first time. The rule comes from Node: in an import, «A file extension must be provided» [6]. And from TypeScript, which explains that the specifier «is emitted as-written» [5]: it comes out as you wrote it. If Node is going to load servicio.js, that's what you write.

That's what happens here, not a law. TypeScript has an option, rewriteRelativeImportExtensions, that changes a relative .ts to .js in what it emits [24]. The template doesn't turn it on, so the specifier comes out intact.

It's the same rule as the alias, seen from the other side. With module: nodenext, TypeScript does warn you about this one. Measured, removing the extension:

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

About the alias it doesn't warn, because paths exists precisely to tell it "trust me, someone else resolves it."

Why are the tests compiled separately?

Because a tsconfig describes a single program, and the code and its tests are two: one gets delivered and the other doesn't.

The TypeScript guide puts it like this: «A single tsconfig.json can only represent a single environment» [7], and it puts test code on the list of what deserves its own. Its project references page tells what used to happen with a single file for src/ and test/: «It was possible for the implementation files to import the test files», and they couldn't be compiled together «without having src appear in the output folder name» [8].

We measured it in a three-file project, with "include": ["src", "test"]:

  • With rootDir: ./src, it doesn't compile: error TS6059: File '…/test/reporte.test.ts' is not under 'rootDir'.
  • Without rootDir, it compiles, but the output changes shape: dist/src/main.js and dist/test/reporte.test.js. The tests travel in what gets delivered, and node dist/main.js answers Error: Cannot find module '…/dist/main.js'.
  • And main.ts imported a file from test/ without anyone complaining. It compiled and ran.

The template splits it into three files, each with one job:

The template splits it into three files, each with one job
FileWhat it includesWhat it does
tsconfig.jsonsrc/The base: checks, doesn't write
tsconfig.build.jsonthe same (inherits with extends [2])Writes dist/: the .js files and their .d.ts (files that describe types and don't run code)
test/tsconfig.jsontest/Checks the tests; never writes

The subtle part is in the third one. The tests import #reporte, just like main.ts. But that tsconfig lives in another folder and doesn't include src/, so TypeScript reaches dist/reporte.d.ts, the types file the build left behind. Measured: not a single file from src/ gets into the tests' program. The tests see what anyone using the compiled output sees.

It has a cost, and the same page says so: with several loose tsconfig files «you end up always running tsc twice» [8]. That's what project references are for. With five files, running twice isn't noticeable; the README says when to take that step.

How do the tests run?

Node runs them straight from the .ts files, stripping their types; and they load the already compiled code, through the same # door.

Node runs TypeScript files that only carry erasable syntax: it erases the type annotations, but it doesn't transform the TypeScript that would need to generate new JavaScript. It replaces the types with whitespace, and «no type checking is performed» [3]. The template uses it for the tests, with the runner Node already ships (node --test), without installing anything else. Since Node loads those files as they are, the relative imports there carry .ts: ./comun/servidor.ts. The rule didn't change: you write what Node is going to load.

npm test does three things: it builds dist/, checks the tests' types and runs them. The report ends like this:

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

That's 46 tests, and they're counted there. With a pattern that doesn't match any file, node --test exits with 0 and ℹ tests 0 (measured): a green that tested nothing.

The script's pattern, "test/**/*.test.ts", isn't superfluous either. By default, Node runs every file under a test/ folder [11]. Measured without the pattern: the helper server shows up as one more test, ✔ test/comun/servidor.ts, and the report says 47.

One of the tests, programa.test.ts, runs dist/main.js in another process. It's the only one that sees what no type check sees: whether Node finds each module on startup.

What does the checker take care of that a template mustn't teach wrong?

A timeout that covers the whole query, a cap on what gets read, and errors that never repeat the URL.

What comes in from servicios.json is unknown until it's checked field by field: types don't guard what comes in at runtime. The body of each response is read up to 64 KiB and let go. No message repeats a URL, which may carry a token. We removed each protection in a copy, one by one: all 26 turned their test red.

And where does Iván's import go?

In main.ts, with the name #revisar; and the name, in package.json.

On Wednesday, Iván and Lucía deleted the paths line. They declared #revisar in "imports" and changed one line of main.ts. The editor kept autocompleting. And this time, what the compiler accepted was the same thing Node was going to look for.

How do I know the boundary exists?

Because a script crosses it on purpose in every change: it plants the alias and demands that it compile and not start, for the exact reason.

herramientas/probar-frontera.sh works on a temporary copy. It compiles and starts the same program twice. Between the two, the only thing that changes is how main.ts imports the revisar module, and who declares that name:

  1. Control, with the project as it is. main.ts imports #revisar. It has to compile and start. If not, the experiment is set up wrong, or your project already carries an import Node doesn't resolve, and the script stops in red.
  2. Violation. @/revisar is planted in paths and main.ts imports it. It has to compile, with the alias intact in dist/main.js, and it has to not start, with ERR_MODULE_NOT_FOUND.

This is the real output:

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

Why the control? Because an experiment that only expects a red also turns "green" when it fails for the wrong reason. We broke it seven ways, and all seven came out red. Three say a lot: with a loader that does resolve the alias, ❌ ARRANCÓ; with an alias that tsc rejects, it says the violation didn't compile and that this «no demuestra la frontera»; with the alias planted in the real project, it stops at the control.

The GitHub CI is written to run the types, the tests and the boundary with Node's most recent LTS and with 26.13.0, and the boundary also on macOS with the system /bin/bash, on every change and every Monday. If the public repository goes 60 days without activity, GitHub turns off the Monday run [22].

What are five frequent mistakes?

All five come from the same thing: believing that tsconfig.json is in charge where it isn't.

1. An alias in paths that nobody resolves at runtime

It compiles, the editor accepts it, and Node doesn't start.

It's Iván's mistake [1][2]. paths isn't a mistake in itself: it's useful when a bundler resolves the alias and TypeScript just needs to be told [1]. What fails is using it alone. It's given away by ERR_MODULE_NOT_FOUND, Node's error for a module it couldn't resolve [12], with Cannot find package: Node thought @/revisar was an installed package. For a private alias, with no loader or bundler, the standard way out is "imports" [1][3].

2. Relative paths without an extension, with a resolution that forgives them

With moduleResolution: bundler, TypeScript accepts a bare ./servicio; Node doesn't.

bundler tells TypeScript that a bundler is going to resolve the imports. The guide warns that this option «is infectious, allowing code that only works in bundlers to be produced» [7]. Measured in the template, with bundler and an import without an extension: it compiles, and on startup:

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

If your program runs on Node just as it comes out of tsc, the option is nodenext, which checks with Node's rules [5][6].

3. A single tsconfig.json for the code and the tests

Either the tests travel in dist/, or the program changes place, or the code ends up importing a test.

They're the three symptoms measured above [8]. Since TypeScript 6, rootDir is no longer guessed: it's the tsconfig's folder, and that version's release notes describe the symptom exactly: «files being written to ./dist/src/index.js instead of ./dist/index.js» [9]. The way out is one tsconfig per program [7].

4. Copying the tsconfig.json from an old tutorial

TypeScript 7 removed options that thousands of tutorials still teach.

TypeScript 7 came out on July 8, 2026 [10]. It's a new compiler, and what version 6 marked as deprecated is now an error. The announcement says so about the two most copied options: «baseUrl is no longer supported», and the same about moduleResolution: node [10]. Measured with 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 was the usual partner of paths. If your alias depended on both, half of it no longer exists. Before copying a tsconfig, check what year it's from.

5. Believing that if Node ran it, the types are fine

Node strips the types. It doesn't check them.

Node running .ts doesn't make it a compiler [3]. Measured with a two-line file, const limite: number = "cinco"; and a console.log: Node prints cinco and exits with 0. tsc, with the same file:

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

They're two tools with two jobs. That's why npm test checks the types before running the tests.

5. Believing that if Node ran it, the types are fine
MistakeWhat gives it awaySource
1. Alias in paths with nobody to resolve itERR_MODULE_NOT_FOUND: Cannot find package '@/…' on startup[1][2][3]
2. No extension, with bundlerCannot find module '…/dist/servicio' on startup[5][6][7]
3. One tsconfig for everythingdist/src/main.js, tests in dist/, or TS6059[7][8][9]
4. A tsconfig from an old tutorialTS5102, TS5108[9][10]
5. "Node ran it"A green from Node with a red from tsc[3]

Exercise: can you make it compile and not start?

You're going to plant Iván's alias, see that the compiler accepts it, try to fix it where it seems logical and see how the script warns you.

You need Node 26.13 or newer (node --version), which already ships npm, plus Git and bash; about 20 minutes.

  • On Linux Mint 22, don't use apt install nodejs: Mint 22 is based on Ubuntu 24.04 [19], which ships Node 18.19 [18], and with it the tests don't run: Could not find '…/test/**/*.test.ts' (measured). Install Node with nvm, as its README says [20]:
  sudo apt install curl
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.0/install.sh | bash

Open another terminal (in the same one, nvm still isn't found; measured) and run nvm install 26. Lesson 1 of the TypeScript course walks through it step by step. - On macOS, the same, with nvm. - If you already have nvm, nvm install 26. On Windows, use WSL.

Step 1. Clone and check that everything is green.

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

What you should see: ℹ pass 46 with ℹ fail 0 and, at the end of the script, ✅ frontera: se sostiene.

Use this clone only for practice. That way, every change you see in it comes from the exercise.

Step 2. Predict before touching. You're going to declare the alias @/revisar in tsconfig.json and use it in main.ts. Write down three things: does it compile? Does it start? And what if you also declare @/revisar in package.json?

Step 3. Plant the alias. These two lines work the same on Linux and macOS; they leave a .bak copy of each file.

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 finishes without a single error. node doesn't start. The line that matters:

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

Step 4. Fix it where it seems logical. If Node reads package.json, declare the same name there:

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

The same ERR_MODULE_NOT_FOUND. Node only looks in "imports" for names that start with #; it treats the rest as packages. And the script turns red, without reaching the second step:

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

That's the control at work: your project already carries an import Node doesn't resolve.

Step 5. Give it the name Node does look for.

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

It answers revisor 0.1.0. The paths line is still in tsconfig.json, and it wasn't needed: nobody uses it anymore.

Step 6. Put back only what you touched. The exercise changed three files. Before putting them back, look at what changed in them:

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

You should see two changes: the paths line in tsconfig.json and the "@/revisar" line in package.json. src/main.ts doesn't show up: in step 5 it went back to how it was. If you see anything else, it's yours: save it before going on.

If only the exercise's changes are there, restore those three files. git restore only touches the paths you give it [25]:

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

The boundary goes back to green, and git status shows the only thing left: the copies sed made.

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

Keep them until you're sure you don't need them. Then delete them one by one, with rm -i src/main.ts.bak tsconfig.json.bak, which asks before each one. Don't use a command that cleans the whole folder: it would also take your notes.

How you know you did it right: you ran seven times and saw three outcomes. Green, four times: the two in step 1, the program in step 5 and the boundary in step 6. Node's red, ERR_MODULE_NOT_FOUND, twice: steps 3 and 4. And the script's red, «el control NO arrancó», in step 4. If in step 3 npm run build shows TS2307, the sed line didn't find "outDir": "./dist", in tsconfig.json: check that you didn't edit it. If in step 5 the error is still there, check that main.ts says "#revisar".

To go further (optional): the alias Iván wanted almost exists. Since Node 24.14, a name can start with #/ [4], and TypeScript understands it since version 6 [9]. Run npm pkg set 'imports.#/*=./dist/*.js', change the main.ts import to "#/revisar" and compile again. First, predict: does it start? Answer: yes, revisor 0.1.0 (measured). Put it back the same way as in step 6: git diff -- package.json src/main.ts to see the two changes, and git restore package.json src/main.ts.

Key takeaways

Three questions to ask your repository this week.

  1. Does your tsconfig.json have paths? If so, which tool resolves those names when the program runs? If the answer is "none", you already know what's going to happen.
  2. What's inside your dist/? If you find a test file, your code and your tests are being compiled as a single program.
  3. Does any test start the compiled program, the way the server would start it? If none does, who's the first to find out about an import Node can't find?

What's next?

In Go, the boundary is guarded by the tool; in Python, by the installation; in Rust, by the compiler; in TypeScript, by Node on startup. In Java, the boundaries are no longer files: they're layers.

A month later, Iván got his first API in Java, with Spring Boot. Four folders named after layers: api, facade, service, repository. His change was a new field in a response.

He touched four files to move one piece of data.

In the facade there was a method that only called another one. What good is a layer that does nothing? In installment 5: a layered API, what each layer may know about the others, and when you do and don't need the facade.

The template and the course

  • Template: github.com/HabilMX/estructura-typescript. Use it as a GitHub template or clone it [21]. The README explains each folder and each tsconfig, what it doesn't include, when to add each thing and how to remove the example. The code is MIT; the text and explanations are CC BY-SA 4.0.
  • Versions: Node 26.13 or newer. 26 is the most recent LTS line [16]. In engines, package.json declares the minimum the template supports: 26.13.0, the first LTS of that line. It's a minimum, not the list of what was tested. TypeScript 7.0.2, the current one on November 17 [17], pinned in package-lock.json, which npm ci respects without modifying it [13][14]. It was tested with Node 26.13.1 and 26.13.0 on macOS arm64 (also with the system /bin/bash) and on Linux arm64 (ubuntu:24.04 container). Linux x86-64 hasn't been tested yet. With Node 24.22.0 it also ran, with an EBADENGINE warning from npm (measured): engines warns, it doesn't prevent [15]. The CI is written for each week's LTS and 26.13.0 on Linux, and the LTS on macOS [23].
  • Hábil's TypeScript course: if modules, tsconfig.json or testing with Node are new to you, lesson 7 covers them from scratch: TypeScript course · Lesson 7, Modules, tests, and quality.

I write from what we see every day at Hábil, where we build systems for banking, insurance and companies in Mexico. If at work or at school you run into a repository nobody knows where to touch, let's talk: habil.mx

What does Hábil do?

We teach programming with the same things we use to build: tested, explained and open code.

This series comes from the same place as our courses. The TypeScript course starts from the fact that types don't exist at runtime: it teaches what they protect, what they don't, and how to validate data that arrives from outside, and we publish it openly, under a Creative Commons license; its lesson 7 covers the modules, tests and quality that this article's template uses. And the catalog has more programming courses, free and with code tested and explained step by step.

See the TypeScript course and the Programming courses catalog.

If your team inherits a system nobody knows where to touch, or needs to build one that can keep being maintained, we do that too: see Build your custom system. Request your first conversation, at no cost. In it we review whether it makes sense to configure what you already have, use a product or build, and what you would get in each case. Write to us on WhatsApp.

Sources accessed on November 17, 2026. Quotes in English are reproduced as is.

References

  1. TypeScript, «Modules - Reference»: «paths», «paths does not affect emit», «package.json "imports" and self-name imports» and «Implied and enforced options», The TypeScript Handbook. https://www.typescriptlang.org/docs/handbook/modules/reference.html
  2. TypeScript, «TSConfig Reference»: paths and extends. https://www.typescriptlang.org/tsconfig/
  3. Node.js v26.13.1, «Modules: TypeScript»: «Type stripping» and «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» and «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» (release notes): «rootDir now defaults to .», «types now defaults to []», «Deprecated: --baseUrl» and «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), July 8, 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, typescript package registry, latest version: 7.0.2. https://registry.npmjs.org/typescript/latest
  18. Launchpad (Canonical), nodejs package published in 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