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

s

Первый шаг: не ставить глобально (расхожая ошибка)

Стандартный совет, который вы найдёте в большинстве гайдов — npm install -g typescript. С профессиональной точки зрения это антипаттерн. Глобальная установка приводит к двум проблемам:

Профессиональный подход — всегда устанавливать TypeScript локально как dev-зависимость: npm install --save-dev typescript, а для запуска использовать npx tsc. Только так вы избежите неожиданных расхождений в код-базе.

Файл tsconfig.json: тонкие настройки, о которых молчат

Стандартная конфигурация из tsc --init содержит около 30 закомментированных параметров. Опытные специалисты акцентируют внимание не на очевидных strict: true, а на менее известных, но критичных для production-проектов.

Параметр exactOptionalPropertyTypes

Распространённая ловушка в TypeScript — неявное допущение, что undefined в объекте эквивалентен отсутствию ключа. Включение exactOptionalPropertyTypes ломает эту иллюзию: если вы пишете property?: string, то присваивание obj.property = undefined вызовет ошибку компиляции. Это заставляет вас явно обрабатывать необязательность, что особенно важно при работе с API.

Директива noPropertyAccessFromIndexSignature

Когда в проекте есть индексные сигнатуры ([key: string]: any), TypeScript разрешает обращаться через точку: obj.someProp. С noPropertyAccessFromIndexSignature вы вынуждены использовать только квадратные скобки (obj['someProp']). Это не про стиль — это про безопасность: вы сразу видите, что работаете с динамической структурой, а не с известным полем. Редкая, но эффективная защита от ошибок рефакторинга.

Ошибка новичков: игнорировать skipLibCheck

В небольших проектах часто включают skipLibCheck: true, чтобы ускорить компиляцию. На продакшене это недопустимо — вы слепо доверяете библиотекам, которые могут содержать несовместимые объявления типов. Вместо этого используйте skipLibCheck: false и точечно исправляйте несовместимости через paths или override в package.json.

Настройка деклараций: почему declarationMap обязателен

Типичный совет: генерируйте .d.ts-файлы (declaration: true). Профессиональная хитрость — всегда добавлять declarationMap: true. Без него при отладке в IDE вы не сможете перейти к исходному коду библиотеки из объявления типа. С declarationMap вы получаете source maps для типов, что в 2026 году стало стандартом де-факто в крупных монорепозиториях.

Оркестрация сборки: не зацикливайтесь на TSC для бандлинга

Типичное заблуждение — пытаться использовать tsc для финальной сборки приложения. tsc — транспайлер, а не бандлер. Он не умеет объединять модули в один файл (без дополнительных флагов, которые ломают дерево зависимостей). Профессиональная практика: настроить TypeScript только для проверки типов (tsc --noEmit), а сборку передать Vite, esbuild или Webpack. Это даёт выигрыш в скорости и корректную обработку CSS/JSON-модулей.

Non-obvious nuance: порядок files vs include

Многие указывают include: ['src//'], но забывают, что files имеет приоритет. Если вы перечислите файлы в files руками, TypeScript проигнорирует include. Лучшая стратегия — не использовать files вообще. Вместо этого применяйте include + exclude, а для явного исключения тестов — exclude: ['/.spec.ts']. Это избавит от эффекта «а сам файл почему-то не скомпилировался».

Про привидения типов: @ts-expect-error лучше, чем @ts-ignore

Даже в 2026 году многие копируют старые примеры с // @ts-ignore. Профессионалы настаивают на // @ts-expect-error, потому что если ошибка исчезнет (например, после обновления библиотеки), @ts-expect-error выдаст предупреждение в следующем релизе компилятора. @ts-ignore же молча останется, создавая «мёртвый» код, который маскирует реальные проблемы.

Итоговый совет: при установке и настройке TypeScript не копируйте конфиги из репозиториев «для новичков». Отталкивайтесь от strict: true и последовательно добавляйте флаги из списка --strict*, тестируя каждый на вашей кодовой базе. Только так вы получите предсказуемый компилятор, а не «магический» инструмент, который то работает, то нет.

Добавлено: 07.05.2026