TypeScript strict у великому проекті: поетапна міграція без зупинки розробки
Почему нельзя просто включить strict
В проекте на несколько сотен файлов "strict": true выдаёт тысячи ошибок. Исправить их одной веткой — значит неделями держать конфликтующий со всеми PR, который никто не может нормально отревьюить. Остановить разработку на это время тоже нельзя. Нужна схема, при которой новый код сразу пишется строго, а старый переводится по частям.
Что входит в strict
Флаг strict — это набор отдельных проверок, каждую можно включать независимо:
noImplicitAny— параметры и переменные без типа, который нельзя вывести, становятся ошибкой, а неany.strictNullChecks—nullиundefinedперестают быть допустимыми значениями любого типа. Обычно даёт больше всего ошибок и больше всего пользы.strictFunctionTypes,strictBindCallApply,strictPropertyInitialization,noImplicitThis,alwaysStrict,useUnknownInCatchVariables.
Ещё один полезный флаг, не входящий в strict, — noUncheckedIndexedAccess: доступ arr[i] и record[key] возвращает T | undefined. Его стоит включать отдельным этапом в конце.
Стратегия 1: флаги по одному
Самая простая схема для проектов среднего размера:
- 1.Включить флаги, дающие мало ошибок (
alwaysStrict,strictBindCallApply,noImplicitThis), — обычно это десятки правок. - 2.
noImplicitAny: ошибки механические, исправляются быстро, частично автоматически. - 3.
strictNullChecks— основной этап. Его удобнее делать по второй стратегии. - 4.Включить
strict: trueи убрать отдельные флаги.
Каждый шаг — отдельный небольшой PR, который легко влить.
Стратегия 2: строгий конфиг для переведённых файлов
Основной tsconfig.json остаётся нестрогим, рядом появляется строгий, который проверяет только переведённую часть:
// tsconfig.strict.json
{
"extends": "./tsconfig.json",
"compilerOptions": { "strict": true, "noEmit": true },
"include": [
"src/shared/lib/**/*",
"src/entities/user/**/*",
"next-env.d.ts"
]
}Здесь важная ловушка. tsc проверяет не только файлы из include, но и всё, что они импортируют. Если переведённый модуль импортирует непереведённый, ошибки из непереведённого тоже попадут в вывод. Поэтому переводят снизу вверх (сначала утилиты и модели, потом то, что их использует), а вывод фильтруют по списку переведённых путей:
// scripts/check-strict.mjs
import { execSync } from "node:child_process";
import { readFileSync } from "node:fs";
const cfg = JSON.parse(readFileSync("tsconfig.strict.json", "utf8"));
const prefixes = cfg.include.map((p) => p.replace(/\*\*.*$/, ""));
let out = "";
try {
execSync("npx tsc -p tsconfig.strict.json --pretty false", { encoding: "utf8" });
} catch (e) {
out = e.stdout ?? "";
}
const errors = out.split("\n").filter((l) => /error TS\d+/.test(l) && prefixes.some((p) => l.startsWith(p)));
for (const e of errors) console.error(e);
process.exit(errors.length ? 1 : 0);Скрипт идёт в CI обязательной проверкой. Добавил папку в include — она защищена от регресса навсегда.
Есть готовый инструмент для того же подхода с обратной логикой: typescript-strict-plugin позволяет включить strict для всего проекта, пометив непереведённые файлы комментарием // @ts-strict-ignore, и проверять это в CI его командой tsc-strict. Удобно, когда переведённых файлов уже больше половины.
Стратегия 3: храповик по числу ошибок
Если важнее не дать ситуации ухудшаться, чем быстро всё исправить, достаточно считать ошибки полного строгого прогона и не позволять их числу расти:
COUNT=$(npx tsc -p tsconfig.strict-all.json --noEmit --pretty false | grep -c "error TS" || true) BASELINE=$(cat .strict-baseline) if [ "$COUNT" -gt "$BASELINE" ]; then echo "strict errors: $COUNT > baseline $BASELINE"; exit 1 fi echo "$COUNT" > .strict-baseline # закоммитьте уменьшение в том же PR
Каждый PR либо не меняет число, либо уменьшает его. Инструмент betterer делает то же самое аккуратнее: отслеживает ошибки по файлам, а не только общее число, поэтому исправление в одном месте не маскирует новую ошибку в другом.
Как исправлять, чтобы не стало хуже
Цель — не убрать красное подчёркивание, а сделать типы правдивыми.
- `!` (non-null assertion) превращает ошибку компиляции в ошибку рантайма. Допустим, только когда гарантия действительно есть, и её можно объяснить. Иначе — явная проверка с ранним выходом.
- `any` → `unknown` для данных извне (JSON, ответы API,
catch (e)), а дальше сужение проверками или схемой валидации. - `@ts-expect-error` вместо `@ts-ignore`. Первый падает, когда ошибки больше нет, и не даёт временным подавлениям жить вечно. Всегда с комментарием, почему.
- Опциональные поля в моделях. Если поле в базе
NOT NULL, оно не должно быть?в типе только потому, что так проще инициализировать объект в тесте.
Правила ESLint @typescript-eslint/no-explicit-any и @typescript-eslint/no-non-null-assertion в режиме ошибки для переведённых каталогов не дают вернуть старые привычки.
Организация работы
- Маленькие PR по одной папке, без смешивания с функциональными изменениями — их легко ревьюить и откатывать.
- Новые файлы сразу в строгую зону. Иначе непереведённая часть растёт быстрее, чем уменьшается.
- Начинайте с кода, где ошибки дороже всего: работа с деньгами, права доступа, парсинг внешних данных.
Когда не стоит усердствовать
Скрипты миграций, одноразовые утилиты и прототипы, которые скоро удалят, переводить не нужно — исключите их из строгой зоны. И если проект в режиме поддержки без активной разработки, храповика достаточно: он не даст стать хуже, не требуя отдельного проекта по миграции.