TypeScript: установка и настройка

Установка TypeScript в проект включает добавление пакета typescript как dev-зависимость, создание tsconfig.json с настройками компилятора и настройку скриптов для компиляции и проверки типов.

Зачем нужно

Правильная начальная настройка TypeScript определяет строгость проверок, целевой JavaScript, структуру модулей и совместимость с инструментами. Плохо настроенный tsconfig приводит к тому, что TypeScript пропускает реальные ошибки или мешает написанию кода.

Где используется

  • Новый проект с нуля — установка и базовая конфигурация
  • Добавление TypeScript в существующий JS-проект
  • Настройка для конкретной среды: Node.js, браузер, библиотека
  • Монорепозитории с несколькими tsconfig

Основной контент

Установка

# В существующий проект
npm install -D typescript

# Новый Node.js-проект с нуля
mkdir my-project && cd my-project
npm init -y
npm install -D typescript @types/node

# Создать tsconfig.json
npx tsc --init

Минимальный tsconfig.json для Node.js

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

tsconfig.json для браузерного проекта (Vite/bundler)

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"]
  },
  "include": ["src"]
}

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

my-project/
├── src/
│   ├── index.ts
│   └── utils/
│       └── format.ts
├── dist/            ← генерируется tsc
├── node_modules/
├── package.json
└── tsconfig.json

package.json — скрипты

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

Установка типов для Node.js и популярных библиотек

# Node.js встроенные типы
npm install -D @types/node

# Express
npm install express && npm install -D @types/express

# Lodash
npm install lodash && npm install -D @types/lodash

strict mode — что включает

// "strict": true включает все эти опции:
{
  "strictNullChecks": true,         // null и undefined не совместимы с другими типами
  "strictFunctionTypes": true,      // строгая проверка функциональных типов
  "strictBindCallApply": true,      // строгая проверка bind/call/apply
  "strictPropertyInitialization": true, // свойства класса должны быть инициализированы
  "noImplicitAny": true,            // запрет неявного any
  "noImplicitThis": true,           // запрет неявного this: any
  "alwaysStrict": true              // "use strict" в каждом файле
}

Частые ошибки

  • Не включать strict: true — без него многие полезные проверки отключены; включайте сразу.
  • Не указывать rootDir и outDir — компилятор будет выводить файлы рядом с источниками, захламляя src/.
  • Забыть @types/node — без них нет типов для process, fs, path и других встроенных модулей Node.
  • Коммитить dist/ — сборка должна происходить в CI; добавьте dist/ в .gitignore.

Связанные темы

Ресурсы