← Back to blog

Three checks before any headless project

The first question I ask before any proposal: "Who's editing content after we're done, and where?"

If the answer is "Bitrix stays as the CMS, editors won't need to change anything" — we keep talking. If it's "we'll figure it out" — that's a different project with a different budget and a different timeline.

Three hours before kickoff saves six weeks in the middle.

A headless pre-flight is a structured discovery session — 1-3 hours — run before a headless CMS project begins. It covers three areas that predictably cause problems mid-project: editorial workflow, API surface, and deployment pipeline.

I once walked away from a $40k contract because a one-day pre-flight showed the project wasn't ready for headless. Not technically — organizationally. The full story is in I turned down a $40K rewrite contract. The short version: stacks don't kill headless projects. Starting without three specific checks does.

For the "should we go headless at all" question, there's a separate post: Five questions I ask before proposing headless to a client. These three are what you do once the decision is made and the project is starting.

Check 1: editors and CMS

The most underestimated question: who's updating content after launch?

In a headless setup, Bitrix or Laravel stays as the backend CMS. The front end (Next.js) pulls data through an API. If editors are used to working in Bitrix, nothing changes for them. They log into the familiar interface, publish, and the frontend picks it up automatically.

Problems start when you discover mid-project that "editors don't actually use Bitrix" or "we'd like to switch CMS while we're at it." That means a parallel CMS migration on top of a headless restructure. Two changes running at once.

Three questions worth asking upfront:

  • How many people edit content right now?
  • Are they staying on the current CMS or switching?
  • Who trains editors on the new workflow if it changes?

One editor who's also a developer — no problem, they'll adapt fast. Five marketing editors — that's a separate track with its own training budget and timeline.

Check 2: how many API endpoints do you need on Day 1?

Headless runs through an API. The frontend doesn't render pages from the CMS directly; it requests data from endpoints. And if you don't map out that endpoint list before you start, the first sprint burns on figuring it out in real time.

On the 28k SKU catalog project, we mapped this list before any development started. Twelve endpoints just for the core flows: category listing, product card, filters, search, cart, checkout data. Without that list, the first three weeks would've been developers blocked waiting on API specs.

Take the front-end mockups and for each screen, write down what data it needs and where it comes from. That's API mapping. Takes 2-3 hours on a typical e-com project.

When the list surfaces data your CMS doesn't have yet, or data that's structured differently than the frontend needs — that's an early signal for backend work. Better to see it in a spreadsheet on day 2 than in error logs on week 8.

Check 3: deployment pipeline

Headless means separate deployments: front end lives independently from the backend. That's one of the core benefits — a Bitrix security patch doesn't touch Next.js, and a frontend update doesn't require touching the CMS server.

But that benefit only works if the infrastructure supports it.

  • Is there a CI/CD pipeline for the frontend? (GitHub Actions, Vercel, GitLab CI — doesn't matter which, what matters is automated deploy on push)
  • Is the backend deployed via FTP or through a pipeline?
  • Is there a staging environment, or only production?

The pattern I see most often: the team builds a Next.js front end, but plans to deploy it "alongside Bitrix" over FTP on the same server. That isn't headless. It's an expensive template with an API. The deployment pipeline isn't an implementation detail — it's the foundation of the whole architectural decision.

If CI/CD doesn't exist yet, set it up before the main development starts. Takes 1-2 days. Skip it, and the team starts deploying manually, then forgets to, then discovers that prod and staging have drifted.

What to do when answers get uncomfortable

Three checks, three possible outcomes:

  1. Everything looks good — kick off with a clear foundation and no hidden blockers.
  2. There are gaps — document them, estimate the extra work, adjust the quote and timeline before signing anything.
  3. Hard blocker — I recommend pausing the headless launch and solving the specific problem first. That's an uncomfortable conversation. It's still better at pre-flight than two months in.

One condition: the client needs to be in the room. This isn't a checklist for the developer to run solo. The editor brings real examples of their daily work. The product owner explains what data each screen actually needs. The devops person shows how deployment currently works.

Without that, you get a pre-flight on paper. The real blockers show up later.

Three hours vs six weeks

These checks take 1-3 hours depending on project complexity. They won't surface everything. But the most predictable blockers will be on paper before the dev budget starts running.

Headless works. I use it. It doesn't work automatically — only when it starts with an honest look at what actually exists today.

If the decision to go headless is already made on your project, but these three checks haven't happened — do them before the next sprint. Not after.