Local Dev for Headless Bitrix: Three Setups, One That Actually Works

The first question I get about headless Bitrix is about architecture. The second is about deployment. The third nobody asks out loud — but everyone runs into it in the first week: how do you actually develop when you don't have Bitrix on your machine?

I work with a setup where Next.js and Bitrix live in separate repos but on the same hardware. That's unusual. Most headless teams split frontend and backend across different people and machines. Which is exactly why I can explain all the trade-offs from the inside.

Why local Bitrix dev is harder than it looks

A standard Next.js project starts with npm install && npm run dev. Five minutes and you have something running.

Headless Bitrix doesn't work that way. A full local Bitrix stack means a commercial license, a web server, PHP-FPM, MySQL, and a cron job for composite cache. That's multiple hours of setup, not a quick start.

So most headless teams do something else: the Next.js developer writes code locally, API requests go to a staging server or sometimes production. That's not a bad call. But each approach has a specific cost, and those costs are worth knowing before you hit them.

Three setup patterns and what each one costs

Full local stack. Bitrix runs on every developer's machine. Next.js talks to localhost.

The upside is full isolation. You can break things without affecting anyone else.

The downside is cost. Bitrix licenses aren't free. Setting up and maintaining a local Bitrix instance with the right modules, content, and current catalog data takes dozens of hours upfront and regular syncs after. For a team of three or more, this is a problem that needs a DevOps person.

This makes sense for long-term projects where the backend is actively changing alongside the frontend.

Staging proxy. Bitrix on a dedicated staging server that mirrors production. Next.js locally, API requests go to staging.

This is the most common pattern. It removes the local Bitrix installation problem entirely.

The cost is data drift. Staging is rarely an accurate copy of production: the database gets synced weekly at best, the content is stale, some promotions are missing. A developer sees one thing, a user in production sees another. This is where bugs come from that only reproduce in production.

Second problem: multiple developers hitting the same staging server at the same time. One person changes an iblock structure — everyone else's builds break.

Production proxy. Next.js locally, API goes to live Bitrix.

Fast to configure, works immediately. But one write operation during testing and that data lands in production. I've seen a test overwrite a product description. It wasn't a junior — it was a senior developer at the end of a long day.

Production proxy is only acceptable for read operations, with explicit read-only constraints enforced in the config.

Our setup: two repos, one machine

Running Next.js and Bitrix on the same physical machine — separate repos, shared hardware — is unusual in headless projects. Most teams split frontend and backend across different people and machines. I don't. ivanpin.com (Next.js 16 + React 19) and wgp_backend (1C-Bitrix) both run locally on my machine.

What it actually changes:

Next.js hits the backend API over localhost, not the internet. Latency drops from 80–150ms per request to single-digit milliseconds. That sounds minor until you're debugging a complex query and you're on iteration 50.

Changes to PHP endpoints are visible immediately. I edit a file in wgp_backend/api/ivanpin/services/, save, and re-request — no deploy, no FTP, no waiting. That changes the pace of work more than I expected.

The data is live and current because it's the same database.

One thing it doesn't solve: two developers on the same project would need a different approach. This setup doesn't scale.

.env.local: where teams consistently get it wrong

When Next.js is pointing at a remote Bitrix — staging or production — .env.local becomes the collection point for every configuration mistake.

Three patterns I see repeatedly.

First, CORS on localhost. Bitrix doesn't know that localhost:3000 is a trusted origin. By default, the browser will block preflight requests. The fix is on the PHP side via Access-Control-Allow-Origin, but staging often has different CORS settings than production and nobody notices until day one of development. I covered more API surprises like this in bitrix-rest-api-headless-surprises.

Second, the NEXT_PUBLIC_ prefix. Variables without this prefix aren't available in the browser — they're server-side only. The classic mistake: someone puts API_URL without the prefix and gets undefined on the client. Two hours of debugging, one rename.

Third, sessions and cookies. Bitrix uses sessions for some API method authentication. If Next.js and Bitrix are on different domains, session cookies don't transfer automatically. You need credentials: 'include' in fetch calls and SameSite=None; Secure on the backend. On localhost this gets painful because Secure requires HTTPS that you don't have locally.

Two things that shortened the feedback loop

Next.js hot reload. Obvious, but worth naming in the headless context: UI changes are visible in the browser without a manual refresh, even when the data is coming from a remote Bitrix. This decouples "I changed a component" from "I tested the API" — two independent cycles that used to step on each other.

An API smoke-test script. Before starting work, I run a short curl script that checks three or four key endpoints: does the API return 200, is there data, does the response structure match what we expect. Ten seconds and it's clear whether staging is working today or not. Without this, a developer can spend 20–30 minutes before realizing the problem isn't in their code.

This is the same pattern I wrote about in headless-preflight-three-checks: a fast check before you start work saves more time than the check itself costs.

What you're still trading off

Staging proxy is the right call for most teams. I mean that as a statement of fact, not a criticism. Running a full local Bitrix instance for every developer is economically impractical in most projects.

The only thing that matters is making the choice consciously. Data drift on staging isn't a bug — it's a known property of the setup. CORS needs to be configured before development starts, not on the first day of debugging. Production proxy is read-only by policy, enforced in code.

In bitrix-nextjs-deploy-velocity-gap I covered a related problem: frontend and backend deploy at different speeds, and that gap needs planning. Local dev is the same story at the start of the cycle rather than the end.

The question isn't "how do I set up a perfect local environment." It's "which trade-offs am I choosing and why." Answer that on day one. Discovering it on week three costs more.