Ты вызываешь element.startViewTransition(), чтобы карточка товара на странице плавно перестроилась без рывка всего экрана, и добавляешь window.fetchLater(), чтобы браузер гарантированно отправил аналитику при закрытии вкладки. В свежем Chrome всё работает как часы: анимация идёт мягко, отложенный запрос встаёт в очередь, в консоли тишина. И в ту же секунду компилятор TypeScript 6 отказывается собирать проект, подчёркивая оба вызова красным: метода startViewTransition якобы нет у HTMLElement, а про fetchLater объект Window вообще не слышал.
Перед нами странное противоречие: браузер, которым пользуются миллионы людей, штатно исполняет стандартизированный код, а система типов уверяет, будто ты допустил ошибку. Почему официальный словарь типов годами не замечает новых возможностей веб-платформы и как открытый пакет modern-web-types от инженера Google Филипа Уолтона возвращает строгую типизацию без ручных костылей?
Политика двух движков: почему стандартный словарь типов отстаёт от браузеров
Откуда TypeScript знает о возможностях браузера? Компилятор сверяет код со словарём определений DOM (lib.dom.d.ts) из пакета @typescript/lib-dom. Его генерирует сборщик Microsoft TypeScript-DOM-lib-generator на базе машиночитаемых спецификаций W3C. Но на входе стоит фильтр — правило двух браузерных движков: новый стандарт попадает в TypeScript только после реализации минимум в двух независимых движках из трёх (Blink в Chrome и Edge, Gecko в Firefox, WebKit в Safari).
Это напоминает осторожного издателя карт, который не наносит на схему новый мост через реку, пока рядом не построят второй такой же. По мосту уже ездят машины, но навигатор упрямо кричит, что ты едешь по воде.
Авторы компилятора хотели отсечь сырые черновики, но, как показал Филип Уолтон в статье Modern Web Types, на которую обратила внимание Библиотека фронтендера, эта перестраховка вредит коду. Пока один браузер уже выпустил стандарт в релиз, а второй только ставит задачу в план, разработчики выбирают из двух плохих решений:
- Заглушки
@ts-ignoreилиas any. Написав(window as any).fetchLater('/analytics'), ты гасишь ошибку в IDE, но отключаешь проверку типов. Опечатка в параметреactivateAfterпройдёт сборку и выстрелит в продакшене. - Ручные декларации (
declare global). Команда создаёт свойglobal.d.tsи дописывает методы вHTMLElementилиPerformanceEntry. Такие файлы часто неполны, кочуют между проектами, а когда второй браузер внедрит фичу, самописные типы конфликтуют со стандартной библиотекой при обновлении TypeScript.
Как устроен modern-web-types: генерация из спецификаций W3C и тысяча скрытых типов
Вместо кустарных файлов Уолтон задействовал тот же промышленный конвейер, которым пользуется Microsoft. Если сравнить ручную поддержку .d.ts и modern-web-types, первый подход держится на внимательности программиста, а второй работает как автоматическое зеркало спецификаций W3C.
Пакет modern-web-types запускает оригинальный TypeScript-DOM-lib-generator поверх базы стандартов W3C (w3c/webref), снижая порог включения с двух браузерных движков до одного стабильного релиза. Каждую неделю сценарий GitHub Actions сверяет генератор со свежими данными W3C и открывает Pull Request при выходе новых браузерных API.
Снижение планки всего на один движок открывает больше тысячи определений, которые раньше были невидимы для стандартного компилятора. Когда я заглянул в сводную таблицу репозитория, меня особенно впечатлил масштаб этого разрыва:
| Категория определений | Среда DOM | Потоки WebWorker |
|---|---|---|
| Новые интерфейсы | 433 | 144 |
| Псевдонимы типов (type aliases) | 96 | 35 |
| Новые глобальные объекты | 223 | 56 |
| Новые свойства и методы в существующих интерфейсах | 311 | 64 |
Ключевая строка здесь, на мой взгляд, последняя: 311 расширений в DOM и 64 в воркерах дополняют базовые интерфейсы Document, Element, Navigator, Request и PerformanceEntry. Именно они возвращают точные сигнатуры для анимаций element.startViewTransition(), поля scripts в PerformanceEntry (Long Animation Frame API для поиска медленных скриптов) и отложенных запросов fetchLater().
Установка и настройка: npm-алиас для @typescript/lib-dom и флаг libReplacement
Поскольку сгенерированные файлы повторяют структуру встроенной библиотеки TypeScript, менять импорты в коде не нужно. При проверке браузерного проекта компилятор ищет пакет @typescript/lib-dom. Достаточно установить modern-web-types под этим именем через npm-алиас командой npm install --save-dev @typescript/lib-dom@npm:modern-web-types.
Однако на свежем тулчейне легко угодить в конфигурационную ловушку. Вслед за изменениями, которые мы разбирали в статье о переходе компилятора TypeScript на нативный стек и настройке алиасов совместимости, ради скорости сборки автоматический поиск внешних подмен отключили по умолчанию. Поэтому в TypeScript 6 и новее нужно явно включить флаг "libReplacement": true в tsconfig.json (а для фоновых потоков Web Worker при необходимости указать "types": ["modern-web-types/webworker"]).
Настроим tsconfig.json для нашего проекта на TypeScript 6, чтобы компилятор подхватил расширенный словарь DOM:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"libReplacement": true,
"strict": true
}
}
После сохранения конфига компилятор переключается со стандартной заглушки на modern-web-types. Красные подчёркивания под element.startViewTransition() и window.fetchLater() пропадают, а редактор подсказывает точные типы аргументов по спецификации W3C. Когда второй браузер поддержит стандарт и он войдёт в официальный TypeScript, конфликтов не возникнет — сигнатуры созданы одним генератором.
Безопасность в продакшене: почему статические типы не отменяют проверку фич в рантайме
Зелёная сборка в терминале легко создаёт иллюзию, будто код безопасно заработает у любого посетителя сайта. На самом деле, как мы выясняли в разборе того, почему статические типы не заменяют рантайм-валидацию и стираются при сборке, все типы исчезают при компиляции в JavaScript. Если вызвать window.fetchLater() напрямую, в Safari или Firefox страница упадёт с ошибкой TypeError.
По-моему, это самый трезвый подход к веб-стандартам. Старое правило двух движков всё равно не спасало от падений: метод из двух браузеров точно так же ронял приложение в третьем. Зато возможности одного движка (как долго было с метриками Core Web Vitals — LargestContentfulPaint, PerformanceEventTiming, LayoutShift, fetchpriority и speculationrules) полностью безопасны при прогрессивном улучшении (Progressive Enhancement). Это как эскалатор рядом с обычной лестницей: где он работает — едем с комфортом, где нет — идём по ступенькам.
Вернёмся к нашей карточке товара и аналитике. Добавим проверку наличия методов во время выполнения (Feature Detection), чтобы задействовать плавную анимацию и батчинг в Chrome без поломок в остальных браузерах:
function updateCard(element: HTMLElement, updateDOM: () => void) {
if ('startViewTransition' in element) {
element.startViewTransition(() => updateDOM());
} else {
updateDOM();
}
}
function sendExitBeacon(data: Record<string, unknown>) {
if ('fetchLater' in window) {
window.fetchLater('/analytics', {
method: 'POST',
body: JSON.stringify(data),
activateAfter: 5000,
});
} else {
navigator.sendBeacon('/analytics', JSON.stringify(data));
}
}
Условия 'startViewTransition' in element и 'fetchLater' in window одновременно защищают приложение в браузере и сужают тип для компилятора. Внутри блока if TypeScript строго проверяет колбэк анимации и число миллисекунд в activateAfter, страхуя от опечаток в редакторе. В рантайме пользователи Chrome получают плавный переход и отложенную отправку метрик, а в Safari и Firefox код без ошибок уходит в ветку else. Чтобы не пропускать такие проверки, Уолтон рекомендует сочетать автотесты в браузерах с линтерами совместимости под стандарт Web Platform Baseline.
Разделяй статическую проверку и исполнение кода: modern-web-types избавляет от слепых зон компилятора и костылей as any, а проверка доступности метода в рантайме гарантирует стабильную работу сайта в любом браузере.



