Headless Drupal

A decoupled architecture in which Drupal stores content and enforces access, and one or more separate front ends read it through an API.

Drupal lernenDrupal-Glossar Last updated October 26, 2026

Headless Drupal means using Drupal only as the content back end. Editors still create, review and publish content in Drupal, but a separate application, built for example with React, Vue or Astro, requests that content through an API and builds the pages visitors see. The same content can feed a website, an app and other channels at once.

How it works in Drupal 11

A standard Drupal site stores content and also renders it, through a theme. A headless setup drops the second job. Drupal exposes its content as data, and the front end fetches it over HTTP. Drupal.org describes the result as a split between the back end, which manages content, and the front end, which presents it.

Drupal 11 core already contains the API layer. The JSON:API module serves entities as JSON, and the core REST module is also available. GraphQL is a contributed alternative. A set of contributed modules fills the gaps that a front end meets:

Decoupled Router turns a front-end path into the matching entity. It follows redirects and aliases, so editors keep control of URLs. It answers requests such as /router/translate-path?path=/recipes/four-hour-stewed-lamb, and its redirect support needs the Redirect module.
Simple OAuth adds OAuth 2.0 authentication for protected API calls.
JSON:API Extras shapes what the API exposes, for example by hiding fields.

Ready-made stacks combine these parts with a front-end framework. The Next.js for Drupal module is one of them. Drupal.org's stack list also names Druxt for Nuxt, Lupus Decoupled, an Octahedroid stack and NodeHive, without saying how actively each is maintained.

Example

A company keeps its articles in Drupal and shows them on a site built with Next.js. An editor saves an article. A visitor opens the front-end address /blog/launch-news. The Next.js application asks Decoupled Router which entity belongs to that path, then requests the article from /jsonapi/node/article and renders the page in its own templates. Drupal never produces the HTML for that visit.

Status and tools

Checked on 26 October 2026: the Next.js for Drupal module is at release 2.1.0 (13 March 2026), supports Drupal 10 and 11, and is developed on GitHub rather than in the drupal.org issue queue. The GraphQL module is at 5.1.0 for Drupal 10.4 and 11, and its 3.x branch is in maintenance mode. Decoupled Router is at 2.0.7 (22 August 2026). The drupal.org pages on decoupled APIs and on getting started show a last update of 12 November 2025, so verify module versions on the project pages before you plan a build.

Common mistakes

Going headless for a simple brochure site. You take on a second application, a second deployment and a second team skill set. A drupal.org page marked as needing work (last updated 31 October 2022) notes that layout is controlled on the front end and that Layout Builder will not work out of the box.
Forgetting the editor side. Previews, URL changes and redirects are not free. Test them with a real editor before launch.
Leaving the API open. A public front end is not a reason to expose private fields. Entity and field access still decide what each caller sees, so test with an anonymous request too.

For marketing and content teams

A headless site changes how your work reaches the page. You keep the editing forms in your CMS, but page design and layout live in the front-end code, so a new landing page layout can mean a developer ticket. Ask three questions before you agree to the architecture: can I preview a draft on the real front end, who changes layouts and how fast, and which channels will use this content. If the answer to the third is only one website, a standard Drupal site is worth comparing.

Sources

Questions about Headless Drupal

Drupal.org uses the two names for the same idea. Its Decoupled Drupal documentation opens with "Decoupled Drupal, or headless Drupal" and says it separates the back end (content management) from the front end (presentation layer).

Drupal core ships JSON:API, and drupal.org's stack list names it as the primary API of Next.js for Drupal. GraphQL is the alternative: it comes from the contributed GraphQL module, and the same list shows an Octahedroid stack that uses it as its primary API. Of the API options on drupal.org's modules page, only JSON:API is stated to be in core.

Only if the front end supports it. The Next.js for Drupal module lists iframe previews, multi-site previews and revision previews as features, so that stack has an answer. For any other front end, ask the developer how a draft reaches the preview before you commit to the architecture.

Yes, two settings need a decision. A browser front end on another domain needs CORS, which is disabled by default: cors.config in services.yml ships with enabled: false. Private content also needs authentication, for example OAuth 2.0 through the Simple OAuth module, whose latest release is 6.1.3 from 21 October 2026.

Cite this definition

"Headless Drupal." DXPR Drupal glossary, https://dxpr.com/hc/documentation/learn-drupal/drupal-glossary/headless-drupal. Last updated October 26, 2026.

Related terms

All Drupal terms from A to Z