Headless and decoupled Drupal
Drupal as the content engine behind any frontend.
From architecture advice to the API layer: I build headless and decoupled Drupal solutions that stay scalable and maintainable.
Discuss your architecture
Headless Drupal is an architecture choice, not an upgrade.
Drupal delivers content as data via an API, and a separate application turns that into pages.
That makes sense with multiple channels or a front-end stack that already exists, and it's wasted effort for a single website with an editorial team that assembles pages itself.
I map out which part needs to be decoupled, connect it with JSON:API or GraphQL, and leave the rest where it belongs.
What does headless Drupal mean?
Headless Drupal means Drupal no longer delivers HTML to the visitor, but structured data to a layer that handles the display.
Headless and decoupled get used interchangeably, and that's where a lot of projects go wrong from the start, because there are two variants underneath with very different price tags.
Fully decoupled
With fully decoupled, Drupal becomes just the content model, workflow and editorial environment.
All public-facing HTML comes from a separate application, usually a JavaScript framework with server-side rendering.
The trade-off is that you build yourself what the theme layer normally provides: routing, metatags, canonicals, sitemap, redirects, error pages, language switching and preview.
Two codebases, two deploy pipelines, two upgrade paths.
Progressively decoupled
With progressively decoupled, Drupal keeps rendering the page and a JavaScript component only takes over the part where interactivity actually adds something: a search interface with facets, a configurator, a map.
The editorial team keeps preview and layout, and the semantics and SEO foundation of the rest of the page stay in Drupal.
For most sites, this is the better choice, because you only pay for the complexity you actually need.
When should you choose headless Drupal?
Headless makes sense when the front end has more than one consumer, or already existed before Drupal came into the picture.
The trigger then sits outside the website itself.
I work through that trade-off point by point in headless Drupal: when to use it and when not.
- ✓ You deliver the same content to a website, a mobile app and a third channel, and don't want to edit it three times over.
- ✓ You already have a front-end stack and a team working in it, and Drupal comes in as the content source.
- ✓ Front end and back end are built by separate teams or vendors, with an API as the agreement between them.
- ✓ Part of your interface is an application, not a page, and that doesn't belong in a Twig template.
When headless mainly adds cost
For a site with one public front end and an editorial team that assembles its own pages, fully decoupled mainly adds work without a payoff.
You rebuild what you already had, and pay for it twice: once at build time and once in maintenance.
The extra cost sits in four places: a second codebase with its own dependencies and update rhythm, hosting and monitoring for two runtimes, debugging across two systems because the first question with every error is which layer caused it, and your hiring, because you need Drupal knowledge and framework knowledge in the same team.
Headless also doesn't automatically make a site faster.
A cached Drupal page behind a CDN is often faster than a bundle that still fetches data after loading.
Speed comes from caching, image formats and how much code the browser gets, not from the architecture choice; where those gains sit in Drupal is covered in Core Web Vitals for Drupal.
If your situation looks like this, I'll say so, even if the budget is already sitting there.
JSON:API or GraphQL?
JSON:API is the default choice, because it's in core and needs no extra building.
It's been part of core since Drupal 8.7, follows the JSON:API specification, and is read-only by default.
Every entity and bundle gets an endpoint without you having to define anything, and with sparse fieldsets and include, you fetch what a page needs in a single request.
GraphQL isn't in core.
It's a contrib module; in the current 5.x series (4.x is still a maintenance branch), you define the schema yourself in code.
That's more work upfront and delivers an integration you have full control over, which pays off when clients need very different cross-sections of the same content.
| Topic | JSON:API | GraphQL |
|---|---|---|
| Status | In core since 8.7 | Contrib module, 5.x (4.x in maintenance) |
| Setup work | Enable and configure permissions | Define the schema yourself in code |
| Queries | Fixed shape per resource, filters via parameters | Client chooses the fields per request |
| Caching | GET, so cacheable in Drupal and on a CDN | Usually POST to a single endpoint |
| Choose for | One or two clients | Clients with differing data needs |
The integration is rarely the hardest part.
The content model is.
A model that works fine in Drupal can be unusable over an API, because the meaning lives in the theme layer instead of in the fields.
What headless does to your editorial team
The heaviest loss with fully decoupled sits with the editorial team, not with the technology.
Drupal renders preview with its own theme, and that theme is gone.
An editor who wants to see an unpublished version as it will appear live therefore needs their own preview path in the front end, with authenticated requests and the right revision or moderation state.
Layout Builder is the second bottleneck.
It works with render arrays and HTML, not structured data, so over an API you don't get a usable layout tree back.
So you choose: Drupal keeps rendering, or you drop free-form page building and work with a fixed component contract.
The second option gives a more consistent site, but is a constraint for anyone used to dragging things around.
On top of that, contextual links and inline editing disappear, and one question gets added: who makes sure the front end rebuilds or clears its cache when an editor hits publish.
Without that agreement, your site sits hours behind your editorial team.
What headless does to SEO
Headless isn't bad for SEO, but every piece of automation Drupal normally gives you for free, you have to take over explicitly.
This is where decoupled projects quietly take damage, because it only shows up once rankings drop.
- Rendering: server-side rendering isn't an option, it's a requirement, because a page built entirely in the browser depends on what the search engine is willing to render.
- Status codes: a client-side app easily returns a 200 on a page that doesn't exist, and redirects from the Redirect module no longer reach the visitor.
- Metadata: titles, descriptions, canonicals, hreflang and structured data need to travel over the API all the way into the head.
- Sitemap and URLs: the sitemap and path aliases sit in Drupal, so your front end keeps the same URLs or you lose your history.
- Core Web Vitals: LCP, INP and CLS measure what the browser receives, and a large bundle makes those numbers worse.
Not a reason to write off headless, but a reason to budget it properly.
More on that under technical SEO and frontend performance.
If you're converting an existing site, your URL structure often changes along with it, and that makes this a migration question too.
Accessibility moves to the front end too
The accessibility Drupal brings in core only applies to what Drupal itself renders, so in a fully decoupled setup you start from zero in the front end.
That weighs more heavily than it used to: the European Accessibility Act, directive 2019/882, has applied since 28 June 2025.
Whether it applies to you depends on your sector and what you offer: it targets, among others, webshops, banking, transport and e-books, with an exception for micro-enterprises providing services.
For government sites, directive 2016/2102 and its national implementation apply.
Have the exact obligation checked legally.
Technically, in both cases you work towards WCAG 2.2 level AA and EN 301 549.
The problems I keep finding in decoupled front ends are always the same four.
With client-side routing, focus doesn't move, and a screen reader user doesn't hear that there's a new page.
The document title stays that of the previous page.
Error messages from client-side validation sit disconnected from their field.
And modals don't trap focus, so keyboard users end up behind the window.
A component library that calls itself accessible doesn't fix that, because the behaviour comes from how you wire the components together.
Testing stays manual work with keyboard and screen reader alongside tools like Lighthouse and axe DevTools.
The approach is covered under digital accessibility.
Which Drupal version do you build a headless back end on?
On Drupal 11, the current stable series, today 11.4.x.
Drupal 10 reaches end of life on 9 December 2026 and 10.6.0 is the last minor release, so starting a new project on 10 means upgrading within three months.
Drupal 12 is released in the week of 7 December 2026, the same week as that end of life, and isn't available yet.
That path is plannable, because security releases come at fixed points and a minor roughly every six months.
Your front end's dependencies don't follow that rhythm, and that cost is often missing from the budget.
My approach: scope, connect, document
- Scope. Establishing which part needs to be decoupled and which doesn't, based on the channels, the teams and the editorial team.
Result: an architecture choice with the consequences for preview, SEO and accessibility included, instead of a framework that was already chosen beforehand. - Connect. Making the content model usable over an API, setting up JSON:API or GraphQL, arranging permissions and authentication, and agreeing the caching strategy plus invalidation on publish.
The preview path belongs here, not in a leftover list after go-live. - Document. A component contract between back end and front end, documentation of the endpoints, and tests on the integration, so your own team can take it over.
I've worked with Drupal for more than ten years, for universities, government and industry, and I step into the existing Git flow and conventions instead of setting up a separate way of working alongside it.
Earlier work is under cases, including the Brighteye case.
What does a headless Drupal project cost?
My rate is 75 to 95 euros per hour or 650 to 800 euros per day, excluding VAT, lower for long engagements and returning clients.
Belgian Drupal freelancers list rates on Malt between 400 and 600 euros per day with a median around 550 euros, the broader Belgian IT freelance market sits around 710 euros per day, and for the Netherlands Freelance.nl quotes 70 to 90 euros per hour.
What makes a headless project more expensive than the same project with a Drupal theme isn't a markup on the hourly rate, it's the extra scope: a second application, rebuilding preview, and the SEO and accessibility layer you'd otherwise get for free.
Progressively decoupled stays closer to a normal build.
The breakdown is on my rates and ways of working page, and if it's a new platform without a decoupled front end, look at Drupal architecture and development.
Not sure whether headless fits your situation?
Describe your situation via the contact form: the channels you serve, the front end you already have, and what your editorial team does themselves today.
I'll look at your request and give you an honest picture within 24 hours of what headless delivers and what it costs, including when the answer is that you don't need it.
Frequently asked questions
What is headless Drupal?
Headless Drupal is a setup in which Drupal manages the content and offers it as structured data via an API, while a separate application renders the pages.
The connection usually runs over JSON:API, which has been in core since Drupal 8.7, or over GraphQL as a contrib module.
The content model, permissions and workflow stay in Drupal, but the presentation layer is no longer its responsibility.
What is the difference between fully decoupled and progressively decoupled?
With fully decoupled, Drupal no longer delivers a single public page and all HTML comes from a separate frontend.
With progressively decoupled, Drupal keeps rendering and only a component gets taken over, such as a search interface or a configurator.
The difference determines what you rebuild: with the first, preview, routing, metadata and accessibility; with the second, just that one component.
For a single website with an active editorial team, the second is usually enough.
Is JSON:API or GraphQL the better choice for Drupal?
JSON:API for most projects, since it's in core, requires no schema work, and delivers GET requests you can cache in Drupal and on a CDN.
GraphQL is interesting when clients need very different cross-sections of the same content, but then you define the schema yourself in code.
Both stand or fall with your content model, so that's the choice that needs to be right first.
When don't you need headless Drupal?
With a single public website with an editorial team that assembles its own pages and without a frontend stack already in place.
Then in a separate application you'd rebuild what Drupal already delivers: routing, metatags, redirects, error pages, language switching and preview, and you pay for that twice, in the build and in maintenance.
If you still want a piece of interface as an application, progressively decoupled is almost always the better choice, since then you only set that one component apart.
Is headless Drupal bad for SEO?
Not by definition, but it puts the responsibility on you instead of on Drupal.
Server-side rendering is a requirement, status codes and redirects have to stay correct in the frontend, and metatags, canonicals, hreflang and structured data need to travel over the API all the way into the head.
If one of those four goes wrong, you publish pages that work but aren't indexable.
In a Drupal theme you get most of that for free.
Can my editorial team still see a preview in a headless setup?
Yes, but you build that yourself.
Drupal normally renders preview with its own theme, and that no longer exists in a fully decoupled setup, so the frontend needs its own preview route that fetches unpublished revisions with authentication.
The same applies to Layout Builder: it delivers HTML instead of structured data, so free-form page building usually gets traded in for a fixed component contract.
What does headless Drupal cost?
More than the same project with a Drupal theme, and the difference isn't in my hourly rate but in the scope: a second application with its own dependencies and deploys, a preview path you build yourself, and the SEO and accessibility layer a theme provides for free.
Progressively decoupled stays closer to a normal build, because you only set that one component apart.
My hourly and daily rate and the ways of working together are on my rates page.
A question about this topic?
Briefly describe your situation, and I'll let you know what's going on and what it would cost. No sales pitch.
