re:re:actable
Урок 072 минуты чтения

Как Node.js запускает TypeScript без сборки и какие ограничения?

На этой странице
Кратко

Современный Node.js умеет запускать TypeScript-код в ограниченном режиме, удаляя erasable types. Это удобно для scripts и простых cases, но не заменяет полноценный TypeScript toolchain во всех проектах.

Вопрос

Как Node.js запускает TypeScript без сборки и какие у этого ограничения?

Что значит запуск TypeScript в Node.js?

Node.js может обрабатывать .ts файлы, если код использует синтаксис, который можно стереть без трансформации runtime-семантики.

Пример:

type User = {
  id: string;
  email: string;
};
 
function greet(user: User) {
  return `Hello ${user.email}`;
}
 
console.log(greet({
  id: '1',
  email: 'admin@example.com',
}));

Типы удаляются, JavaScript выполняется.

Что не стоит ожидать?

Node.js не является полноценным tsc:

  • не делает type checking;
  • не компилирует все TypeScript features;
  • не заменяет build pipeline;
  • не решает path aliases так, как bundler/tsconfig;
  • не проверяет типы в CI.

Type checking все равно делают:

tsc --noEmit

Когда это полезно?

  • CLI scripts;
  • dev tooling;
  • маленькие Node utilities;
  • one-off migration scripts;
  • prototypes;
  • tests без build step.

Когда лучше обычный build?

  • production service;
  • decorators;
  • complex tsconfig;
  • path aliases;
  • bundling;
  • minification;
  • framework build;
  • strict CI pipeline.

Практический workflow

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "start": "node src/index.ts"
  }
}

Если проект использует нестандартные TypeScript transforms, оставь tsx, ts-node, Vite, SWC или tsc build.

Что важно помнить

  • Node.js удаляет аннотации типов (type stripping), но не проверяет типы — для проверки нужен tsc --noEmit.
  • Синтаксис, требующий генерации кода (enum, namespace с кодом, parameter properties), не поддерживается без флага трансформации.
  • В импортах указывают расширение .ts, импорты типов — через import type.
  • Для production обычно по-прежнему собирают код или используют tsx/esbuild.

Мини-шпаргалка

  • Node.js может запускать часть TypeScript без сборки.
  • Type stripping не равно type checking.
  • Для проверки типов нужен tsc --noEmit.
  • Для сложного backend build pipeline пока безопаснее явная сборка.

Документация

Node.js: Modules — TypeScript.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам