Установка TypeScript через npm и проверка версии

TypeScript это пакет npm с именем typescript. Установите его в проект и проверьте, что он работает:

npm install --save-dev typescript
npx tsc --version

Version 7.0.2

Пакет предоставляет команду tsc, то есть компилятор TypeScript. Для установки нужны Node.js и npm (он входит в Node.js); скачайте Node.js с nodejs.org или через пакетный менеджер системы и проверьте его командой node --version.

Чтобы попробовать TypeScript, ничего устанавливать не нужно. Этот блок компилируется и запускается прямо в браузере:

function add(a: number, b: number): number {
    return a + b;
}

console.log(`2 + 3 = ${add(2, 3)}`);

Установка TypeScript в проект

Рекомендуемый способ это локальная установка как dev-зависимости проекта:

mkdir hello-ts
cd hello-ts
npm init -y
npm install --save-dev typescript

npm install --save-dev typescript (короткая форма npm i -D typescript) помещает компилятор в node_modules и записывает его в package.json:

{
    "devDependencies": {
        "typescript": "^7.0.2"
    }
}

Это dev-зависимость, потому что компилятор нужен только для сборки кода, а не для его запуска. Любой, кто клонирует проект и выполнит npm install, получит ту же версию компилятора.

Чтобы запустить локальный компилятор, добавьте перед ним npx: эта команда ищет программы в node_modules/.bin:

npx tsc --version

В скриптах package.json можно писать tsc без npx, потому что npm добавляет node_modules/.bin в PATH для скриптов:

{
    "scripts": {
        "build": "tsc",
        "typecheck": "tsc --noEmit"
    }
}

Тогда npm run build компилирует проект, а npm run typecheck проверяет типы, не записывая файлов.

Проверка версии TypeScript

npm ls typescript

hello-ts@1.0.0 /home/ana/hello-ts
└── typescript@7.0.2

Если npx tsc --version и tsc --version выводят разные версии, у проекта свой компилятор, а глобальный старее или новее. Для сборки проекта важна версия проекта.

Глобальная установка TypeScript

Глобальная установка даёт команду tsc в любом терминале, без npx:

npm install -g typescript
tsc --version

В macOS и Linux это может завершиться ошибкой прав доступа EACCES, если Node.js установлен для всей системы. Установка Node.js через менеджер версий вроде nvm или fnm решает проблему, а sudo npm install -g использовать не рекомендуется.

Используйте глобальную команду для быстрых экспериментов. Для настоящего проекта держите и локальную установку: тогда package.json фиксирует версию, и обновление глобального компилятора не изменит сборку проекта.

Установка через pnpm, Yarn или Bun

Любой пакетный менеджер JavaScript устанавливает один и тот же пакет:

pnpm add -D typescript
yarn add -D typescript
bun add -d typescript

Запускайте компилятор через pnpm tsc, yarn tsc или bunx tsc.

Создание tsconfig.json через tsc --init

Файл tsconfig.json помечает папку как проект TypeScript и хранит параметры компилятора. Сгенерируйте его:

npx tsc --init

Created a new tsconfig.json

You can learn more at https://aka.ms/tsconfig

Сгенерированный файл (TypeScript 7) включает strict и ещё несколько проверок, использует "module": "nodenext" и "target": "esnext" и содержит закомментированные строки для rootDir и outDir. Раскомментируйте их, чтобы компилятор читал из src и писал в dist:

{
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist",
        "module": "nodenext",
        "target": "esnext",
        "types": [],
        "strict": true
    }
}

Это сокращённый вид; в настоящем файле больше параметров, и у каждого есть комментарий. Что они делают, объясняет страница о tsconfig. Повторный запуск npx tsc --init в той же папке завершается ошибкой error TS5054: A 'tsconfig.json' file is already defined, так что ваши настройки он никогда не перезапишет.

Компиляция первого файла

Создайте src/index.ts:

function greet(name: string): string {
    return `Hello, ${name}!`;
}

const names = ["Ada", "Grace", "Linus"];
for (const name of names) {
    console.log(greet(name));
}

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

npx tsc
node dist/index.js

Hello, Ada!
Hello, Grace!
Hello, Linus!

npx tsc без аргументов читает tsconfig.json, проверяет типы во всех включённых файлах и записывает результат в dist. Со сгенерированными настройками для каждого файла вы получите index.js, а также index.d.ts (объявления типов) и файлы .map (карты исходников).

О результате полезно знать две вещи:

• По умолчанию ошибки типов не останавливают вывод. tsc сообщает об ошибках, завершается с ненулевым кодом и всё равно записывает JavaScript. Задайте "noEmitOnError": true, чтобы при ошибках ничего не записывалось.
• Если есть tsconfig.json, не передавайте имена файлов. npx tsc src/index.ts завершается ошибкой error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Запускайте просто npx tsc или добавьте --ignoreConfig, если действительно хотите скомпилировать один файл с настройками по умолчанию.

Режим наблюдения

--watch (коротко -w) оставляет компилятор работать и перекомпилирует код при каждом изменении файла:

npx tsc --watch

06:28:22 AM - Starting compilation in watch mode...

06:28:22 AM - Found 0 errors. Watching for file changes.

Держите его открытым в терминале рядом с редактором. Остановить можно через Ctrl+C.

Установка конкретной версии TypeScript

Укажите версию после @:

npm install --save-dev typescript@7.0.2   # an exact version
npm install --save-dev typescript@6       # the newest 6.x
npm install --save-dev typescript@latest  # the newest stable release
npm install --save-dev typescript@next    # nightly builds of the next version

TypeScript 6 это последняя версия, компилятор которой написан на JavaScript. Некоторым инструментам, которые вызывают JavaScript API компилятора, она всё ещё нужна; об этом и об обновлении рассказывает страница о TypeScript 7.

Настройка редактора

В VS Code поддержка TypeScript встроена: откройте файл .ts, и вы получите подчёркивание ошибок, автодополнение, типы при наведении и переименование без установки чего-либо. Для скорости TypeScript 7 в редакторе команда TypeScript выпускает отдельное расширение, которое переключает VS Code на нативный языковой сервер TypeScript 7. WebStorm и другие IDE JetBrains поддерживают TypeScript из коробки, а Neovim, Vim, Emacs, Zed и Sublime Text используют языковой сервер TypeScript через поддержку LSP.

Частые ошибки установки

This is not the tsc command you are looking for. Вы выполнили npx tsc в папке без установленного TypeScript, и npx скачал устаревший пакет, который случайно называется tsc. Установите настоящий через npm install --save-dev typescript.

tsc: command not found или 'tsc' is not recognized as an internal or external command в Windows. TypeScript не установлен глобально или глобальная папка npm не входит в PATH. Используйте npx tsc в проекте с локальной установкой или установите глобально и откройте новый терминал.

error TS2591: Cannot find name 'process' (или require; __dirname даёт TS2304). Типы собственных API Node.js находятся в отдельном пакете. Установите его через npm install --save-dev @types/node, затем добавьте "types": ["node"] в compilerOptions: TypeScript 7 больше не подгружает автоматически все установленные пакеты @types.

error TS5011: The common source directory of 'tsconfig.json' is './src'. Файлы лежат в src, и вы задали outDir, но не rootDir. Добавьте "rootDir": "./src".

error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. npm init -y записывает "type": "commonjs" в package.json, поэтому конфигурация из tsc --init ("module": "nodenext" с verbatimModuleSyntax) считает каждый файл .ts модулем CommonJS, где import и export запрещены. Замените на "type": "module" и пишите относительные импорты с расширением .js: import { add } from "./math.js".