Drupal and React: The Complete Guide for 2026

Drupal and React is one of the most common decoupled CMS pairings you’ll see in production. The reasons are structural: Drupal is one of the few open-source CMSs with genuinely mature editorial features, and React is the dominant frontend framework for complex interactive UIs. Pair them and you get the best of both — if you set it up correctly.

But “use Drupal with React” can mean three very different architectures, and the one you pick determines almost everything about how your project goes. This guide walks through each option, when to use it, and what to watch out for.

The three ways to use Drupal + React

1. Fully decoupled (headless)

Drupal serves content via JSON:API or GraphQL. React (usually as a Next.js or Vite app) is a completely separate application that fetches from the API. Visitors never see Drupal-rendered HTML.

This is the cleanest separation. The Drupal site is hosted at admin.yoursite.com; the React app is hosted at yoursite.com. They share nothing at the HTML level. Editors log in to Drupal and see Drupal’s admin UI; everyone else sees the React app.

When to use fully decoupled:

You want a modern frontend DX (component libraries, Next.js App Router, React Server Components).
Your frontend needs to be fast and do things Drupal’s render pipeline can’t (streaming, ISR, server components).
You have frontend engineering capacity. This path always requires more frontend work than you expect.
Your content model is stable. Decoupled setups don’t love rapid, on-the-fly content model changes because every change means updating the API contract.

When fully decoupled is the wrong call:

You don’t have a dedicated frontend team or React expertise.
Your editors expect WYSIWYG / visual layout control. Fully decoupled means they get form-based editing.
You’re on a tight budget. Preview, auth, and deploy plumbing are real work.

2. Progressively decoupled

Drupal still renders most of the page using Twig templates — but specific regions (a product configurator, an interactive map, a dashboard) get replaced with React components at runtime. The React components fetch their data from the same Drupal backend they’re embedded in.

This is a middle path. Editors still get Drupal’s full templating and preview experience. Developers get React freedom for the parts of the page that need it.

When to use progressively decoupled:

Most of your pages are static content where Drupal’s Twig is fine.
You have a few high-interaction zones (search, filters, calculators) where React is much better than vanilla JS or jQuery.
Your frontend and backend teams are the same people, or you can’t justify two separate deploy pipelines.
You want a gradual migration path — start progressive, eventually decouple fully.

When progressive decoupling is the wrong call:

Your whole site is interactive (app-like). The mixed model adds complexity without upside.
You hate maintaining two rendering systems in one repo. Some teams do; some don’t.

3. Hybrid (gradual migration)

Drupal serves some routes; React (via Next.js) serves others. A routing layer (typically at the CDN or with Next.js rewrites) decides which backend handles which URL.

This is the pragmatic option when you’re migrating a big old Drupal site and can’t rewrite everything at once. Start with the homepage and top landing pages in Next.js, leave /blog/* and /about/* on Drupal, and migrate one section at a time.

When to use hybrid:

Big legacy Drupal site with hundreds or thousands of URLs.
You can’t afford a Big Bang launch.
You want to ship a modern frontend on the money pages first and migrate the long tail later.

When hybrid is the wrong call:

Small site (less than 50 pages). Just do it fully decoupled from day one.
You don’t have the CDN/routing expertise to set up the split cleanly. It’s easy to ship cache invalidation bugs.

The decision tree

Here’s how to actually pick:

Is your site mostly static content? → Fully decoupled. Drupal for content management, Next.js/Astro/Vite for the frontend, done.
Is your site mostly already Drupal and you have a few interactive zones? → Progressively decoupled. Keep Twig templates; add React where it helps.
Do you have a big legacy Drupal site you’re modernizing over 6-12 months? → Hybrid. Split at the CDN, migrate section by section.

Most teams come to us thinking they want option 1 and should be doing option 2 or 3. The pull toward “let’s just rewrite everything in Next.js” is strong — and often wrong. The right question isn’t “should we use React?” but “which parts of our current Drupal site are genuinely better in React, and which parts are fine in Twig?”

How the data flow works (fully decoupled)

In a fully decoupled setup, here’s what happens on a typical page load:

User requests yoursite.com/about.
Next.js (or your React app) receives the request and calls api.yoursite.com/jsonapi/node/page?filter[path.alias][value]=/about.
Drupal responds with a JSON payload — node data, field values, related entities.
Next.js renders the React components with that data and returns HTML to the user.
React hydrates on the client for interactivity.

With Next.js App Router and React Server Components, step 4 happens on the server. With Vite or classic Next.js pages, it happens in the browser. The choice affects SEO and performance.

For preview, the flow is different: the editor is logged in to Drupal, clicks “Preview,” and gets redirected to a special preview URL on the frontend. The frontend sees a preview token in the URL, passes it to the Drupal API, and Drupal responds with draft content instead of published content. This is the #1 thing teams underestimate about decoupled Drupal — preview is its own engineering effort, not something you get for free.

What about Drupal’s own React support?

Drupal has several contrib modules and core features that touch React:

react contrib module — provides helpers for embedding React apps in Drupal blocks. Useful for progressive decoupling.
Reactify theme — a starter theme that uses React for rendering. Useful for experimentation, not what we’d recommend for production.
Drupal Canvas + React — an experimental path for building Drupal pages with React components. Still early.

None of these replace “just run Drupal headless and build a Next.js frontend.” But if you’re going progressive, the react module is a reasonable starting point.

Common mistakes we see

1. Skipping preview until the end. Teams build the frontend, test with published content, launch, and then discover editors can’t preview drafts. Build preview infrastructure in the first two weeks, not the last two.

2. Not thinking about the content model in API terms. Drupal lets you build arbitrarily complex nested content types (Paragraphs inside Paragraphs inside Layout Builder sections). It all works via JSON:API but the resulting queries become unwieldy. Design your content model with the API contract in mind — flat is better than deeply nested.

3. Hardcoding asset URLs. File fields in Drupal return full URLs that point to the Drupal backend domain. If you don’t rewrite or proxy them, your “headless” frontend ends up loading every image from api.yoursite.com, which defeats the point. Set up a proper asset proxy or CDN rewrite.

4. Not handling the 404 correctly. When a URL doesn’t exist in Drupal, the JSON:API returns an empty result, not a 404. Your frontend needs to detect this and return a 404 itself, or you’ll end up serving 200 responses with empty content — bad for SEO.

5. Forgetting authentication for logged-in users. If your site has user accounts, you need to decide: does Drupal own the auth, or does a separate service (Auth0, Clerk, etc.)? Both work, but you need to pick early, not in month four.

What stack to actually use

If you’re starting fresh and want our opinionated recommendation:

Backend: Drupal 10 or 11, jsonapi core module enabled, jsonapi_extras for fine-grained control, next contrib for preview tunneling, pathauto + redirect for URL management.
Frontend: Next.js App Router on Vercel. Use Server Components for content pages, Client Components for interactive bits. Set up ISR with tag-based revalidation so Drupal can push cache invalidation when content changes.
Content model: Flat content types with reference fields, not deep Paragraphs trees. Use Media Library for images, and set up responsive image styles upfront.
Dev environment: Lando or DDEV for Drupal, next dev for frontend. Point Next.js at the Lando Drupal URL in dev; point it at production Drupal in prod.

TL;DR

“Use Drupal with React” is three different architectures. Fully decoupled gives you the cleanest separation and the modern frontend DX. Progressively decoupled is the pragmatic middle path for sites that are mostly fine in Twig. Hybrid is the way to migrate a big legacy site section by section. Most teams pick the wrong one initially because the allure of “rewrite it all in React” is strong. The right answer depends on your site shape, team capacity, and migration budget.

If you’re evaluating which approach is right for your Drupal site, we do free 30-minute audit calls — and we’ll tell you honestly if “rewrite it in React” isn’t the right answer. Sometimes it isn’t.