Отладка Wippy FE

Если что-то сломалось, начните отсюда. В каждом разделе перечислены самые частые причины в порядке вероятности и конкретная проверка в DevTools для каждой.

Пустой экран при загрузке

1. Сначала посмотрите Console:

  • Failed to resolve module specifier 'vue' — страница вынесла во внешние зависимости спецификатор, которого нет в её активной import map. В hosted-режиме изучите import map, которую фактически раздаёт целевой релиз Web Host; в host-less-режиме изучите map в app.html. Сверяйте каждую внешнюю зависимость Rollup именно с этой map, а не с предполагаемым каноническим списком пакетов или порядком слияния.
  • Proxy globals not found (или ваши импорты из @wippy-fe/proxy возвращают undefined) — proxy.js / dev-proxy.js не загрузился до запуска скрипта вашего приложения, поэтому среда выполнения так и не установила свои внутренние глобальные переменные. Проверьте, что dev-proxy.js подключён с data-role="@wippy/scripts" в app.html.
  • Молчаливое зависание (ни ошибок, ни приложения) — конфигурация вставляется синхронно как window.__WIPPY_APP_CONFIG__ до запуска proxy.js, поэтому геттеры @wippy-fe/proxy разрешаются (или выбрасывают Proxy globals not found) немедленно; они не ждут SetConfig. Настоящее зависание означает, что среда выполнения так и не смонтировалась — либо proxy.js / dev-proxy.js не загрузился и не установил свои глобальные переменные (см. пункт Proxy globals not found выше), либо, в host-less-режиме, dev-оверлей находится в состоянии ожидания, потому что вы не нажали Accept. Убедитесь, что появилась FAB (плавающая кнопка) dev-оверлея; если нет — скрипт прокси не загрузился. (Рукопожатие SetConfig / GetConfig относится только к ручному встраиванию на уровне хоста iframe.html?waitForCustomConfig, а не к hosted- или host-less-микрофронтенду.)

2. Посмотрите вкладку Network:

  • Убедитесь, что dev-proxy.js (host-less) или proxy.js (hosted) загрузился со статусом 200.
  • Если 404: src в вашем теге <script data-role="@wippy/scripts"> указывает на неверный URL.

3. Проверьте, что среда выполнения установила свои глобальные переменные (внутренняя диагностика):

// Внутренние глобальные переменные — код приложения их никогда не читает; это лишь
// консольная проверка того, что среда выполнения прокси смонтировалась.
// Код приложения/веб-компонента использует `import { ... } from '@wippy-fe/proxy'`.
window.$W              // должен быть объектом, а не undefined
window.__WIPPY_APP_API__ // разрешённый экземпляр прокси — присутствует после установки средой выполнения

Геттеры @wippy-fe/proxy читают эти глобальные переменные (window.__WIPPY_APP_API__ — живой экземпляр хоста); это не связано с тем, как разрешается URL модуля. Если глобальные переменные есть, а импорты падают, изучите активную import map и сетевой ответ для точного спецификатора @wippy-fe/proxy. Исправьте map или решение о внешних зависимостях в той среде, которая раздаёт страницу; не делайте выводов о hosted-поведении по успешной загрузке в host-less-режиме.

Веб-компонент не появляется

1. Проверьте три условия:

Выполните на своём бэкенде:

curl /api/public/components/list?auto_register=true

tag_name вашего компонента должен присутствовать в ответе. Если нет:

  • отсутствует announced: true в _index.yaml → добавьте его
  • отсутствует auto_register: true → добавьте его
  • компонент не зарегистрирован в wippy/views → проверьте зависимости модуля

2. Посмотрите Console:

customElements.get('your-tag-name')  // undefined означает, что элемент не был зарегистрирован

3. Посмотрите вкладку Network:

  • Отфильтруйте по URL index.js вашего компонента
  • URL должен содержать ?declare-tag=your-tag-name — именно так элемент регистрирует себя
  • Если в URL нет параметра ?declare-tag=: вызов define(import.meta.url, MyElement) не попал во входной чанк. Это проблема preserveEntrySignatures: false — см. Система сборки

Запросы к API падают / 401

1. В host-less-режиме:

  • Заглушка dev-token в конфигурации прокси не является настоящими учётными данными — от реального бэкенда она всегда получит 401
  • Откройте dev-оверлей → найдите поле auth.token в JSON-конфигурации → вставьте настоящий bearer-токен
  • Убедитесь, что APP_API_URL в конфигурации оверлея указывает на работающий бэкенд (не на localhost, если ваш бэкенд в другом месте)

2. В hosted-режиме:

  • Обрабатывайте 401 вызовом host.handleError('auth-expired', error) — это запускает поток повторной аутентификации хоста
  • Если все запросы к API отдают 401: проверьте, что токен сессии хоста корректно вставляется (прокси делает это автоматически через api.get(...))

Тема выглядит неправильно

1. В host-less-режиме: Dev-оверлей стартует с отключёнными по умолчанию инъекциями themeConfig, primevue, markdown и iframe. Ваше приложение будет отображаться без какого-либо платформенного CSS, пока вы их не включите.

Откройте FAB dev-оверлея → включите нужные инъекции CSS → отметьте "Auto-accept on reload".

2. Сравните полную действующую цепочку:

Непустого токена недостаточно. Используйте различимые значения, чтобы сброс к стандартной палитре или случайный алиас семейства сразу бросался в глаза:

css_variables:
  "--p-primary": "#dc2626"
  "--p-secondary": "#7c3aed"
  "--p-accent": "#0d9488"
  "--p-danger": "#be123c"
  "--p-success": "#15803d"
  "--p-warn": "#c2410c"
  "--p-info": "#0369a1"
  "--p-help": "#9333ea"
  "--theme-diagnostic-sentinel": "#123456"

Затем сравнивайте в таком порядке:

  1. Действующая настроенная карта: изучите config.theming.global.cssVariables и подтвердите базу плюс активные замены @light / @dark.
  2. Корень страницы: прочитайте точное значение токена через getComputedStyle(document.documentElement).getPropertyValue(name).trim().
  3. Хост веб-компонента: прочитайте тот же токен из getComputedStyle(customElement).
  4. Внутренний корень веб-компонента: прочитайте его из getComputedStyle(customElement.shadowRoot.querySelector('[data-wippy-theme-root]')).
  5. Отрисованный семантический цвет: поставьте background-color: var(--p-<family>-color) на пробный элемент и сравните вычисленный backgroundColor; это физически разрешает color-mix().

Повторите в режимах Auto-light, Auto-dark, принудительный Light и принудительный Dark. Для каждого настроенного семейства проверьте его базу, все оттенки 50–950, color, contrast-color, hover-color и active-color; также проверьте прямое переопределение оттенка/алиаса, токен поверхности и контрольное значение-сентинел. Значения на странице, на хосте и во внутреннем корне должны совпадать.

Интерпретируйте первое расхождение: неверная действующая карта означает проблему конфигурации/слияния; неверный корень страницы — компиляции/инъекции переменных; корректная страница, но неверный хост веб-компонента — распространения из хоста; корректный хост веб-компонента, но неверный внутренний корень — моста принудительной темы или локальных умолчаний; равные токены, но неверный отрисованный цвет — неверного потребляющего селектора или семантического алиаса.

3. Специфика веб-компонентов:

  • Если платформенные умолчания отсутствуют, проверьте, что hostCssKeys включает 'themeConfigUrl'.
  • Если хост корректен, но внутренний корень сбрасывается к стандартным значениям, убедитесь в актуальности @wippy-fe/webcomponent-core; не копируйте палитру в CSS компонента.
  • Если компоненты PrimeVue отображаются без стилей, добавьте 'primeVueCssUrl' в hostCssKeys.

Полный конвейер инъекции см. в Оформление: микрофронтенд-приложения или Оформление: веб-компоненты.

Адресная строка хоста не обновляется

Переносимые микрофронтенд-приложения должны использовать фабрику createAppRouter() из @wippy-fe/router. Пакет владеет обоими направлениями синхронизации с хостом; код приложения не должен воспроизводить обвязку router.afterEach и @history.

Проверка:

import { createAppRouter } from '@wippy-fe/router'
import { config } from '@wippy-fe/proxy'
import { routes } from './routes'

const router = createAppRouter(routes, {
  initialPath: config.context?.route ?? '/',
})

Если адресная строка хоста всё равно не обновляется, убедитесь, что текущее семейство @wippy-fe/router установлено согласованно и что никакая локальная обёртка не подменяет фабрику. В host-less-режиме вкладка Monitor dev-оверлея показывает маршрут, о котором сообщает пакет.

Локально работает, а под хостом ломается

1. Проверьте document.baseURI:

document.baseURI  // должен быть <url>/<base_path>/ из вашей записи реестра

Если пусто или неверно: тег <base> не был вставлен. Проверьте, что base_path в _index.yaml соответствует фактической структуре директорий вашей сборки.

2. Проверьте глобальные переменные прокси (внутренняя диагностика):

window.__WIPPY_PROXY_CONFIG__  // внутренняя — должна существовать в режиме размещения в iframe

Undefined означает, что прокси не был вставлен до запуска вашего приложения. Код приложения никогда не читает её напрямую; см. Прокси и изоляция § Внутреннее устройство.

3. Убедитесь в наличии base: '' в vite.config.ts: Без base: '' Vite выдаёт абсолютные пути к ресурсам. Приложение прекрасно загружается на вашем локальном dev-сервере (который раздаёт из /), но отдаёт 404 при раздаче из поддиректории CDN.

4. Несовпадение import map: Заново загрузите <version-tag>/import-map.json из релиза Web Host, зафиксированного в fe_facade_url. Замените весь объект imports в host-less app.html и перегенерируйте внешние зависимости Vite из всех его ключей. Не удаляйте host-less map и не правьте отдельные записи. Включайте вновь импортированный точный спецификатор в бандл только тогда, когда он отсутствует в загруженной map.

Использование логгера как инструмента отладки

Вывод logger.debug() и logger.info() появляется в Console браузера во время разработки, а не только в продакшн-транспортах. Используйте его для трассировки последовательности загрузки:

import { logger, config, host, api } from '@wippy-fe/proxy'

export function createMainApp() {
  logger.debug('App bootstrap started')
  logger.debug('Host services resolved', { hasConfig: !!config })
  // ... используйте config, host, api напрямую
}

logger.captureException(error) в dev-режиме также пишет в Console, а в продакшене перехватывается системой перехвата ошибок хоста.