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.