Ошибка "Unknown file extension .ts" при запуске TypeScript через Node.js

Почему возникает ошибка и как её исправить

Node.js по умолчанию понимает только JavaScript (.js, .mjs, .cjs). TypeScript — это надстройка над JS, и Node.js не умеет исполнять .ts файлы напрямую. Ошибка "Unknown file extension .ts" возникает именно поэтому.

Есть два основных способа запустить TypeScript-код:

• Компиляция в JS — преобразовать .ts в .js через компилятор TypeScript (tsc), затем запустить .js файл
• Запуск "на лету" — использовать специальные инструменты (ts-node, tsx), которые компилируют и запускают .ts файлы в одной команде

Способ 1: Компиляция через tsc (рекомендуется для новичков)

Установите TypeScript локально в проект:

npm init -y
npm install typescript --save-dev

Создайте файл конфигурации tsconfig.json (даже для одного файла он нужен):

npx tsc --init

В сгенерированном файле укажите настройки:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

Создайте папку src и поместите туда ваш index.ts:

// src/index.ts
const greeting: string = "Hello, World!";
console.log(greeting);

Скомпилируйте и запустите:

npx tsc
node dist/index.js

В папке dist появится скомпилированный index.js, который Node.js выполнит без ошибок.

Способ 2: Запуск через ts-node (быстрый старт)

Установите ts-node:

npm install ts-node --save-dev

Запустите файл напрямую:

npx ts-node src/index.ts

ts-node сам скомпилирует и выполнит код. Для работы с ES-модулями может потребоваться флаг:

npx ts-node --esm src/index.ts

Способ 3: Использование tsx (современная альтернатива)

tsx — более быстрый и простой инструмент:

npm install tsx --save-dev
npx tsx src/index.ts

tsx работает "из коробки" и с CommonJS, и с ES-модулями без лишних настроек.

Важные советы для новичков

• Всегда устанавливайте TypeScript локально в проект (--save-dev), а не глобально — это избежит конфликтов версий
• Создавайте tsconfig.json даже для простых проектов — это упростит настройку в будущем
• Не пытайтесь запускать node index.ts — это не сработает. Используйте npx tsc для компиляции или npx ts-node/npx tsx для прямого запуска
• Добавьте в package.json скрипты для удобства:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsx src/index.ts"
  }
}

Теперь вы можете запускать:

npm run build     # компиляция
npm run start     # запуск скомпилированного кода
npm run dev       # быстрый запуск через tsx

Ошибка "Unknown file extension .ts" больше не появится — вы будете работать с .js файлами или использовать инструменты, которые умеют обрабатывать TypeScript.

node --experimental-strip-types index.ts

{
  "scripts": {
    "start": "node --experimental-strip-types index.ts"
  }
}

npm install -g tsx

tsx index.ts