Локальная разработка для headless Bitrix: три сценария и один рабочий

October 1, 2024

Первый вопрос, который мне задают про headless Bitrix, всегда про архитектуру. Второй — про деплой. Третий никто не задаёт вслух, но все спотыкаются об него на первой неделе: как вообще разрабатывать, если у тебя нет Bitrix на машине?

Я работаю с сетапом, где Next.js и Bitrix живут в разных репозиториях, но на одном железе. Это редкость. Большинство headless-команд разделяют фронтенд и бэкенд по разным людям и машинам. Именно поэтому я могу объяснить все компромиссы изнутри.

Почему это сложнее, чем поставить обычный Next.js

Стандартный Next.js-проект поднимается за npm install && npm run dev. Пять минут — и у тебя работающая страница.

Headless Bitrix так не работает. Полный локальный стек — это лицензия, веб-сервер (nginx или IIS), PHP-FPM, MySQL, cron для составного кэша и несколько часов на настройку. Это отдельный проект, а не «быстро развернуться локально».

Поэтому большинство headless-команд делают иначе: Next.js-разработчик пишет код у себя на машине, а API-запросы идут на staging-сервер или даже на прод. Это не плохо само по себе. Но у каждого подхода есть конкретная цена.

Когда начинаешь headless Bitrix-проект, вопрос локальной разработки редко обсуждается явно. Он всплывает через неделю, когда первый разработчик открывает задачу и спрашивает: «А на чём мне это тестировать?»

Три сценария: цена каждого

За несколько лет работы с headless Bitrix + Next.js я видел три устойчивых сценария.

Полный локальный стек. Bitrix поднят у каждого разработчика локально. Next.js работает против localhost.

Плюс — полная изоляция. Можно ломать что угодно, не трогая других.

Минус — дорого. Лицензия Bitrix не бесплатна. Поднять и поддерживать локальный Bitrix с нужными модулями, контентом и актуальными данными каталога — это десятки часов в начале и регулярные синхронизации потом. Для команды из 3+ человек нужен отдельный DevOps.

Этот вариант оправдан, если бэкенд активно меняется параллельно с фронтом на долгосрочном проекте.

Staging-прокси. Bitrix на отдельном staging-сервере. Next.js у разработчика локально, API-запросы идут на staging.

Самый распространённый сценарий. Он снимает проблему локальной установки Bitrix.

Цена — расхождение данных. Staging редко бывает точной копией прода: базу синхронизируют раз в неделю или реже, там устаревший контент, нет части промо-акций. Разработчик видит одно, пользователь в проде — другое. Классический источник багов, которые воспроизводятся только на проде.

Второй риск: несколько разработчиков одновременно работают против одного staging-сервера. Один меняет структуру iblock — у всех сразу ломается сборка.

Прод-прокси. Next.js локально, API идёт на продакшн Bitrix.

Быстро настроить, работает сразу. Но достаточно одной тестовой операции записи — и она попадёт в живые данные. Я видел, как тест на прод затёр описание товара. Случилось это не со стажёром, а с senior-разработчиком в конце рабочего дня.

Прод-прокси допустим только для операций чтения, с явными read-only ограничениями в конфигурации.

Наш сетап: оба репо на одном железе

Я работаю иначе. ivanpin.com (Next.js 16 + React 19) и wgp_backend (1С-Битрикс) живут в разных репозиториях, но на одной машине. Это нетипичный сценарий — обычно фронт и бэк разделены физически.

Что это даёт на практике:

Next.js обращается к API бэкенда по локальному URL, без сети. Latency в запросах — единицы миллисекунд вместо 80–150ms через интернет. Это звучит как мелочь, пока не начинаешь дебажить сложный запрос и не делаешь 50 итераций подряд.

Изменения в PHP-эндпоинте видны сразу. Я правлю файл в wgp_backend/api/ivanpin/services/, сохраняю, перезапрашиваю — никакого деплоя, никакого FTP, никакого ожидания. Это меняет скорость работы.

Плюс — данные живые и актуальные. Контент из базы тот же, что на проде, потому что это та же база.

Минус — один: это нельзя масштабировать на команду. Если над проектом работают два разработчика, этот сценарий перестаёт работать без дополнительной оркестрации.

`.env.local`: где ошибаются чаще всего

Когда Next.js работает против удалённого Bitrix — staging или прода — .env.local становится точкой сбора всех ошибок конфигурации.

Три типичных проблемы.

Первая — CORS на localhost. Bitrix не знает, что localhost:3000 — это доверенный источник. По умолчанию браузер заблокирует preflight-запросы. Решается на стороне PHP через Access-Control-Allow-Origin, но об этом забывают настроить на staging отдельно от прода. В bitrix-rest-api-headless-surprises я разобрал ещё несколько подобных сюрпризов API.

Вторая — NEXT_PUBLIC_ префикс. Переменные без этого префикса недоступны в браузере — они только серверные. Ошибка классическая: разработчик кладёт API_URL без префикса и получает undefined на клиенте. Два часа дебага, одно переименование.

Третья — сессии и cookies. Bitrix использует сессии для авторизации ряда API-методов. Если Next.js и Bitrix на разных доменах, cookie с сессией не передаётся автоматически. Нужно явно настраивать credentials: 'include' во fetch и SameSite=None; Secure на стороне бэкенда. На localhost это особенно больно — Secure требует HTTPS, которого локально нет.

Два инструмента, которые ускорили работу

Next.js hot reload. Звучит очевидно, но конкретно для headless-сетапа это важно: изменения в React-компонентах видны в браузере без ручного обновления страницы. Данные приходят с удалённого Bitrix, но UI перестраивается мгновенно. Это отделяет «изменил компонент» от «проверил API» — два независимых цикла.

Smoke-test скрипт для API. Перед началом работы я запускаю curl-скрипт, который проверяет 3–4 ключевых эндпоинта: возвращает ли API статус 200, есть ли данные, соответствует ли структура ответа. 10 секунд — и понятно, работает ли staging сегодня или нет. Без этого разработчик теряет 20–30 минут, прежде чем понимает, что проблема не в его коде.

Этот паттерн я описал в контексте headless-preflight-three-checks: быстрая проверка до начала работы экономит время всей итерации.

Что остаётся компромиссом

Staging-прокси — правильный выбор для большинства команд. Это признание, а не критика. Поднимать полный Bitrix локально для каждого разработчика экономически нецелесообразно в большинстве проектов.

Важно делать этот выбор осознанно. Расхождение данных на staging — не случайность, это норма. CORS надо настроить до старта разработки, не в первый день дебага. Прод-прокси — только для чтения, с явным ограничением в конфигурации.

В bitrix-nextjs-deploy-velocity-gap я разбирал другой аспект той же проблемы: деплой фронта и бэка движется с разной скоростью, и это нужно планировать. Локальная разработка — это та же история, только в начале цикла, а не в конце.

Вопрос не «как настроить идеальный локальный сетап». Вопрос «какие компромиссы ты выбираешь и почему». Ответ на него лучше иметь в первый день проекта, а не через месяц.