@types
Тема дорожной карты · Node.js
Декларации типов — это файлы определений TypeScript (.d.ts), описывающие публичный API JavaScript-библиотек, чтобы TypeScript мог выполнять проверку типов и автодополнение в редакторе без необходимости писать саму библиотеку на TypeScript. Область npm @types в реестре npm (поддерживаемая DefinitelyTyped) является основным источником поддерживаемых сообществом деклараций типов для экосистемы Node.js — установка @types/node добавляет типы для всех встроенных модулей Node.js, @types/express добавляет типы для middleware Express, а @types/supertest типизирует библиотеку HTTP-тестирования supertest. Декларации типов устанавливаются как devDependencies, поскольку они потребляются только компилятором TypeScript и не присутствуют во время выполнения в JavaScript-среде Node.js. Современные npm-пакеты, написанные на TypeScript, поставляют собственные декларации через поля types или exports в package.json, что делает отдельные пакеты @types/ излишними — примеры включают prisma, ioredis, pino и zod. Понимание того, как TypeScript разрешает декларации типов — проверяя types в package.json, затем index.d.ts, и затем возвращаясь к @types/ — важно для диагностики ошибок отсутствующих типов в TypeScript-проектах Node.js и для создания npm-пакетов, корректно работающих как в JavaScript, так и в TypeScript-потребительских проектах.
Как это работает
@types добавляет статическую типизацию к JavaScript через TypeScript-компилятор (tsc) или runtime-трансформеры (tsx, ts-node, swc, esbuild). tsconfig.json контролирует строгость; strict: true — современный дефолт, ловит много багов на сборке. Type-декларации для npm-пакетов — из пакета или DefinitelyTyped (@types/*). Современные проекты компилируют через SWC/esbuild для скорости, типы проверяют отдельно tsc --noEmit в CI.
Когда применять
TypeScript — в каждый новый Node-проект: кривая обучения маленькая, выигрыш большой (ловит опечатки, безопасные рефакторы, IDE-автокомплит). Даже однофайловые скрипты выигрывают. Тонкий runtime-трансформер (tsx) в dev для мгновенного фидбека; реальная проверка типов (tsc --noEmit) — в CI. Избегайте any и @ts-ignore — это против смысла.
Типичные ошибки
Ловушки @types: уход в any когда типы мешают (рефакторьте, не кастуйте); tsc для компиляции в CI (медленно — отдавайте swc/esbuild, tsc — только проверка типов); расходящиеся runtime + type-check пайплайны пропускают ошибки; забыли обновить @types/node вместе с major Node; гонка за strict: false "чтобы быстрее" (баги вернутся позже).