When decoupled Drupal fits better than traditional Drupal
The choice between decoupled and traditional Drupal turns on two questions: who builds and owns the presentation layer, and how many channels consume the same content. If your editors depend on Drupal theming, page-building tools and one public site, traditional Drupal is usually the simpler fit. Editors see changes on the page they publish, the theme lives in the same codebase as the content model, and one team can ship both. Drupal CMS and its visual page builder, Drupal Canvas, target this editor-led path. Confirm which of those tools your version of the site would actually use before you commit to a build.
Decoupling makes sense when the same content must appear in React, Vue or Astro front ends or in other channels, and when a separate team owns the presentation layer. Drupal acts as the content API, and the core jsonapi module provides create, read, update and delete for entities with no configuration, plus filtering, includes, pagination, revisions, translations and file uploads. Use the core module and avoid the standalone JSON:API project, which Drupal.org says is unsupported because of a security issue. Drupal's decoupled Drupal documentation explains the architecture. Decoupling is not automatically cheaper or safer. The front end becomes a second codebase with its own build pipeline, dependencies, hosting and patching, and someone must own it after launch.
Before you split the stack, confirm three things: whether editors need live preview from the front end, which caching layer will sit in front of both systems, and whether your team has JavaScript engineers who will maintain the front end for years. Preview, cache invalidation and access control for unpublished revisions all move from the Drupal theme into your application code, so each needs a named owner. Ask any integrator for a written list of which of these the build will own and which stays in Drupal. Also plan around timing: Drupal 10 reaches end of life on December 9, 2026, and Drupal 12 is scheduled for the week of December 7, 2026, so align the Drupal upgrade with the front-end release cycle.
Decoupled and traditional Drupal side by side
This table compares how each model divides work across the presentation layer, caching, preview, authentication and team skills. Both models run Drupal core on the same PHP and database platform, so read each row as a question about where your front end lives and who maintains it.
| Decision area | Traditional Drupal | Decoupled Drupal |
|---|---|---|
| Presentation layer ownership | Drupal renders pages through its theme layer, so Drupal developers own templates, markup and page logic. | A separate front end built with React, Vue or Astro owns rendering. The difference matters when a separate front-end team or framework is required. |
| How content reaches the browser | Drupal assembles full HTML pages on the server for each request, using its render and cache systems. | The browser or front-end server requests content from Drupal's JSON:API endpoints, then renders it. Confirm which pages can be pre-rendered in your setup. |
| Front-end hosting | Drupal's web servers serve pages, so one hosting stack covers the site. | Adds a second deployable application with its own hosting, build pipeline and domain configuration. Confirm the hosting model with your front-end team. |
| Preview for editors | Editors see changes through Drupal's native content preview and layout tools. | Preview needs a bridge between Drupal and the front end, which must be built and tested. Confirm how draft revisions appear on the front end before committing. |
| Caching layers | Caching sits inside Drupal and its reverse proxy, with one set of cache tags to manage. | Caching spans Drupal, the API layer and the front-end host, so invalidation must be designed across all three. Confirm invalidation behavior for each content type. |
| Authentication handling | Drupal manages logins and sessions directly. Contributed modules such as samlauth and OpenID Connect can connect external identity providers. | Front-end users and editors may need token-based access to Drupal's APIs, which must be designed and secured separately. Confirm the token and session model with your security team. |
| Theming and page building | Themes are built in Drupal, and Drupal's own page-building tools serve editors directly. | Themes move to the front-end codebase, so Drupal's theme system and its page-building tools may not apply. Confirm which editorial features still work on the decoupled site. |
| Upgrade scope | A Drupal core upgrade covers the whole site, including themes and templates. | Drupal upgrades affect the API contract, while the front end upgrades on its own schedule. Drupal 12.0.0 is scheduled for the week of December 7, 2026 (Drupal core release schedule), so plan both tracks together. |
| PHP and database requirements | Drupal 11 requires PHP 8.3 or later and Drupal 12 requires PHP 8.5 or later (Drupal.org PHP requirements). Both models need the same platform, including MariaDB, MySQL, PostgreSQL or SQLite. | Same Drupal PHP and database requirements as traditional Drupal, plus a Node.js runtime for the front end. Confirm the Node.js version your framework requires. |
| Team skills needed | Drupal developers, themers and site builders who work in Drupal's templates and configuration. | Drupal developers for content models and APIs, plus front-end engineers for React, Vue or Astro. Confirm whether one team can cover both or whether two teams are needed. |
How decoupled Drupal splits the stack into separate parts
A decoupled build divides one application into parts that each own a job: content, the API, the front end, delivery and access control. Traditional Drupal keeps theme, routing and rendering inside a single application, so a failure usually stays in one place. Splitting the stack moves that risk to the connections between parts, and those connections are what the team must design and operate.
Drupal content model and back end
Drupal owns content types, fields, revisions, translations, roles and editorial workflow. In a decoupled build it no longer renders pages, so editors work in the admin UI while developers decide which fields become API resources. If the content model changes without a matching front-end update, the front end breaks silently. Check which fields editors need, who approves schema changes, and whether the editorial workflow still matters to the front end.
Core JSON:API module
The JSON:API module ships in Drupal core and exposes entities for create, read, update and delete with filtering, includes, pagination, sorting, revisions, translations and file uploads. It is the contract between the two halves, so every API change is a change to the front end. Drupal.org states that the standalone JSON:API project is unsupported because of a security issue, so use the core module. Confirm which resources, fields and access rules are exposed before the front end depends on them.
Front-end application
A React, Vue or Astro application builds routes, layouts, components and client-side behavior that Drupal's theme would otherwise handle. Your team now owns page rendering, accessibility, SEO metadata and preview, none of which Drupal does for you. If this application fails or is misconfigured, visitors see a blank or broken site even while Drupal is healthy. Ask who maintains it, how it is built and deployed, and how it handles content that editors preview before publishing.
Caching and delivery layer
A CDN or reverse proxy sits in front of both the API and the front end, serving cached responses and absorbing traffic spikes. Caching rules must respect Drupal's cache tags so that a published change clears the right responses, and the front end must rebuild or revalidate pages when content changes. Stale content is the most common failure here, and it appears only after an editor publishes. Confirm purge triggers, cache lifetimes for preview and published content, and who responds when a purge fails.
Authentication modules for protected content
When some content sits behind login, modules such as SAML Authentication (samlauth) or the OpenID Connect module handle sign-in for Drupal, and the front end must pass credentials or tokens to the API. The samlauth project lets Drupal act as a SAML service provider, and the OpenID Connect module creates accounts on first sign-in. Each request for protected content must be checked in Drupal, not only in the front end. Confirm which identity provider you use, how sessions and tokens expire, and how JSON:API access rules match the login model.
What the core JSON:API module gives a decoupled build
The JSON:API module ships in Drupal core, so a decoupled build starts without installing a separate package. It implements the JSON:API specification for Drupal entities and provides zero-configuration create, read, update and delete operations for content. That means a React, Vue or Astro front end can query nodes, taxonomy terms and users as soon as the module is enabled, with no custom controller code for basic reads and writes. Install the core version only. Drupal.org states that the standalone JSON:API project is unsupported because of a security issue, so any project plan that pulls in the separate package should be corrected before development begins. The JSON:API module documentation on Drupal.org is the natural next read for the exact endpoint behavior your build will depend on.
The module covers the query features most front ends need: filtering, includes, pagination, sorting, revisions, translations and file uploads. Each one lets a consumer ask for narrower or richer responses, which affects payload size and page speed. Before you commit, test the queries your heaviest pages will send, including nested includes across references and translated content, against a realistic content volume. Confirm how revisions and translations are exposed for each entity type your editors use, since that determines what a preview or multilingual front end can request.
The module does not make the design decisions for you. Your team still owns the content model, including which fields, bundles and references the API exposes. It does not set field-level permissions for each consumer, so decide whether a public site, an authenticated portal and an internal tool should see different fields, and enforce that in Drupal rather than trusting the front end. Preview workflows, rate limiting and caching strategy are also yours to design and test. Ask any implementation partner to document how each of these is handled in writing before the scope is agreed.
Which model suits each team situation
Choose traditional Drupal when editors own page layout and need to see theme output as they work, because Drupal renders the page itself. A decoupled setup splits preview between the CMS and a separate front end, which adds a second rendering path to build, host and keep in sync. Drupal CMS and its visual page builder, Drupal Canvas, are worth evaluating for this workflow, but confirm what they support in your theme and Drupal version before you rely on them.
- Required roles: a site builder or themer who owns the theme, a Drupal developer for custom modules and content editors who will test layouts.
- Tipping decision: whether editors need to arrange components and see the rendered result without a developer release.
- Preview cost: traditional Drupal previews the same theme the public sees, so there is no separate preview pipeline to maintain.
- Upgrade load: core, contributed modules and the theme move together on the Drupal release schedule, so budget for that upkeep in either model.
- Page builder option: test whether Drupal Canvas handles your required components, layouts and workflow on the Drupal version you plan to run.
Before committing, have the team build one landing page that editors change in the tool you plan to use, then confirm the preview matches the production output.
Choose decoupled Drupal when the same content must reach a web app, a mobile app and a documentation site at launch. Drupal serves as a content API for front ends built with frameworks such as React, Vue or Astro. The core JSON:API module provides create, read, update and delete for content with no extra configuration, and it supports filtering, includes, pagination, sorting, revisions, translations and file uploads. Each consumer then adds its own build, hosting and release path, and that is the main cost of this model.
- Required roles: a Drupal back-end developer for content types and API exposure, front-end engineers for each channel and a platform engineer for separate hosting and caching.
- Tipping decision: the number of consumers that exist at launch. One consumer with channels planned for later usually favors traditional Drupal.
- Module source: Drupal.org says the standalone JSON:API project is unsupported because of a security issue, so the core module is the version to plan around.
- Caching and preview: each front end needs its own cache invalidation and preview flow, which you must design and test.
- Ongoing load: plan for front-end maintenance alongside Drupal updates on the Drupal release schedule.
Before committing, list each consumer, its launch scope and the fields it needs, then confirm the API responses cover those fields for the permissions each consumer should have.
A regulated portal with login-gated content must settle where authentication and access control sit. Drupal can act as a SAML service provider through the contributed samlauth module, and the contributed OpenID Connect module lets external providers authenticate users and create accounts on first sign-in. If the front end handles login instead, Drupal and the API still need to decide which content each user may read, and that decision must be enforced on the server.
- Required roles: an identity architect, a security engineer who owns session and access policy, a Drupal developer, a front-end engineer and a compliance lead who needs the evidence.
- Tipping decision: whether the identity provider is the single source of sessions across Drupal and the front end, and whether the team can test denials at each layer.
- samlauth: its latest stable release, 8.x-3.14, supports Drupal 10.3 and later and Drupal 11, so confirm your target version against it.
- OpenID Connect: built-in clients cover generic OAuth 2.0, GitHub, Google, LinkedIn, Facebook and Okta, so confirm that your provider fits one of them or the generic client.
- Enforcement layer: a front-end route guard hides pages but does not by itself protect the API, so test what unauthenticated and lower-privilege requests return.
Before committing, record which layer enforces access for each content type, then send test requests to the API with no session and with a lower-privilege account.
Who runs upgrades, caching and monitoring in each model
This table compares who handles each recurring operating task when Drupal renders pages itself versus when Drupal serves content to a separate front end. Read each row as a question to answer in your own plan: a decoupled build roughly doubles the release tracks and the monitoring surface, while a traditional build concentrates them in one codebase.
| Operating task | Traditional Drupal | Decoupled Drupal (Drupal plus React, Vue or Astro) |
|---|---|---|
| Drupal core upgrades | Your team or partner applies core and contributed module updates to one codebase, with Drupal 10 end of life on December 9, 2026 and Drupal 12 requiring PHP 8.5 in the plan. | The same Drupal upgrade work applies to the back end, and any change to JSON:API responses must be tested against the front end before the back end ships. |
| Front-end framework and dependency updates | Not applicable as a separate track. Theme and Twig or PHP dependencies move with Drupal core. | A separate team or owner keeps the React, Vue or Astro framework, build tools and npm packages current, on its own schedule. |
| Security patch windows | Bugfix releases come on the first Wednesday of each month and security releases on the third Wednesday, so one patch cycle covers the site. | Drupal patches follow the same Wednesday windows, and the front-end dependency tree needs its own advisory review and patch process. |
| Coordinating release tracks | One release train: core, contributed modules and theme ship and get tested together in one environment. | Two release tracks to coordinate. Plan joint test runs so a Drupal update and a front-end deploy do not break content previews or page rendering. |
| Database and file backups | Back up the Drupal database and the public and private file directories together so content and assets restore to the same point. | Back up the Drupal database and file storage as in the traditional model. The front-end host usually holds no content, but confirm where build artifacts and preview data live. |
| Cache purging and invalidation | Drupal's page cache and render cache are purged by Drupal on content change, with reverse proxy purging configured where used. | Content changes must reach the CDN or front-end cache. Confirm how webhooks or rebuilds trigger invalidation, since stale pages are a common failure point. |
| Monitoring the front end and API | One set of uptime, error and performance checks covers rendered pages and the database. | Monitor the front end's pages and the JSON:API endpoints separately, including response shape, status codes and latency for each content type. |
| Skills each task needs | PHP, Drupal configuration management, Drush and web server administration. | Drupal and PHP skills plus JavaScript framework, build pipeline, CDN and API contract testing skills. Confirm both skill sets exist in your team or partner. |
Where front-end hosting, preview and caching add cost
A decoupled Drupal build adds cost in layers that a traditional Drupal site does not carry, so the first decision is to price each layer separately. The front end needs a hosting or build service (static hosting, server-side rendering or an edge platform, depending on whether the React, Vue or Astro app renders at build time or per request). Between the browser and Drupal sits a caching and delivery layer, often a CDN plus Drupal's own page and dynamic caches, and someone must own its cache tags, purge rules and invalidation when editors publish. Each of these is a line item in a quote, and the reader should ask who is paid to configure and operate each one.
Preview is the component most often underestimated. Editors on a traditional site see changes in the rendered page; on a headless build they need a preview flow that fetches unpublished revisions from JSON:API and renders them through the front end, which is engineering work to design and maintain, not a setting. The second dependency tree adds recurring cost: the front-end framework, its build tooling and its packages need patching alongside Drupal's monthly bugfix and third-Wednesday security releases, and integration tests across Drupal and the front end must be rewritten when either side changes. Much of this cost recurs, while the initial build, content model work and preview design are largely one-time, provided the content model stays stable.
Traditional Drupal shifts cost toward theme maintenance and module updates. Drupal's Twig theme, its contributed modules and their compatibility with each major version drive most of the recurring effort, and themes cannot be carried across major versions the way a headless front end sometimes can. To keep a fixed-scope quote comparable, ask the partner to state, for each layer: who builds it, who hosts and patches it, who is on call and for which hours, how cache invalidation is triggered after publishing, and how preview works for unpublished content, including which Drupal endpoints and front-end routes it uses. Ask whether the cost of a Drupal 12 upgrade is included or priced separately, given the scheduled timing in the Drupal core release schedule.
How to decide and phase a move to headless Drupal
This sequence tests whether headless Drupal fits your channels, content model, access rules and editorial workflow before any front end is built. Each step ends with a written output that supports a go, adjust or stay decision.
Map every channel that consumes content
Product, content and platform owners list each place content appears today, such as the main website, a mobile app, kiosks, email or partner feeds, and each channel planned for the next release. For each channel, record the rendering owner, the update frequency and whether it needs Drupal-managed page layouts or only structured data. The output is a channel register with a named owner for each channel. It supports the core decision: if only one channel needs API delivery and the rest need Drupal-rendered pages, a hybrid setup may be easier to run than a full headless build.
Inventory the content model and rendering modules
Site builders and Drupal developers export the content types, fields, paragraphs, views, blocks and contributed modules that generate output, then mark which ones depend on Twig templates or theme logic. They also check that each module exposes data through core JSON:API or needs custom work for the front end. The output is a field-by-field map showing which pieces move to the API and which must be rebuilt. This map drives effort estimates, which should come from your partner's written scope rather than from this page.
Decide where authentication and access are enforced
Security architects and identity owners decide whether Drupal, the front end or an upstream gateway checks user sessions, roles and unpublished content. They confirm which identity option fits the existing directory, such as the contributed SAML Authentication module or the OpenID Connect module, and how JSON:API requests will be authorized for anonymous and logged-in readers. The output is a written access model signed off by security. Teams should confirm with their Drupal partner how each protected route will be tested before the front end starts.
Prototype the editorial preview flow
Editors and a developer build a small clickable prototype that shows how drafts, revisions and scheduled content appear in the new front end before publication. The team records which preview patterns editors can use without a second system and where a preview depends on a separate application. The output is a tested preview specification with editor sign-off. This step often decides the headless question, because a preview gap can require extra tooling and ongoing maintenance that a traditional Drupal site does not need.
Build the front end against JSON:API in staging
Front-end engineers build the chosen framework, such as React, Vue or Astro, against the core JSON:API endpoints in a staging environment that mirrors production Drupal. They test filtering, includes, pagination, translations and file handling against real content volumes, and they set a caching and invalidation plan with the hosting team. The output is a staging build with a documented endpoint list, cache rules and a load test report. Confirm that your Drupal version is on a supported release line before you lock the API contract, since Drupal 10 reaches end of life on December 9, 2026.
Cut over channel by channel
Operations and content leads move one channel at a time to the new front end, starting with the lowest-risk channel from the register. The existing Drupal theme stays live and serving traffic until the replacement for each channel passes its acceptance checks, including search indexing, redirects and analytics. The output is a cutover log per channel with rollback steps and a sign-off date. Once every channel is live, the team retires the old theme, and that retirement is the point where the headless architecture becomes the only delivery path.
Frequently asked questions about decoupled Drupal costs and skills
Does decoupled Drupal cost more to run than traditional Drupal?
Usually yes, because you run two systems instead of one. Drupal still handles content, users, permissions and workflow, but the front end adds its own hosting, build pipeline, deployment process and monitoring. The recurring costs that matter are front-end hosting and CDN usage, the preview environment that editors need to see unpublished content, and the developers who maintain the JavaScript code alongside the PHP. Traditional Drupal has its own recurring costs, including hosting, module updates and the Drupal 11 to Drupal 12 upgrade cycle, so the gap depends on your traffic, caching design and team. Ask any quote to separate one-time build work from annual run costs, and to state who pays for hosting, licenses and on-call support.
What skills does a team need for decoupled Drupal versus traditional Drupal?
Traditional Drupal needs people who can build and maintain PHP modules, Twig themes, site configuration and the Drupal upgrade path. A decoupled model keeps most of that skill set on the back end and adds front-end engineering in React, Vue or Astro, plus API design, caching headers, authentication for the front end and a build and deployment pipeline. Ask a partner or your own leads to name who owns each layer, who handles preview, and who responds when an API change breaks the front end. Confirm that your team can operate both runtimes, because the Drupal side still needs PHP 11 level support while the front end needs its own release discipline.
Can an internal team build a decoupled Drupal site without a partner?
Yes, if the team already has Drupal and front-end engineering experience and can own both halves after launch. The core JSON:API module is part of Drupal core and provides create, read, update and delete for content with no extra configuration, so the API layer does not need a third-party project. The harder work is usually the preview flow, role-based access, caching and deployment, which are where small teams often underestimate effort. Ask whether your staff have built these parts before, and whether a fixed-scope engagement with written deliverables would reduce the risk of learning them on a live project.
How long does a decoupled Drupal build take, and what drives that timing?
No duration in our supplied facts applies to your project, so treat any number from a vendor as a claim to test. Timing is driven by content model complexity, the number of templates and components on the front end, how much preview and editorial workflow you need, the authentication model, and the number of integrations with other systems. Migration from an existing Drupal 7 site adds time because Drupal 6 and 7 sites are migrated into a new site rather than upgraded in place, and themes must be rebuilt. Ask for a written scope that lists each content type, template, integration and environment, and agree on a timeline only after that scope is fixed.
Is JSON:API enough for editorial preview and access control?
JSON:API covers the data side well: it supports filtering, includes, pagination, sorting, revisions, translations and file uploads. It does not by itself give you a finished preview experience or a complete access model, so you must design both. Preview usually needs a route that renders unpublished revisions for authenticated editors, and access control depends on how Drupal roles and entity permissions map to what the front end can request. Use Drupal's own permissions as the source of truth and test that unpublished content never leaks to anonymous requests. For sign-in, the contributed SAML Authentication module supports Drupal as a SAML service provider on Drupal 10.3 and later, and the OpenID Connect module creates accounts on first sign-in. Confirm both fit your identity provider and login flow.
How do Drupal 10 end of life and Drupal 12 PHP requirements affect a decision made now?
Drupal 10 reaches end of life on December 9, 2026, with no new Drupal 10 releases after that date, so a new build should target Drupal 11 or plan for Drupal 12. Drupal 12.0.0 is scheduled for the week of December 7, 2026, and the documented PHP requirements are PHP 8.1 or later for Drupal 10, PHP 8.3 or later for Drupal 11 and PHP 8.5 or later for Drupal 12. Check the date of your decision against the Drupal core release schedule, confirm your hosting supports the PHP version you will need, and ask your partner how the front end will be upgraded when Drupal changes. Decoupling can make a later core upgrade easier to isolate, but it adds a second upgrade track that you must budget for.
How DeployOpen scopes and supports a decoupled Drupal build
DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside the client's own infrastructure, so a decoupled Drupal project is handled as a defined engagement in your cloud account, data center or air-gapped network. Most engagements are fixed-scope, with the decisions on front-end framework, hosting and preview agreed in writing before work starts.
How we scope
- Confirm which content types, editorial workflows and pages stay in Drupal rendering and which move to a headless front end.
- Document the front-end framework choice, hosting target and preview requirements in the written scope before work starts.
- Agree which JSON:API endpoints, authentication method and caching layers the scope covers, along with the Drupal version in use.
How we build
- Implement content models and JSON:API access rules using the core JSON:API module rather than a standalone copy.
- Integrate the chosen front-end build, preview path and cache invalidation inside your infrastructure, with testing against the agreed scope.
- Wire identity integration, such as SAML or OpenID Connect where required, and run security testing on the API and front end.
How we hand over
- Deliver architecture documentation covering the Drupal back end, API contract, front-end deployment and caching design.
- Provide runbooks for content editors, front-end release steps, backups and the Drupal update process your team will follow.
- Walk your platform, front-end and content teams through the handover so the internal owners know how the system is operated.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, which can cover Drupal minor and major upgrades when they fall due.
- Ask any quote to separate one-time build work from recurring retainer work, including who pays for front-end hosting and CDN services.
- Confirm with DeployOpen which upgrade, testing and response commitments a retainer includes before you sign, since terms follow the written scope.
