Headless Drupal with Next.js: Building Lightning-Fast Frontends

A headless CMS separates the backend (content storage and management) from the frontend (presentation layer). In headless Drupal, the CMS acts purely as the backend content repository and exposes content via RESTful API, JSON:API, or GraphQL endpoints, enabling modern frontend frameworks such as Next.js, React, or Vue.js to build the frontend independently. This architectural separation fundamentally changes how teams build and maintain websites — content editors continue using Drupal's familiar admin interface while frontend developers work with modern JavaScript tooling and component-based architectures.

• Flexibility: Choose the frontend technologies that best meet your requirements — React, Vue.js, Svelte, or any framework that consumes APIs
• Faster Development: Frontend and backend teams work independently with separate deployment pipelines and release cycles
• Omnichannel Delivery: Deliver content to websites, mobile apps, smart devices, digital kiosks, and voice assistants from a single content source
• Better Performance: Decoupled rendering with SSG/SSR enables sub-second page loads impossible with Drupal's traditional PHP rendering

Drupal provides two mature API modules for headless implementations, each with distinct advantages. JSON:API (included in Drupal core since 10.x) follows the JSON:API specification — providing standardised, RESTful endpoints for every content entity with automatic filtering, sorting, pagination, and relationship inclusion via ?include= parameters. JSON:API is zero-configuration: once enabled, every content type, taxonomy, media entity, and user profile is immediately available via predictable URLs like /jsonapi/node/article. GraphQL (via the contributed graphql module) offers schema-first API design where the frontend requests exactly the fields it needs in a single query — eliminating over-fetching and reducing API payload sizes by 40–60%. GraphQL excels for complex content architectures with deeply nested relationships (articles → authors → profiles → images) where JSON:API would require multiple include parameters. For most projects, JSON:API is recommended due to its zero-configuration core support and Drupal's excellent integration with the next-drupal library, while GraphQL is preferred for teams already using GraphQL across their stack or requiring complex query patterns.

• Static Site Generation (SSG): Pre-render pages at build time using generateStaticParams() for blazing-fast load times — product pages, blog posts, and landing pages served as static HTML from CDN edge nodes
• Server-Side Rendering (SSR): Render dynamic content on the server for personalised pages, search results, and authenticated experiences with full SEO compatibility
• Incremental Static Regeneration (ISR): Update static pages on-demand without rebuilding the entire site — when content changes in Drupal, only the affected pages are regenerated
• App Router Architecture: Next.js 14+ App Router with React Server Components enables streaming, parallel data fetching, and fine-grained caching strategies per route segment
• API Routes: Server-side API routes handle form submissions, authentication, and Drupal webhook processing without exposing Drupal credentials to the client
• Image Optimization: Next.js Image component automatically optimises Drupal media images with responsive sizing, WebP/AVIF conversion, and lazy loading

1. Content Management in Drupal: Editors create and manage content through Drupal's admin interface with structured content types, media library, and editorial workflows (Draft → Review → Published)
2. API Exposure: Drupal exposes content via JSON:API or GraphQL endpoints with CORS configured for the Next.js domain. Authentication uses OAuth 2.0 or API keys for protected content
3. Next.js Data Fetching: Next.js App Router uses async Server Components to fetch data at the route level — static routes use generateStaticParams() with ISR revalidation, dynamic routes use server-side fetching with caching directives
4. Webhook-Triggered Revalidation: Drupal sends webhooks on content save/publish events to Next.js API routes, which call revalidatePath() or revalidateTag() to purge and regenerate affected pages in under 2 seconds
5. CDN Deployment: Next.js deploys to Vercel, Netlify, or self-hosted Node.js servers with edge caching — static pages are served from 100+ global CDN nodes for sub-50ms TTFB worldwide

The next-drupal library (maintained by Chapter Three) is the de facto standard for connecting Next.js with Drupal — providing type-safe data fetching, content preview, and on-demand revalidation out of the box. Key features include: DrupalClient for authenticated API requests with automatic token management, getResource() and getResourceCollection() helpers that handle JSON:API include parameters, filtering, and pagination with TypeScript types generated from Drupal's content model. Draft Mode integration enables content editors to preview unpublished changes in the Next.js frontend before publishing — clicking "Preview" in Drupal's admin opens the Next.js site with draft content rendered in real-time. On-demand ISR is triggered via Drupal webhooks — when an editor publishes an article, only that article's page (and any listing pages referencing it) are regenerated, keeping the rest of the site statically cached. The library also provides search_api integration for faceted search, metatag module support for SEO metadata, and path alias resolution for clean URLs.

Effective headless Drupal implementations require API-first content modeling — structuring content types for programmatic consumption rather than visual rendering. Structured content over rich text: Instead of a single WYSIWYG body field, model content as granular components — Hero, Text Block, Image Gallery, CTA, Testimonial — each as a Paragraph type (via Drupal's Paragraphs module) or Layout Builder section. This enables the Next.js frontend to render each component with purpose-built React components rather than parsing arbitrary HTML. Media entities: Use Drupal's Media module with image styles configured for responsive breakpoints — the API exposes multiple image derivatives (thumbnail, card, hero) that Next.js selects based on context. Taxonomy strategy: Design vocabularies as API-filterable dimensions — categories, tags, regions, content types — enabling the frontend to build dynamic listing and filtering experiences. Entity references: Model relationships explicitly (Article → Author, Article → Related Articles, Page → Menu) so the API delivers navigable content graphs rather than flat data. Translation support: Drupal's multilingual system exposes content in all enabled languages through the API, enabling Next.js to build locale-specific routes with automatic language detection.

A critical advantage of headless Drupal over headless-only CMS platforms (Contentful, Sanity) is Drupal's mature editorial workflow system. Draft Preview: The next-drupal library enables seamless preview mode — editors click "Preview" in Drupal and are redirected to the Next.js frontend where unpublished content renders exactly as it will appear after publishing, including all component layouts and media. Content Moderation: Drupal's Content Moderation module provides configurable states (Draft → Review → Published → Archived) with role-based permissions — only editors with the Publisher role can move content to Published state, triggering ISR regeneration. Revision History: Every content change is tracked with full revision history — editors can compare versions, revert changes, and understand who modified what. Scheduled Publishing: The Scheduler module enables future-dated publishing and unpublishing — Next.js polls for scheduled changes via cron-triggered webhooks, ensuring time-sensitive content (promotions, announcements) goes live automatically. Workflow Notifications: Email and Slack notifications alert reviewers when content is submitted for review, ensuring timely editorial processes.

• CDN Caching Strategy: Use stale-while-revalidate headers for static pages — visitors always get cached content instantly while ISR regenerates pages in the background after content changes
• SSG for Core Pages: Pre-render high-traffic pages (homepage, product pages, blog archive) at build time with generateStaticParams() for zero-latency serving from CDN edge
• ISR Revalidation: Set revalidation intervals per content type — blog posts revalidate on webhook trigger (near-instant), product listings revalidate every 60 seconds, navigation menus revalidate every 5 minutes
• API Response Caching: Cache Drupal API responses at the Next.js server level using React Server Component cache directives — preventing redundant API calls for shared data (menus, footers, global settings)
• Image Pipeline: Serve Drupal media through Next.js Image optimization or a dedicated image CDN (Cloudinary, Imgix) with automatic format selection, responsive sizing, and aggressive caching