re:re:actable
Урок 031 минута чтения

declare global - антипатерн

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

declare global расширяет глобальные типы. Это мощный инструмент, но как привычный способ "добавить что-то куда угодно" он становится антипаттерном: зависимости становятся скрытыми, а типы - менее предсказуемыми.

Вопрос

Почему declare global может быть антипаттерном?

Что делает declare global

declare global {
  interface Window {
    appVersion: string;
  }
}
 
window.appVersion;

Такой код добавляет поле в глобальный интерфейс Window.

В чем риск

Глобальное расширение действует на весь проект. Другой файл может начать использовать window.appVersion, хотя не видно, где это поле реально создается.

console.log(window.appVersion.toUpperCase());

Тип есть, но runtime-значения может не быть.

Когда это оправдано

declare global уместен для настоящих глобальных контрактов: расширения Window, тестовых матчеров, глобальных переменных окружения или интеграции с библиотекой.

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      API_URL: string;
    }
  }
}

Лучшая альтернатива

Если зависимость не глобальная по смыслу, передавай ее явно.

type AppConfig = {
  appVersion: string;
};
 
function render(config: AppConfig) {
  return config.appVersion;
}

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

  • declare global расширяет глобальную область и влияет на весь проект — изменения сложно отследить.
  • Глобальные типы оправданы для Window, переменных окружения и полифилов; бизнес-типы лучше импортировать из модулей.
  • Файл с declare global должен быть модулем (содержать export {}).
  • Для типов env-переменных в Vite используют interface ImportMetaEnv в vite-env.d.ts.

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

  • declare global меняет типы для всего проекта.
  • Глобальные типы легко создают скрытые зависимости.
  • Тип не гарантирует наличие значения на runtime.
  • Используй только для действительно глобальных контрактов.

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

TypeScript: Global augmentation, Vite: Env Variables and Modes.

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

Поиск

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