Vercel Protected Source Maps: як дебажити production і не світити вихідний код

Зачіпка

Production-помилки хочеться бачити нормально: з файлами, рядками й зрозумілими stack traces. Але якщо source map лежить поруч із JavaScript і відкривається всім, debugging перетворюється на публічну екскурсію по вихідному коду.

14 травня 2026 року Vercel запустив Protected Source Maps і зробив цю опцію стандартною для нових проєктів. Для існуючих проєктів це хороший момент провести короткий аудит: чи справді ваші .map файли мають бачити всі в інтернеті.

Проблема / Контекст

У production frontend-код зазвичай проходить збірку: файли об’єднуються, стискаються, імена скорочуються, а результат стає швидшим для браузера. Це добре для користувача, але не дуже зручно для debugging. Коли помилка прилітає з файлу на кшталт app-8f3a91.js, людина не хоче вручну вгадувати, який компонент упав.

Тут допомагає source map. Він каже інструментам: цей шматок, тобто мінімізований код, відповідає ось цьому початковому файлу й рядку. Завдяки цьому DevTools або error tracker можуть показати зрозумілий stack trace.

Побічний ефект очевидний: source map може відкрити структуру проєкту, імена файлів, частину логіки, коментарі або інші деталі, які команда не планувала показувати публічно. Це не завжди катастрофа, але це точно поверхня ризику. Особливо якщо у коді є внутрішні маршрути, feature flags, неакуратні коментарі або логіка, яку зручно аналізувати конкурентам і атакувальникам.

Next.js прямо попереджає: browser source maps у production за замовчуванням вимкнені, щоб не витікало джерело на клієнті. Якщо команда вмикає productionBrowserSourceMaps: true, файли генеруються поруч із JavaScript і Next.js може їх віддавати за запитом. У Vercel Protected Source Maps додає контроль доступу саме на цьому місці.

Чому це важливо

Команди часто живуть між двома крайнощами. Перша: вимкнути source maps повністю й потім ловити production-баги наосліп. Друга: увімкнути їх у production і не перевірити, хто може скачати .map. Обидва варіанти мають ціну.

Protected Source Maps дає середній шлях. Команда зберігає readable stack traces і browser debugging, але Vercel перевіряє доступ до .map файлів через Vercel Authentication. Авторизовані учасники команди можуть отримати source maps. Усі інші бачать 404 Not Found, а не підтвердження, що файл існує, але їм не можна.

Важливий нюанс: це не робить поганий frontend-код секретним. Усе, що реально виконується в браузері, користувач усе одно отримує у вигляді JavaScript. Захист source maps не замінює нормальну модель безпеки. Він просто прибирає зайву підказку, яка робить reverse engineering простішим.

Ілюстрація: що саме закривається

Уявіть production deployment як вітрину магазину. Мінімізований JavaScript — це товар на полиці: браузер має його отримати, інакше сайт не працюватиме. Source map — це внутрішня схема складу, де видно, як усе організовано. Для команди схема корисна. Для випадкового відвідувача — зайва.

Protected Source Maps ставить замок не на сам сайт, а на browser .map файли. Якщо людина має доступ до deployment, вона може дебажити. Якщо ні — запит до source map виглядає так, ніби файлу немає.

Як це зробити

1. Зрозумійте, чи production build генерує source maps

Почніть із конфігу. Для Next.js ключовий прапорець виглядає так:

// next.config.js
module.exports = {
  productionBrowserSourceMaps: true,
};

Якщо такого прапорця немає, це ще не означає, що source maps точно відсутні. У проєкті може бути інший build tool, окремий Webpack-конфіг, Sentry-плагін або custom pipeline. Але це швидка перша точка перевірки.

Після production build подивіться на output. Якщо поруч із JavaScript або CSS є файли *.map, питання вже не теоретичне.

2. Перевірте доступ ззовні

Відкрийте production або preview URL у приватному вікні без Vercel-логіну. У DevTools знайдіть JavaScript asset і спробуйте додати .map або відкрити URL, який браузер бачить у sourceMappingURL.

Для ручної перевірки з термінала підійде проста команда:

curl -I "https://your-app.example/_next/static/chunks/app/example.js.map"

Якщо без авторизації повертається 200, source map публічний. Якщо після ввімкнення захисту повертається 404, Vercel приховує файл від сторонніх запитів.

3. Увімкніть Protected Source Maps у Vercel

Для існуючих проєктів зайдіть у Vercel Dashboard, відкрийте project settings, далі Deployment Protection, і увімкніть Protected Source Maps. За документацією Vercel, зміна застосовується до наступного запиту .map без redeploy.

Якщо команда керує налаштуваннями через API, потрібне поле protectedSourcemaps: true у запиті оновлення проєкту. Це зручно для platform-команд, але для більшості маленьких команд dashboard буде швидшим і безпечнішим.

4. Перевірте browser debugging

Після ввімкнення захисту DevTools не завжди зможе просто так завантажити .map, бо браузерні запити до source maps не несуть вашу Vercel-сесію автоматично. Vercel пропонує шлях через Vercel Toolbar: відкрити deployment, активувати Toolbar, увійти користувачем із доступом, увімкнути Debug Mode і перезавантажити сторінку.

Тут важливо не зупинятися на словах “увімкнули”. Візьміть реальну production-помилку або тестовий throw у preview, відкрийте stack trace і переконайтеся, що він веде до зрозумілих файлів, а не тільки до мінімізованого bundle.

5. Перевірте automation і error tracking

Не всі інструменти працюють як людина в браузері. CI/CD, Playwright, monitoring або error tracker можуть ходити до protected deployment автоматично. Для таких сценаріїв Vercel має automation bypass: спеціальний секрет, який передається через заголовок або query parameter.

Найкраща практика — тримати секрет в environment variable, а не прописувати його в коді чи відкритих URL. Після увімкнення source-map protection перевірте:

• чи проходять E2E-тести проти protected deployment;
• чи monitoring не отримує зайві 404;
• чи error tracker досі може зіставляти stack traces;
• чи bypass не лежить у логах або репозиторії.

6. Не забувайте про межі функції

Protected Source Maps стосується browser source map файлів, які віддаються з deployment. Воно не змінює inline source maps, server-side source maps у Vercel Functions або source maps, які ви окремо завантажили в третій сервіс.

Якщо у вас є окремий upload у Sentry або інший error tracker, це треба перевіряти окремо: хто має доступ до артефактів, чи не публічний bucket, чи не потрапили source maps у статичний public directory.

Антипатерни

• вмикати productionBrowserSourceMaps: true і не перевіряти URL вручну;
• вважати, що source maps безпечні, бо посилання на них “ніхто не знає”;
• вимикати source maps повністю й залишати команду без нормального production-debug;
• давати automation bypass усім інструментам одним секретом без потреби;
• зберігати bypass token у репозиторії або логах;
• думати, що Protected Source Maps приховує весь frontend-код;
• вимикати protectedSourcemaps назад без розуміння, що .map знову стануть публічними на наступний запит.

Висновок / План дій

Protected Source Maps — маленька опція з дуже практичним ефектом. Вона не магічний сейф для frontend-коду, але прибирає непотрібний публічний доступ до файлів, які роблять код набагато читабельнішим.

Що зробити далі:

1. знайти, чи production build створює *.map;
2. перевірити кілька .map URL без авторизації;
3. увімкнути Protected Source Maps для Vercel-проєкту;
4. перевірити DevTools через Vercel Toolbar і Debug Mode;
5. пройтися по CI/CD, monitoring і error tracker;
6. записати рішення в release checklist.

Офіційні джерела:

• https://vercel.com/changelog/protected-source-maps-ship-browser-source-maps-securely
• https://vercel.com/docs/deployment-protection/protected-source-maps
• https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation
• https://nextjs.org/docs/pages/api-reference/config/next-config-js/productionBrowserSourceMaps