Към съдържанието
Архитектура и бекенд17 мин

Структурата на един проект (4): импортът, който се компилира, но не тръгва

От · съосновател и Chief Executive Officer на Hábil ·

Псевдонимът ви в tsconfig.json се компилира, а Node не тръгва: не чете този файл. Какво решава tsconfig, какво решава package.json и шаблон, който го проверява.

Структурата на един проект · част 4 от 7 · TypeScript

Сценарий: героите и историята са измислени. Техническите данни и цитатите са с източник в края.

За 1 минута

  • paths, опцията на tsconfig.json за псевдоними, не променя това, което компилаторът пише. Псевдонимът излиза непроменен в JavaScript, а Node не знае какво е [1][2].
  • Node не чете tsconfig.json. За да даде име на модул, той чете полето "imports" на package.json, а това поле го разбира и TypeScript [1][3][4].
  • tsconfig.json решава как TypeScript проверява програмата и как я генерира (генериране: записване на файловете в dist/). Той не настройва Node, който я изпълнява [3].
  • Тестовете и кодът се компилират поотделно, всеки със свой tsconfig: така dist/ не носи тестове и кодът не може да се опира на тях [7][8].
  • Взимаш шаблон, който се клонира и тръгва от първия път, със скрипт, който доказва тази граница, като става червен, когато трябва.
  • За понеделник: потърси paths в своя tsconfig.json и се запитай кой разрешава тези имена, когато програмата работи.

В тази статия

  1. Какво се случи във вторник в 17:48?
  2. Какво решава tsconfig.json и какво не?
  3. Кои са пет чести грешки?
  4. Упражнение: можеш ли да накараш програмата да се компилира, но да не тръгва?
  5. Ключови изводи
  6. Какво следва?
  7. Шаблонът и курсът
  8. Какво прави Hábil?
  9. Източници

Какво се случи във вторник в 17:48?

Иван написа импорт, който компилаторът прие, а Node, при стартиране, не намери.

Вторник, 17:05. Трети етаж.

Четвърта задача, първата на TypeScript. Пак проверителят — този от Go, Python и Rust, който запитва услуги по HTTP. Този път живееше в едно API, а поръчката беше кратка: «Проверката да може да се пуска и от main».

Проектът го беше оставил някой друг. Изглеждаше добре:

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

В tsconfig.json Иван намери ред, който му хареса:

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

Псевдоним. С него можеше да пише @/revisar, вместо да брои точки и наклонени черти. Използва го в src/main.ts:

import { revisarTodos } from "@/revisar";

Редакторът му допълни името на функцията. Компилира се:

$ npx tsc -p tsconfig.build.json
$

Нищо. Нито грешка, нито предупреждение. Качи промяната.

Вторник, 17:48.

Тестовият сървър пусна новата версия с node dist/main.js. Отговорът (съкратен; пътят е различен на всяка машина):

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

Пакет? Иван не беше инсталирал никакъв пакет. revisar беше негов файл, беше там и компилаторът го беше намерил. Отвори dist/main.js, за да види какво беше написал tsc:

import { revisarTodos } from "@/revisar";

Неговият ред, същият. Компилаторът беше махнал типовете и беше оставил псевдонима както си е.

В 17:56 писа на Лусия, техническата ръководителка.

— Компилира се и не тръгва. Казва, че не намира @/revisar.

— Кой знае къде е @? — отговори тя.

— tsconfig-ът.

— А кой пуска програмата?

Иван погледна командата. node dist/main.js. В този ред нямаше никакъв tsconfig.

— Node.

— Node не чете този файл. Утре ще ти покажа кой чете.

Иван пак погледна реда с псевдонима. Компилаторът му беше дал право. Но не компилаторът щеше да пусне програмата.

Какво решава tsconfig.json и какво не?

Решава как TypeScript проверява и генерира програмата. Не настройва Node, който я изпълнява: Node разрешава импортите при стартиране по свои правила, а за име с # чете package.json.

Документацията на TypeScript го казва за paths без заобикалки, в раздел, който се казва «paths does not affect emit»: опцията не променя пътя на импорта в кода, който TypeScript пише, и затова «it’s very easy to create path aliases that appear to work in TypeScript but will crash at runtime» [1]. Много лесно е да създадеш псевдоним, който изглежда, че работи, и гърми при изпълнение. Справочникът на tsconfig казва тогава за какво служи: за да предупреди TypeScript, «that another tool has this mapping and will use it at runtime or when bundling» [2]. Че друг инструмент вече има тази карта.

В проекта на Иван нямаше друг инструмент. Имаше Node, а документацията на Node затваря клещите: «Node.js ignores tsconfig.json files» [3].

Двете документации сочат един и същ изход. Тази на TypeScript казва, че полето "imports" на package.json е «a standard replacement for convenience paths aliases» [1]. Тази на Node — че най-близкото до paths са subpath imports (вътрешни имена на пакет, обявени в неговия package.json), «with the limitation that they need to start with #» [3].

Шаблонът на тази част, estructura-typescript, е направен така:

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

Той носи проверителя като команден ред, без сървъра на API-то на Иван: границата е същата, а излишното е по-малко. Да вървим част по част, с обичайния въпрос: какъв проблем решава днес?

Кой чете всеки файл?

tsconfig.json го четат компилаторът и редакторът. package.json го четат и двамата, а също и Node.

Това е цялата граница и се побира в една таблица:

Това е цялата граница и се побира в една таблица
ФайлЧете ли го tsc (и редакторът)Чете ли го Node при стартиране
tsconfig.jsonДаНе [3]
package.jsonДа [1]Да [4]

Това, което искаш да важи и в двата момента, при компилиране и при изпълнение, трябва да е във файла, който четат и двамата.

Какво наистина решава tsconfig.json?

Как проверява TypeScript и как генерира. Генерирането са файловете, които tsc записва. Базата на шаблона взима шест решения и нито едно не стига до Node.

{
  "compilerOptions": {
    "target": "es2024",
    "module": "nodenext",
    "strict": true,
    "types": ["node"],
    "rootDir": "./src",
    "outDir": "./dist",
    "noEmit": true
  },
  "include": ["src"]
}
  • За проверката: strict и types, което казва кои глобални типове съществуват. От TypeScript 6 този списък започва празен [9]; без "node" process не съществува: error TS2591: Cannot find name 'process' (измерено).
  • За генерирането: target (какъв JavaScript излиза) и rootDir с outDir (откъде излиза и къде отива).
  • За двете: module: nodenext. Кара TypeScript да следва правилата на Node за модули при проверка и при генериране. При проверка търси всеки импорт така, както би го търсил Node [5]: тази опция носи със себе си moduleResolution: nodenext [1]. При генериране решава дали всеки файл излиза като ECMAScript модул или като CommonJS [1]. Това, което не прави, е да инсталира или да настройва каквото и да е в Node, който ще пусне програмата.

noEmit: true кара този файл само да проверява. Той е този, който редакторът отваря за src/.

Има и още опции (lib, jsx, declaration, sourceMap) и всички правят едно и също: променят компилирането. Нито една не променя как стартира Node.

Тогава как се именува модул?

Ако искаш частен псевдоним, който работи в Node без зареждач и без бъндлър: с име, което започва с #, обявено в "imports" на package.json. За съседни файлове относителният път с .js остава най-простото.

Node ги нарича subpath imports, вътрешни имена на пакет: поле за създаване на «private mappings that only apply to import specifiers from within the package itself» [4]. Specifier, или спецификатор, е текстът в кавичките на един import. Частни: важат само вътре в твоя пакет. И с едно правило за формата: «Entries in the "imports" field must always start with #» [4], за да не се бъркат с външни пакети.

В шаблона са четири реда:

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

А main.ts пише import { revisarTodos } from "#revisar". Node чете полето и зарежда dist/revisar.js.

А TypeScript? Чете същото поле и стига до същия файл. Но dist/revisar.js още не съществува, когато компилираш за първи път. Документацията обяснява допълнителната стъпка: ако package.json е на проекта, който се компилира, TypeScript търси изходния файл, който ще произведе този резултат, и за това използва outDir и rootDir, «so using "imports" usually requires an explicit rootDir to be set» [1]. Затова базата ги обявява. Измерено: в току-що направен клонинг, без dist/, шаблонът се компилира от първия път.

Едно-единствено име, обявено веднъж, което означава едно и също при компилиране и при изпълнение. Не е единственият начин за импортиране, който двамата разбират: такива са и относителните пътища, които идват веднага след това, и инсталираните пакети. Това е начинът, който служи, когато искаш псевдоним.

Защо ./servicio.js, щом файлът се казва servicio.ts?

Защото в кавичките се пише това, което Node ще зареди, а в този шаблон TypeScript го оставя както е.

Между съседни модули шаблонът използва относителни пътища: import { clasificar } from "./servicio.js". Разширението обърква първия път. Правилото идва от Node: в един import «A file extension must be provided» [6]. И от TypeScript, който обяснява, че спецификаторът «is emitted as-written» [5]: излиза така, както си го написал. Ако Node ще зарежда servicio.js, това пишеш.

Така става тук, не е закон. TypeScript има опция, rewriteRelativeImportExtensions, която сменя относителен .ts с .js в това, което генерира [24]. Шаблонът не я включва, така че спецификаторът излиза непокътнат.

Това е същото правило като при псевдонима, видяно от другата страна. С module: nodenext TypeScript те предупреждава за това. Измерено, като се махне разширението:

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

За псевдонима не предупреждава, защото paths съществува точно за да му каже «вярвай, някой друг ще го разреши».

Защо тестовете се компилират отделно?

Защото един tsconfig описва една-единствена програма, а кодът и тестовете му са две: едната се доставя, а другата — не.

Ръководството на TypeScript го казва така: «A single tsconfig.json can only represent a single environment» [7], и слага тестовия код в списъка на това, което заслужава свой. Страницата му за project references разказва какво ставаше с един-единствен файл за src/ и test/: «It was possible for the implementation files to import the test files», и не можеха да се компилират заедно «without having src appear in the output folder name» [8].

Измерихме го на проект с три файла, с "include": ["src", "test"]:

  • С rootDir: ./src не се компилира: error TS6059: File '…/test/reporte.test.ts' is not under 'rootDir'.
  • Без rootDir се компилира, но изходът сменя формата си: dist/src/main.js и dist/test/reporte.test.js. Тестовете пътуват в това, което се доставя, а node dist/main.js отговаря Error: Cannot find module '…/dist/main.js'.
  • А main.ts импортира файл от test/, без никой да се оплаче. Компилира се и тръгна.

Шаблонът го разделя на три файла, всеки със своя работа:

Шаблонът го разделя на три файла, всеки със своя работа
ФайлКакво включваКакво прави
tsconfig.jsonsrc/Базата: проверява, не записва
tsconfig.build.jsonсъщото (наследява с extends [2])Записва dist/: .js файловете и техните .d.ts (файлове, които описват типове и не изпълняват код)
test/tsconfig.jsontest/Проверява тестовете; никога не записва

Финото е в третия. Тестовете импортират #reporte, точно като main.ts. Но този tsconfig живее в друга папка и не включва src/, така че TypeScript стига до dist/reporte.d.ts, файла с типове, който е оставило изграждането. Измерено: в програмата на тестовете не влиза нито един файл от src/. Тестовете виждат това, което вижда всеки, който ползва компилирания код.

Има цена и същата страница я казва: с няколко отделни tsconfig «you end up always running tsc twice» [8]. За това съществуват project references. С пет файла двойното пускане не се усеща; README-то казва кога да се направи тази стъпка.

Как се пускат тестовете?

Node ги изпълнява направо от .ts файловете, като маха типовете; а те зареждат вече компилирания код, през същата врата #.

Node изпълнява файлове на TypeScript, които съдържат само изтриваем синтаксис: изтрива анотациите на типовете, но не преобразува TypeScript, който би трябвало да генерира нов JavaScript. Сменя типовете с интервали и «no type checking is performed» [3]. Шаблонът го ползва за тестовете, с изпълнителя, който Node вече носи (node --test), без да инсталира нищо повече. Тъй като Node зарежда тези файлове както са, там относителните импорти носят .ts: ./comun/servidor.ts. Правилото не се е променило: пишеш това, което Node ще зареди.

npm test прави три неща: изгражда dist/, проверява типовете на тестовете и ги пуска. Отчетът завършва така:

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

Това са 46 теста и се броят там. С шаблон, който не намира нито един файл, node --test излиза с 0 и ℹ tests 0 (измерено): зелено, което не е тествало нищо.

Шаблонът в скрипта, "test/**/*.test.ts", също не е излишен. По подразбиране Node пуска всеки файл, който е под папка test/ [11]. Измерено без шаблона: помощният сървър излиза като още един тест, ✔ test/comun/servidor.ts, и отчетът казва 47.

Един от тестовете, programa.test.ts, изпълнява dist/main.js в друг процес. Той е единственият, който вижда това, което никоя проверка на типове не вижда: дали Node намира всеки модул при стартиране.

За какво се грижи проверителят, което един шаблон не бива да учи погрешно?

Срок, който покрива цялата заявка, таван за това, което се чете, и грешки, които никога не повтарят URL адреса.

Това, което идва от servicios.json, е unknown, докато не се провери поле по поле: типовете не пазят това, което влиза при изпълнение. Тялото на всеки отговор се чете до 64 KiB и се освобождава. Нито едно съобщение не повтаря URL адрес, който може да носи токен. Махнахме всяка защита в копие, една по една: и 26-те направиха теста си червен.

А къде отива импортът на Иван?

В main.ts, с името #revisar; а името — в package.json.

В сряда Иван и Лусия изтриха реда с paths. Обявиха #revisar в "imports" и смениха един ред в main.ts. Редакторът продължи да допълва. И този път това, което компилаторът приемаше, беше същото, което Node щеше да търси.

Как разбирам, че границата съществува?

Защото един скрипт я пресича нарочно при всяка промяна: засажда псевдонима и изисква да се компилира и да не тръгне, по точната причина.

herramientas/probar-frontera.sh работи във временно копие. Компилира и стартира една и съща програма два пъти. Между двата пъти се сменя само как main.ts импортира модула revisar и кой обявява това име:

  1. Контрола, с проекта такъв, какъвто е. main.ts импортира #revisar. Трябва да се компилира и да тръгне. Ако не, експериментът е зле сглобен или проектът ти вече съдържа импорт, който Node не разрешава, и скриптът спира в червено.
  2. Нарушение. Засажда се @/revisar в paths и main.ts го импортира. Трябва да се компилира, с непокътнат псевдоним в dist/main.js, и да не тръгне, с ERR_MODULE_NOT_FOUND.

Ето реалния изход:

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

Защо контролата? Защото експеримент, който очаква само червено, става «зелен» и когато се провали по грешната причина. Счупихме го по седем начина и седемте излязоха в червено. Три казват много: със зареждач, който разрешава псевдонима, ❌ ARRANCÓ; с псевдоним, който tsc отхвърля, казва, че нарушението не се е компилирало и че това «no demuestra la frontera»; с псевдонима, засаден в истинския проект, спира на контролата.

CI в GitHub е написан да пуска типовете, тестовете и границата с най-новата LTS версия на Node и с 26.13.0, а границата и в macOS със системния /bin/bash, при всяка промяна и всеки понеделник. Ако публичното хранилище остане 60 дни без активност, GitHub изключва пускането в понеделник [22].

Кои са пет чести грешки?

И петте идват от едно и също: да вярваш, че tsconfig.json командва там, където не командва.

1. Псевдоним в paths, който никой не разрешава при изпълнение

Компилира се, редакторът го приема, а Node не тръгва.

Това е грешката на Иван [1][2]. paths сам по себе си не е грешка: служи, когато бъндлър разрешава псевдонима и само трябва да се предупреди TypeScript [1]. Това, което се проваля, е да се ползва сам. Издава го ERR_MODULE_NOT_FOUND, грешката на Node за модул, който не е успял да разреши [12], с Cannot find package: Node е решил, че @/revisar е инсталиран пакет. За частен псевдоним, без зареждач и без бъндлър, стандартният изход е "imports" [1][3].

2. Относителни пътища без разширение, с разрешаване, което ги прощава

С moduleResolution: bundler TypeScript приема просто ./servicio; Node — не.

bundler казва на TypeScript, че бъндлър ще разреши импортите. Ръководството предупреждава, че тази опция «is infectious, allowing code that only works in bundlers to be produced» [7]. Измерено в шаблона, с bundler и импорт без разширение: компилира се, а при стартиране:

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

Ако програмата ти върви в Node такава, каквато излиза от tsc, опцията е nodenext, която проверява по правилата на Node [5][6].

3. Един-единствен tsconfig.json за кода и тестовете

Или тестовете пътуват в dist/, или програмата сменя мястото си, или кодът накрая импортира тест.

Това са трите симптома, измерени по-горе [8]. От TypeScript 6 rootDir вече не се отгатва: това е папката на tsconfig, а бележките към тази версия описват симптома точно така: «files being written to ./dist/src/index.js instead of ./dist/index.js» [9]. Изходът е по един tsconfig за всяка програма [7].

4. Копиране на tsconfig.json от стар урок

TypeScript 7 премахна опции, които хиляди уроци още учат.

TypeScript 7 излезе на 8 юли 2026 г. [10]. Това е нов компилатор и това, което версия 6 отбелязваше като остаряло, сега е грешка. Обявлението го казва за двете най-копирани опции: «baseUrl is no longer supported», и същото за moduleResolution: node [10]. Измерено със 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 беше вечният партньор на paths. Ако псевдонимът ти зависеше от двете, половината вече не съществува. Преди да копираш tsconfig, виж от коя година е.

5. Да вярваш, че щом Node го е изпълнил, типовете са наред

Node маха типовете. Не ги проверява.

Това, че Node изпълнява .ts, не го прави компилатор [3]. Измерено с файл от два реда, const limite: number = "cinco"; и един console.log: Node отпечатва cinco и излиза с 0. tsc, със същия файл:

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

Това са два инструмента с две задачи. Затова npm test проверява типовете, преди да пусне тестовете.

5. Да вярваш, че щом Node го е изпълнил, типовете са наред
ГрешкаКакво я издаваИзточник
1. Псевдоним в paths без някой, който да го разрешиERR_MODULE_NOT_FOUND: Cannot find package '@/…' при стартиране[1][2][3]
2. Без разширение, с bundlerCannot find module '…/dist/servicio' при стартиране[5][6][7]
3. Един tsconfig за всичкоdist/src/main.js, тестове в dist/ или TS6059[7][8][9]
4. tsconfig от стар урокTS5102, TS5108[9][10]
5. «Node го изпълни»Зелено от Node с червено от tsc[3]

Упражнение: можеш ли да накараш програмата да се компилира, но да не тръгва?

Ще засадиш псевдонима на Иван, ще видиш, че компилаторът го приема, ще опиташ да го поправиш там, където изглежда логично, и ще видиш как скриптът те предупреждава.

Трябва ти Node 26.13 или по-нов (node --version), който вече носи npm, плюс Git и bash; около 20 минути.

  • В Linux Mint 22 не ползвай apt install nodejs: Mint 22 е базиран на Ubuntu 24.04 [19], който идва с Node 18.19 [18], и с него тестовете не тръгват: Could not find '…/test/**/*.test.ts' (измерено). Инсталирай Node с nvm, както казва неговото README [20]:
  sudo apt install curl
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.0/install.sh | bash

Отвори друг терминал (в същия nvm още не се намира; измерено) и пусни nvm install 26. Урок 1 от курса по TypeScript го обяснява стъпка по стъпка. - В macOS — същото, с nvm. - Ако вече имаш nvm, nvm install 26. В Windows ползвай WSL.

Стъпка 1. Клонирай и провери, че всичко е зелено.

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

Какво трябва да видиш: ℹ pass 46 с ℹ fail 0 и, в края на скрипта, ✅ frontera: se sostiene.

Ползвай този клонинг само за упражнението. Така всяка промяна, която видиш в него, е от упражнението.

Стъпка 2. Предвиди, преди да пипаш. Ще обявиш псевдонима @/revisar в tsconfig.json и ще го ползваш в main.ts. Запиши три неща: компилира ли се? Тръгва ли? А ако освен това обявиш @/revisar в package.json?

Стъпка 3. Засади псевдонима. Тези два реда работят еднакво в Linux и в macOS; оставят копие .bak на всеки файл.

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 завършва без нито една грешка. node не тръгва. Редът, който има значение:

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

Стъпка 4. Поправи го там, където изглежда логично. Щом Node чете package.json, обяви там същото име:

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

Същото ERR_MODULE_NOT_FOUND. Node търси в "imports" само имената, които започват с #; останалите ги третира като пакети. А скриптът става червен, без да стигне до втората стъпка:

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

Това е контролата в действие: проектът ти вече съдържа импорт, който Node не разрешава.

Стъпка 5. Дай му името, което Node наистина търси.

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

Отговаря revisor 0.1.0. Редът с paths още е в tsconfig.json и не потрябва: вече никой не го ползва.

Стъпка 6. Върни само това, което пипна. Упражнението промени три файла. Преди да ги върнеш, виж какво се е променило в тях:

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

Трябва да видиш две промени: реда с paths в tsconfig.json и реда "@/revisar" в package.json. src/main.ts не се появява: в стъпка 5 остана такъв, какъвто беше. Ако видиш нещо друго, то е твое: запази го, преди да продължиш.

Ако е само това от упражнението, върни тези три файла. git restore пипа само пътищата, които му даваш [25]:

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

Границата пак става зелена, а git status показва единственото, което остава: копията, които направи sed.

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

Пази ги, докато не си сигурен, че не ти трябват. После ги изтрий едно по едно, с rm -i src/main.ts.bak tsconfig.json.bak, който пита преди всяко. Не ползвай команда, която чисти цялата папка: ще отнесе и бележките ти.

Как разбираш, че си се справил: пусна седем пъти и видя три резултата. Зелено, четири пъти: двата в стъпка 1, програмата в стъпка 5 и границата в стъпка 6. Червено от Node, ERR_MODULE_NOT_FOUND, два пъти: стъпки 3 и 4. И червеното на скрипта, «el control NO arrancó», в стъпка 4. Ако в стъпка 3 npm run build покаже TS2307, редът със sed не е намерил "outDir": "./dist", в tsconfig.json: провери дали не си го редактирал. Ако в стъпка 5 грешката остава, провери дали main.ts казва "#revisar".

За да отидеш по-далеч (по желание): псевдонимът, който Иван искаше, почти съществува. От Node 24.14 едно име може да започва с #/ [4], а TypeScript го разбира от версия 6 [9]. Пусни npm pkg set 'imports.#/*=./dist/*.js', смени импорта в main.ts на "#/revisar" и компилирай отново. Преди това предвиди: тръгва ли? Отговор: да, revisor 0.1.0 (измерено). Върни всичко като в стъпка 6: git diff -- package.json src/main.ts, за да видиш двете промени, и git restore package.json src/main.ts.

Ключови изводи

Три въпроса, които да зададеш на своето хранилище тази седмица.

  1. Има ли paths в твоя tsconfig.json? Ако има, кой инструмент разрешава тези имена, когато програмата работи? Ако отговорът е «никой», вече знаеш какво ще стане.
  2. Какво има в твоя dist/? Ако намериш тестов файл, кодът и тестовете ти се компилират като една програма.
  3. Пуска ли някой тест компилираната програма така, както би я пуснал сървърът? Ако никой, кой пръв ще разбере за импорт, който Node не намира?

Какво следва?

В Go границата я пази инструментът; в Python — инсталацията; в Rust — компилаторът; в TypeScript — Node при стартиране. В Java границите вече не са файлове: те са слоеве.

Месец по-късно на Иван му се падна първото API на Java, със Spring Boot. Четири папки с имена на слоеве: api, facade, service, repository. Промяната му беше ново поле в един отговор.

Пипна четири файла, за да премести една-единствена стойност.

Във facade имаше метод, който само извикваше друг. За какво е слой, който не прави нищо? В част 5: API на слоеве, какво може да знае всеки слой за другите и кога facade е нужна и кога не е.

Шаблонът и курсът

  • Шаблон: github.com/HabilMX/estructura-typescript. Използва се като шаблон в GitHub или се клонира [21]. README-то обяснява всяка папка и всеки tsconfig, какво не включва, кога да добавиш всяко нещо и как да махнеш примера. Кодът е под MIT; текстът и обясненията — под CC BY-SA 4.0.
  • Версии: Node 26.13 или по-нов. 26 е най-новата LTS линия [16]. В engines package.json обявява минимума, който шаблонът поддържа: 26.13.0, първата LTS от тази линия. Това е минимум, не списъкът на тестваното. TypeScript 7.0.2, актуалната версия към 17 ноември [17], фиксирана в package-lock.json, който npm ci спазва, без да го променя [13][14]. Тестван е с Node 26.13.1 и 26.13.0 в macOS arm64 (и със системния /bin/bash) и в Linux arm64 (контейнер ubuntu:24.04). Linux x86-64 още не е тестван. С Node 24.22.0 също тръгна, с предупреждение EBADENGINE от npm (измерено): engines предупреждава, не забранява [15]. CI е написан за LTS версията на всяка седмица и 26.13.0 в Linux, и LTS в macOS [23].
  • Курсът по TypeScript на Hábil: ако модулите, tsconfig.json или тестовете с Node са нови за теб, урок 7 ги обяснява от нулата: Курс по TypeScript · Урок 7, Модули, тестове и качество.

Пиша от това, което виждаме всеки ден в Hábil, където изграждаме системи за банки, застраховане и компании в Мексико. Ако в работата или в университета ти и колегите ти попаднете на хранилище, за което никой не знае откъде да го хване, да поговорим: habil.mx

Какво прави Hábil?

Учим на програмиране със същото, с което изграждаме: тестван, обяснен и отворен код.

Тази поредица идва от същото място като нашите курсове. Курсът по TypeScript тръгва от това, че типовете не съществуват при изпълнение: учи какво защитават, какво не защитават и как се валидират данните, идващи отвън, и го публикуваме отворено, с лиценз Creative Commons; урок 7 обяснява модулите, тестовете и качеството, които използва шаблонът от тази статия. А в каталога има още курсове по програмиране, безплатни и с тестван и обяснен стъпка по стъпка код.

Разгледай Курса по TypeScript и каталога Курсове по програмиране.

Ако екипът ти наследи система, за която никой не знае откъде да я хване, или трябва да изгради такава, която да може да се поддържа и занапред, правим и това: разгледай Изграждане на система по поръчка. Поискай първи разговор, без заплащане. В него преглеждаме дали си струва да се настрои това, което екипът ти вече има, да се ползва продукт или да се изгради, и какво би получил екипът във всеки случай. Пиши ни в WhatsApp.

Източниците са проверени на 17 ноември 2026 г. Цитатите на английски са възпроизведени дословно.

Източници

  1. TypeScript, «Modules - Reference»: «paths», «paths does not affect emit», «package.json "imports" and self-name imports» и «Implied and enforced options», The TypeScript Handbook. https://www.typescriptlang.org/docs/handbook/modules/reference.html
  2. TypeScript, «TSConfig Reference»: paths и extends. https://www.typescriptlang.org/tsconfig/
  3. Node.js v26.13.1, «Modules: TypeScript»: «Type stripping» и «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» и «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» (бележки към версията): «rootDir now defaults to .», «types now defaults to []», «Deprecated: --baseUrl» и «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 юли 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, версия latest: 7.0.2. https://registry.npmjs.org/typescript/latest
  18. Launchpad (Canonical), пакет nodejs, публикуван в 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

Вашата дейност среща ли тези предизвикателства?

Да обсъдим вашия проект

Предпочитате имейл? Пишете ни на hola@habil.mx