ts-node для TypeScript: полное руководство с примерами

Что такое ts-node и зачем он нужен?

ts-node — это TypeScript-движок для Node.js, который позволяет выполнять файлы TypeScript напрямую, без предварительной компиляции в JavaScript. Он работает как REPL (Read-Eval-Print Loop) и как инструмент командной строки, обеспечивая бесшовную интеграцию TypeScript в экосистему Node.js.

Основные сценарии использования:

• Быстрая разработка и прототипирование — не нужно ждать компиляции каждого изменения
• Запуск скриптов — выполнение TypeScript-файлов в продакшене (с осторожностью)
• Тестирование — запуск тестов, написанных на TypeScript
• Интерактивная разработка — REPL-режим для экспериментов с TypeScript
• Миграция проектов — постепенный переход с JavaScript на TypeScript

В отличие от стандартного подхода (компиляция через tsc и запуск через node), ts-node делает процесс разработки более плавным и быстрым.

Установка ts-node

Установка производится через npm (пакетный менеджер Node.js). Для Python-разработчиков: это аналог pip install.

# Глобальная установка (доступна везде)
npm install -g ts-node

# Локальная установка (рекомендуется для проектов)
npm install --save-dev ts-node

# Установка вместе с TypeScript (если ещё не установлен)
npm install --save-dev ts-node typescript

# Для работы с определёнными версиями TypeScript
npm install --save-dev ts-node@10.9.2 typescript@5.3.3

После установки проверьте версию:

ts-node --version
# Вывод: v10.9.2

Быстрый старт с примером кода

Создайте файл hello.ts:

// hello.ts
interface Greeting {
    name: string;
    age: number;
}

function greet(person: Greeting): string {
    return `Привет, ${person.name}! Тебе ${person.age} лет.`;
}

const user: Greeting = { name: "Алексей", age: 30 };
console.log(greet(user));

Запустите без компиляции:

ts-node hello.ts
# Вывод: Привет, Алексей! Тебе 30 лет.

Для сравнения, обычный способ занял бы два шага:

tsc hello.ts    # компиляция в hello.js
node hello.js   # запуск скомпилированного файла

Основные методы и функции ts-node

1. ts-node [file.ts] — Базовый запуск файла

Описание: Основная команда для выполнения TypeScript-файла. ts-node автоматически компилирует и выполняет код.

Параметры:

• file.ts — путь к файлу TypeScript
• --project или -P — путь к tsconfig.json
• --transpile-only — только транспиляция (быстрее, но без проверки типов)

Пример:

# Обычный запуск
ts-node app.ts

# С указанием конфигурации
ts-node --project tsconfig.prod.json app.ts

# Только транспиляция (быстрее)
ts-node --transpile-only app.ts

2. ts-node --eval — Выполнение кода из строки

Описание: Позволяет выполнить TypeScript-код, переданный как строка, без создания файла.

Параметры:

• -e или --eval — строка с кодом TypeScript
• -p или --print — вывести результат выполнения

Пример:

# Простое выражение
ts-node -e "console.log('Hello from ts-node!')"

# С использованием TypeScript-фич
ts-node -e "
interface User { name: string }
const user: User = { name: 'Мария' };
console.log(user.name);
"

# С выводом результата
ts-node -p "1 + 2"

3. ts-node --compiler-options — Переопределение опций компилятора

Описание: Позволяет временно переопределить настройки TypeScript-компилятора без изменения tsconfig.json.

Параметры:

• -C или --compiler-options — JSON-строка с опциями

Пример:

# Включить строгий режим
ts-node --compiler-options '{"strict": true}' app.ts

# Изменить целевую версию ECMAScript
ts-node --compiler-options '{"target": "ES2020"}' app.ts

# Комбинированные опции
ts-node -C '{"module": "commonjs", "esModuleInterop": true}' app.ts

4. ts-node --transpile-only — Быстрая транспиляция без проверки типов

Описание: Выполняет только транспиляцию (преобразование TypeScript в JavaScript) без проверки типов. Значительно ускоряет выполнение, но не гарантирует типобезопасность.

Параметры:

• -T или --transpile-only — флаг для включения режима

Пример:

# Быстрый запуск (рекомендуется для разработки)
ts-node --transpile-only app.ts

# Сравнение скорости
time ts-node app.ts          # ~2.5 сек
time ts-node -T app.ts       # ~0.8 сек

5. ts-node --type-check — Принудительная проверка типов

Описание: Включает полную проверку типов даже если в tsconfig.json указано "transpileOnly": true.

Параметры:

• --type-check — флаг для включения проверки

Пример:

# Принудительная проверка типов
ts-node --type-check app.ts

# В tsconfig.json может быть:
# {
#   "ts-node": {
#     "transpileOnly": true
#   }
# }
# Но --type-check переопределит это

6. ts-node --project — Указание пользовательского tsconfig.json

Описание: Позволяет использовать альтернативный файл конфигурации TypeScript.

Параметры:

• -P или --project — путь к директории с tsconfig.json или сам файл

Пример:

# Структура проекта:
# /project
#   /config
#     tsconfig.server.json
#   /src
#     server.ts

# Запуск с кастомной конфигурацией
ts-node --project config/tsconfig.server.json src/server.ts

# Или указать директорию
ts-node -P config src/server.ts

7. ts-node --require — Подключение модулей перед выполнением

Описание: Позволяет загрузить дополнительные модули (например, для настройки окружения) перед выполнением основного файла.

Параметры:

• -r или --require — путь к модулю для предварительной загрузки

Пример:

# Загрузка dotenv для переменных окружения
ts-node -r dotenv/config app.ts

# Несколько модулей
ts-node -r tsconfig-paths/register -r module-alias/register app.ts

8. ts-node --cwd-mode — Режим текущей рабочей директории

Описание: Указывает ts-node искать tsconfig.json в текущей рабочей директории, а не в директории с выполняемым файлом.

Параметры:

• --cwd-mode — флаг для включения режима

Пример:

# Структура:
# /project
#   tsconfig.json
#   /scripts
#     deploy.ts

# Запуск из корня проекта
cd /project
ts-node --cwd-mode scripts/deploy.ts
# tsconfig.json будет взят из /project, а не из /project/scripts

9. ts-node --show-config — Отображение итоговой конфигурации

Описание: Показывает, какую конфигурацию ts-node будет использовать для выполнения файла. Полезно для отладки.

Параметры:

• --show-config — флаг для отображения конфигурации

Пример:

# Показать конфигурацию
ts-node --show-config app.ts

# Вывод (пример):
# {
#   "compilerOptions": {
#     "target": "ES2019",
#     "module": "commonjs",
#     "strict": true,
#     "esModuleInterop": true,
#     "skipLibCheck": true
#   },
#   "transpileOnly": false,
#   "files": true,
#   "pretty": true,
#   "compiler": "typescript"
# }

10. ts-node --log-error — Подробное логирование ошибок

Описание: Включает детальное логирование ошибок TypeScript, включая стектрейсы компилятора.

Параметры:

• --log-error — флаг для включения подробного логирования

Пример:

# Запуск с подробными ошибками
ts-node --log-error app.ts

# Полезно при сложных ошибках типов
ts-node --log-error --type-check app.ts

Реальный практический пример использования

Рассмотрим создание REST API сервера на TypeScript с использованием ts-node для разработки.

Структура проекта:

/my-api
  /src
    index.ts
    routes.ts
    types.ts
  tsconfig.json
  package.json

Файл src/types.ts:

export interface User {
    id: number;
    name: string;
    email: string;
}

export interface ApiResponse {
    success: boolean;
    data: T;
    error?: string;
}

Файл src/routes.ts:

import { Router, Request, Response } from 'express';
import { User, ApiResponse } from './types';

const router = Router();

// In-memory база данных
const users: User[] = [
    { id: 1, name: 'Иван', email: 'ivan@example.com' },
    { id: 2, name: 'Мария', email: 'maria@example.com' }
];

router.get('/users', (req: Request, res: Response) => {
    const response: ApiResponse = {
        success: true,
        data: users
    };
    res.json(response);
});

router.get('/users/:id', (req: Request, res: Response) => {
    const id = parseInt(req.params.id);
    const user = users.find(u => u.id === id);
    
    if (!user) {
        const response: ApiResponse = {
            success: false,
            data: null,
            error: 'Пользователь не найден'
        };
        res.status(404).json(response);
        return;
    }
    
    const response: ApiResponse = {
        success: true,
        data: user
    };
    res.json(response);
});

export default router;

Файл src/index.ts:

import express from 'express';
import userRoutes from './routes';

const app =