Source maps и релизы фронтенда
Продакшен-сборка фронтенда минифицирована, поэтому без source maps стек ошибки выглядит как at Xe (index-B3x9.js:1:48211) — понятно только, что что-то сломалось. Когда сборка загружает source maps в NablOps, та же ошибка показывается по исходному коду: at renderCard (src/app/StackCard.tsx:42:7), с кодом вокруг строки, а для упавшего компонента React — где в ваших компонентах это случилось.
Карты загружаются при сборке и в бандл не попадают: посетители сайта их не видят. Ниже — как подключить загрузку для Vite и других сборщиков, как обойтись без секретов в CI и что показывает вкладка «Релизы».
Зачем source maps для ошибок фронтенда
- Стек по исходникам. Файл, функция, строка и код вокруг неё вместо строки минифицированного бандла.
- Компоненты React. Стек компонентов из
ErrorBoundaryтоже переводится в файлы и строки исходников. - Точная группировка. С картами одна ошибка в Chrome, Safari и Firefox — одна запись: учитываются функции и файлы вашего кода, а не текст сообщения, который у каждого браузера свой. Подробнее — в статье ошибки фронтенда на React.
Если карт для релиза нет, на странице ошибки появляется пометка «Нет source map для релиза …», а в покрытии проекта — шаг «Нет source maps у релиза …».
Как загружать source maps в Vite
npm install -D @nablops/vite-plugin// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nablops } from '@nablops/vite-plugin';
export default defineConfig({
plugins: [react(), nablops()],
});При каждой сборке плагин:
- Определяет релиз: опция
release, иначе переменнаяNABL_RELEASE, иначе короткий хэш коммита git, иначе время сборки. Релиз попадает в бандл, поэтому вinitего передавать не нужно. - Включает скрытые карты (
build.sourcemap: 'hidden'), если вы не задалиsourcemapсами: карты собираются, но ссылки на них в бандле нет. - Вписывает debug id в каждый чанк и его карту. По нему NablOps находит нужную карту, даже если файлы лежат на CDN или имена повторяются в разных релизах. Номера строк и колонок в стеке остаются верными.
- Загружает карты в NablOps и при сбое сети повторяет до 3 раз.
- Удаляет
.mapизdist— на прод карты не уезжают. Карты, которые вы включили сами какsourcemap: true, остаются на месте.
Если загрузка не удалась, плагин пишет предупреждение в лог сборки, а сборка завершается успешно. Чтобы она падала, включите failOnError: true. Без авторизации — например, при локальной сборке — плагин пишет одну строку в лог и ничего не загружает.
| Опция | По умолчанию | Что задаёт |
|---|---|---|
release |
NABL_RELEASE → git → время |
версия сборки |
token |
NABL_UPLOAD_TOKEN |
токен загрузки; не нужен при доверенной сборке |
frontendId |
NABL_FRONTEND_ID |
фронтенд, в котором отметить выкладку |
commit |
NABL_COMMIT или текущий коммит |
коммит для отметки выкладки |
deleteMaps |
true |
удалять ли загруженные карты из dist |
failOnError |
false |
ронять ли сборку при неудачной загрузке |
CLI nablops для webpack, esbuild и других сборщиков
Для любого другого сборщика есть команда nablops (Node.js 18+):
npm install -D @nablops/cliexport NABL_RELEASE=$(git rev-parse --short HEAD)
npm run build # сборщик должен сохранить .map рядом с .js
npx nablops sourcemaps inject ./dist --release "$NABL_RELEASE"
npx nablops sourcemaps upload ./dist --release "$NABL_RELEASE" --delete-maps
# … выкладка …
npx nablops releases deploy --frontend <id фронтенда> --release "$NABL_RELEASE" --commit "$CI_COMMIT_SHA"injectвписывает debug id в.js,.mjsи.cjsи их карты. Запускайте его после сборки и до загрузки; на сервер должны уехать файлы уже послеinject.uploadзагружает все.mapкаталога;--delete-mapsудаляет успешно загруженные. Карты больше 50 МБ пропускаются. Если хоть одна карта не загрузилась, команда завершается с кодом 1.releases deployотмечает выкладку релиза во фронтенде.
Тот же релиз передайте в init опцией release — у Next.js и webpack мастер подключения показывает строку с переменной сборки.
Доверенная сборка: source maps без секретов в CI
Хранить токен в CI не нужно. Сборка в GitLab CI или GitHub Actions сама подтверждает, откуда она: предъявляет OIDC-токен своего CI, NablOps проверяет подпись провайдера, репозиторий и ветку и выдаёт плагину короткий токен загрузки на 30 минут. Украсть нечего: токен из лога через полчаса бесполезен, а сборке из другого репозитория NablOps его не выдаст. Нужен @nablops/vite-plugin или @nablops/cli 0.2.0 и новее.
Как настроить:
- Откройте фронтенд → вкладка «Настройки» → карточка «Source maps — стек по исходникам» → «Доверенная сборка».
- Выберите, где идёт сборка — «GitLab CI» (для своего GitLab — его адрес) или «GitHub Actions», укажите репозиторий (
group/projectилиowner/repo) и ветку, из которой выкатывается это окружение. Нажмите «Доверять сборке». - Добавьте в CI фрагмент, который там же показан.
GitLab CI — в job сборки:
build:
id_tokens:
NABL_ID_TOKEN:
aud: https://app.nablops.ioGitHub Actions — в workflow:
permissions:
id-token: write
contents: readПосле первой сборки в карточке правила видно, когда сборка получила токен и сколько карт загружено для какого релиза. Если сборка получила токен, но карт не загрузила, причина — в строке [nablops] лога сборки.
Сборка внутри docker build. Окружение CI в неё само не попадает. Передайте OIDC-токен секретом BuildKit — в слои образа он не попадёт: docker build --secret id=nabl_id_token,env=NABL_ID_TOKEN --build-arg NABL_CI_JOB=$CI_JOB_ID …, а в Dockerfile — ARG NABL_CI_JOB= и RUN --mount=type=secret,id=nabl_id_token,env=NABL_ID_TOKEN echo $NABL_CI_JOB && npm run build. NABL_CI_JOB нужен, потому что секрет не входит в ключ кэша Docker: без него перезапуск сборки того же коммита возьмёт шаг из кэша и карты не загрузит.
Токен загрузки для других CI
Для Jenkins и сборок вне CI остаётся токен загрузки: в тех же настройках — «Другой CI (Jenkins, сборка вне CI) — токен загрузки». Токен nabl_up_… показывается один раз и действует для всех фронтендов вашего аккаунта. Положите его в секрет CI NABL_UPLOAD_TOKEN. Если заданы и токен, и доверенная сборка, используется токен.
Вкладка «Релизы»
На вкладке «Релизы» фронтенда — все версии сборки:
| Колонка | Что показывает |
|---|---|
| «Релиз» | версия и когда пришли первые события; у последней — пометка «свежий» |
| «Выкладка» | когда выложена и с каким коммитом, или «не отмечена» |
| «Source maps» | сколько карт загружено, или «нет карт» — стек ошибок этого релиза по минифицированному бандлу |
| «Новых ошибок» | ошибки, впервые появившиеся в этом релизе |
| «Повторов» | сколько раз ошибки случались в релизе |
Выкладки в ленте. Выкладку отмечает плагин (опция frontendId) или команда nablops releases deploy: в ленте фронтенда появляется событие, на графиках — маркер. Если одна сборка сначала едет на staging, а потом на prod, отмечайте выкладку на шаге деплоя командой CLI, а не в сборке. Без отметки выкладкой считается первое событие с новым релизом.
Регресс в релизе. Если ошибка, которую отметили решённой, вернулась, на её странице видно, в каком релизе она снова появилась. Новые ошибки свежего релиза видны в колонке «Новых ошибок» сразу после выкладки, а падение стабильности — на «Обзоре» в разбивке по релизам.
Карта, загруженная уже после первых ошибок релиза, подхватывается в течение минуты: следующий повтор ошибки переводится по исходникам. Карты хранятся 180 дней с загрузки.
Настройка через ИИ-ассистента
ИИ-ассистент настраивает загрузку карт от начала до конца: подключает плагин, создаёт правило доверенной сборки для вашего репозитория и ветки, вписывает фрагмент в CI и после сборки проверяет, что карты дошли. Для CI без OIDC он создаст токен загрузки.
Что дальше
- Ошибки фронтенда на React — подключение пакета и группировка.
- ChunkLoadError — почему после выкладки не загружаются чанки.
- Сессии и пользователи — доля сессий без сбоев по релизам.
- Карта проекта — витрина фронтенда и шаг покрытия про source maps.
Первый сервер или стек подключается за пару минут. Бесплатно в раннем доступе.
Нашли неточность или не хватает ответа? Напишите в поддержку