Drupal headless: when “decoupled” actually pays off

Headless Drupal gets sold as the obvious modern choice: split the backend from the frontend, bolt on React or Next.js, and you have a fast, future-proof site. We have built it both ways, and the honest version is less exciting. Decoupled Drupal pays off for a specific set of sites and quietly drains the budget on the rest. Here is how to tell which one you are.

What decoupled Drupal actually means

In a normal Drupal site, one system does everything. Drupal stores your content and also renders the HTML the visitor sees. Headless Drupal, the same thing people call decoupled Drupal, cuts that in half. Drupal keeps managing content and hands it out through an API, usually JSON:API or GraphQL. A separate frontend app, often Next.js or Astro, fetches that content and draws the pages.

There is also a middle option that gets ignored in most of these comparisons: progressive decoupling. Drupal still renders the page, and you drop a JavaScript framework into just the parts that need to feel like an app. More on that below, because for a lot of sites it is the right answer.

The honest cost of going headless

The pitch focuses on speed and flexibility. The bill shows up somewhere else. When you decouple, you take on:

• Two codebases instead of one, with two deploy pipelines and two things to keep patched
• The loss of Drupal’s own rendering features: Layout Builder, in-place editing, the preview button that just works
• Editor pain, because content authors no longer see their page as they build it unless you wire up a custom preview
• SEO work you used to get for free, since server-side rendering, meta tags, redirects, and sitemaps all have to be rebuilt on the frontend
• A bigger, pricier team, because now you need frontend engineers who know the JS framework on top of your Drupal people

None of that is a dealbreaker. It is just real, and most vendor articles skip it. In our experience a decoupled build runs roughly 1.5 to 2 times the cost of a well-themed Drupal site, and it needs at least two people who understand it to keep it healthy.

When it actually pays off

Decoupling earns its cost when at least one of these is true for you:

• You publish to more than one place. The same content feeds a website, a mobile app, and maybe a kiosk or a partner feed. Drupal as a content API is genuinely good at this, and rebuilding that content model three times would cost far more.
• You already have a frontend team and a design system in React or Next. If those people and that tooling exist, the friction of decoupling drops a lot.
• You are hitting a real performance ceiling at high traffic, and an edge-rendered frontend on a CDN buys you speed a traditional server render cannot.
• The interface is genuinely app-like: heavy interactivity, live filtering, dashboard behavior that fights against a page-reload model.

If one of those describes your project, headless Drupal is a reasonable call and probably the right one.

When to stay coupled

For most content sites, plain monolithic Drupal is still the smarter build. Either way, getting your existing content in is its own task, and we use a specific set of Drupal migration tools to do it cleanly. Stay coupled when:

• The site is mainly marketing, publishing, or brochure content
• Your team is small and has no dedicated frontend engineers
• Editors need to move fast with WYSIWYG and instant preview
• Budget matters and a good Drupal theme already does everything the design asks for

We have watched agencies sell headless rebuilds to clients who fit every line above. The site ends up slower to update, harder to staff, and no faster for the visitor, because a cached Drupal page and a static frontend land in the same place on a speed test.

Progressive decoupling is the answer more often than people admit

Here is the option that gets lost between the two camps. Keep Drupal rendering your pages, and embed a JavaScript framework only in the spots that need it: a product configurator, a live search, a booking widget. The editor still gets preview and Layout Builder. You still get React where React earns its keep. You skip almost all the cost listed earlier.

For the majority of sites that think they want headless, this is what they actually want. It gives you the interactive piece without signing up to maintain two full stacks.

How to decide in one sitting

Run your project through these questions. If you answer no to all of them, stay coupled.

1. Do you serve the same content to more than one frontend, web plus app for example?
2. Do you already employ frontend engineers fluent in your chosen JS framework?
3. Is there a specific, measured performance problem that a normal cached Drupal site cannot solve?
4. Does a core part of the experience need to behave like an app rather than a set of pages?

One clear yes can justify decoupling. A pile of maybes usually means progressive decoupling, or no change at all.

What we do with this

We build and support Drupal both ways, and we will tell you which one your project needs before you spend on the wrong one. That is part of our Drupal support work, and the API layer that makes decoupling possible overlaps with our integrations practice. If you are also weighing a version jump at the same time, sort that out first: our notes on the Drupal 9 to 10 upgrade cover what to clear before you touch the architecture.

We will not sell you a headless rebuild you do not need. If a themed Drupal site does the job, that is what we will recommend, and we would rather keep your existing site fast than talk you into two codebases you will struggle to staff. The same argument runs on the other platform, with the numbers attached, in our look at what headless WordPress costs to run.