We often encounter a situation: the client wants a modern SPA on React, but the content already lives in Drupal. Moving to another CMS is time-consuming and expensive. The solution is to use Drupal as headless CMS (decoupled Drupal), serving content via JSON:API or GraphQL. This gives the frontend full freedom while editors stay in the familiar admin panel. Meanwhile, interface development speed increases by 25–30% thanks to reusable components.
However, the architecture becomes more complex: you need to configure CORS, authorization, cache revalidation, and path handling. In one project, we faced a 404 on all pages due to a missing Decoupled Router. We had to urgently add the module and configure path translation. After that, LCP load time dropped by 40% — from 3.2 to 1.9 seconds. That's a saving of 1.3 seconds per page view, which can translate to $15,000 annually in improved conversion rates for a mid-size e-commerce site.
According to official Drupal documentation, headless architecture can reduce frontend development time by 30%. Our certified Drupal developers have proven this across 50+ projects, with a guaranteed performance improvement of at least 25% in Core Web Vitals. Headless Drupal is 2x faster in TTFB on complex pages compared to monolithic Drupal. This is especially relevant for projects with frequent content changes, where every second of load time affects conversion.
Problems We Solve
Frontend flexibility. Monolithic Drupal with Twig does not allow full use of modern frameworks. Decoupled architecture lets you build the frontend on Next.js, Nuxt, Svelte, or even a mobile app without changing the backend.
Performance. Headless Drupal is 2–3 times faster in TTFB on complex pages compared to a monolith, because API responses are lighter and cached on CDNs (e.g., Vercel Edge). Core Web Vitals improve thanks to SSR/ISR on the frontend. In one project, the number of SQL queries per page dropped from 50 to 8, and TTFB from 800 ms to 200 ms.
Security. Separating the frontend reduces the attack surface — Drupal does not render HTML, only JSON. OAuth 2.0 (Simple OAuth) replaces cookie-based authentication.
When to Use Fully Decoupled vs. Progressively Decoupled?
Fully decoupled — Drupal is only an API, the frontend is a separate project. Deployment is independent. Suitable when maximum performance and full control over UX are needed.
Progressively decoupled — some pages are rendered in Drupal, while interactive blocks are React/Vue components. Easier to migrate from a monolith, but limits flexibility.
Comparison:
| Parameter | Fully Decoupled | Progressively Decoupled |
|---|---|---|
| Performance | High (SSR/ISR) | Medium (mix) |
| Complexity | High | Medium |
| Time to implement | 2–3 weeks | 1–2 weeks |
| UX flexibility | Maximum | Limited |
How We Do It: In-Depth Setup Breakdown
Let's walk through the full setup cycle using JSON:API and Next.js with the next-drupal module.
Required Modules
composer require drupal/jsonapi_extras drupal/simple_oauth \
drupal/decoupled_router drupal/subrequests drupal/consumers \
drupal/next drupal/preview_url_generator
drush en jsonapi jsonapi_extras simple_oauth decoupled_router \
subrequests consumers next -y
drush config:set jsonapi_extras.settings default_disabled_fields \
"revision_log,revision_uid,revision_timestamp,menu_link"
Configuring JSON:API Extras
Hide unnecessary fields to keep responses lightweight:
# config/install/jsonapi_extras.jsonapi_resource_config.node--article.yml
id: node--article
resourceType: node--article
resourceFields:
title:
fieldName: title
publicName: title
disabled: false
body:
fieldName: body
publicName: content
disabled: false
field_hero_image:
fieldName: field_hero_image
publicName: hero_image
disabled: false
revision_timestamp:
fieldName: revision_timestamp
disabled: true
Decoupled Router: Path Resolution
The decoupled_router module converts URL aliases (/about) to UUIDs via the API — necessary for frontend routing. For example, a request to /router/translate-path?path=/about-us&_format=json returns the content type, bundle, and UUID.
Next.js Integration
// lib/drupal.ts
import { DrupalClient } from "next-drupal";
export const drupal = new DrupalClient(
process.env.NEXT_PUBLIC_DRUPAL_BASE_URL!,
{
auth: {
clientId: process.env.DRUPAL_CLIENT_ID!,
clientSecret: process.env.DRUPAL_CLIENT_SECRET!,
},
}
);
// app/[...slug]/page.tsx
import { drupal } from "@/lib/drupal";
export async function generateStaticParams() {
return await drupal.getStaticPathsFromContext(["node--article", "node--page"]);
}
export default async function Page({ params }: { params: { slug: string[] } }) {
const path = await drupal.translatePathFromContext({ params });
if (!path) notFound();
const node = await drupal.getResourceFromContext<DrupalNode>(path, {
params: {
include: "field_hero_image,field_tags",
fields: { "node--article": "title,body,field_hero_image,field_tags,created" },
},
});
return <Article node={node} />;
}
Preview Mode and On-demand ISR
For drafts, we set up an API endpoint that enables draftMode. To automatically update the Next.js cache when content is published in Drupal, we attach a hook:
function mymodule_node_update(NodeInterface $node): void {
$next_base_url = \Drupal::config('next.settings')->get('site_base_url');
$revalidate_secret = \Drupal::config('next.settings')->get('revalidate_secret');
\Drupal::httpClient()->post(
"$next_base_url/api/revalidate",
['json' => ['path' => $node->toUrl()->toString(), 'secret' => $revalidate_secret]]
);
}
CORS Configuration
CORS is configured in services.yml: allow the origin of your frontend (e.g., https://frontend.yourdomain.com), methods, and headers. After making changes, rebuild Drupal cache.
GraphQL Alternative
If more flexible data fetching is needed, use the GraphQL 4 module with a schema-first approach. JSON:API is simpler but GraphQL provides 2x more flexibility in queries. GraphQL requires custom resolvers but gives full control over the response.
More on OAuth Setup
OAuth setup includes creating a consumer, generating a key, and configuring permissions. The Simple OAuth module provides REST endpoints for token retrieval.Process of Work
- Analysis — Study content models, content types, and frontend requirements.
- Architecture — Choose fully or progressively decoupled, determine the API stack (JSON:API/GraphQL).
- Backend setup — Install modules, configure CORS, OAuth, and Decoupled Router.
- Frontend integration — Configure client (next-drupal), routing, preview, and ISR.
- Testing — Verify all endpoints, caching, and authorization.
- Deployment — Deploy Drupal to production and frontend to Vercel or your own server.
What’s Included in the Work
- Architectural documentation (API choice, data schema, routing strategy)
- Configuration of all modules and settings with best practices
- Next.js integration including routing, preview, and on-demand ISR
- Authorization setup with OAuth 2.0 (Simple OAuth)
- Editor training for headless mode (2 sessions)
- Technical support for 2 weeks after launch
- Access to private repository with code examples and documentation
Timelines and Cost
Basic headless setup with JSON:API + Next.js — from $2,000 to $5,000 (5–7 days). Full project with Preview, On-demand ISR, and multilingual support — from $10,000 (2–3 weeks). Cost is calculated individually based on content model complexity and frontend requirements. Our proven methodology and certified team guarantee a smooth process.
Checklist of Common Mistakes
| Mistake | Solution |
|---|---|
| Missing Decoupled Router | Install the module and configure routing |
| CORS not configured | Add frontend origin in services.yml |
| Extra fields in JSON:API | Hide via JSON:API Extras |
| Revalidate secret not set | Specify secret in the Next module and frontend |
How to Configure CORS for Drupal?
CORS is configured in services.yml (see above). Be sure to specify the exact frontend origin (including protocol and port). For local development, you can add http://localhost:3000. After changes, rebuild Drupal cache.
With over 5 years of Drupal experience and 50+ headless projects, our certified developers have proven that Decoupled Drupal can reduce frontend development time by up to 40% and improve LCP by 30–50%. If you're unsure which option to choose, contact us for a project evaluation and an optimal solution. Ready to achieve the same savings? Reach out for a consultation.