re:re:actable
Урок 053 минуты чтения

Как отключить проверку типов: @ts-ignore, @ts-expect-error и @ts-nocheck

На этой странице
Кратко

Комментарий // @ts-ignore отключает проверку типов для следующей строки, // @ts-expect-error делает то же, но сообщит об ошибке, если проверка на строке на самом деле проходит. // @ts-nocheck отключает проверку для всего файла. Все они — крайняя мера: они скрывают реальные проблемы. Предпочтительный порядок: исправить тип → сузить тип → @ts-expect-error с комментарием, почему.

Вопрос

Как отключить проверку типов для конкретной строки кода? Почему @ts-ignore считается антипаттерном и чем его заменить?

Директивы

// @ts-ignore
const result: number = legacyLib.compute(); // ошибка скрыта, даже если строку потом починят
 
// @ts-expect-error — библиотека возвращает неверный тип, issue #123
const value: string = brokenTypes.getValue();
 
// @ts-nocheck — в начале файла: проверка всего файла отключена
// @ts-check — в JS-файле: включить проверку
ДирективаОбластьЕсли ошибки нет
@ts-ignoreследующая строкамолчит
@ts-expect-errorследующая строкасама становится ошибкой «Unused directive»
@ts-nocheckвесь файл—
@ts-checkвесь JS-файлвключает проверку

Почему @ts-ignore — антипаттерн

  • скрывает все ошибки строки, включая новые, появившиеся позже;
  • после обновления библиотеки ошибка может исчезнуть, а игнор останется навсегда;
  • маскирует реальные баги: undefined, неверные аргументы;
  • распространяется по кодовой базе и обесценивает проверку типов.

@ts-expect-error лучше: когда проблема будет исправлена, компилятор напомнит удалить директиву. Его же используют в тестах типов, чтобы проверить, что неверный код не компилируется.

Чем заменить

// 1. исправить тип
const user = data as unknown as User; // плохо
const user2 = UserSchema.parse(data); // хорошо: проверка в runtime + тип
 
// 2. сузить тип
if (typeof value === "string") {
  value.toUpperCase();
}
 
// 3. уточнить типы библиотеки
declare module "legacy-lib" {
  export function compute(): number;
}
 
// 4. non-null assertion — если точно знаете, что значение есть
const root = document.getElementById("root")!;

Политика в проекте

Линтер @typescript-eslint/ban-ts-comment позволяет запретить @ts-ignore и @ts-nocheck, а @ts-expect-error разрешить только с описанием:

{
  "@typescript-eslint/ban-ts-comment": ["error", { "ts-expect-error": "allow-with-description" }]
}

Что важно помнить

  • Директивы отключают только проверку типов, но не синтаксические ошибки.
  • as, ! и any тоже отключают проверку, только менее заметно — относитесь к ним так же осторожно.
  • При миграции JS → TS временный @ts-nocheck на файлах — нормальная практика, если есть план их исправить.
  • На ревью каждый @ts-expect-error должен иметь объяснение и, по возможности, ссылку на задачу.

Мини-шпаргалка

  • @ts-ignore — скрыть ошибку строки (избегать).
  • @ts-expect-error — скрыть и напомнить, когда ошибка исчезнет.
  • @ts-nocheck — весь файл, только для миграции.
  • Сначала исправить или сузить тип.
  • Линтер ban-ts-comment контролирует использование.

Документация

TypeScript: Comments directives, typescript-eslint: ban-ts-comment.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам