Building Headless Drupal with Next.js: API-First Development in 2025

A headless CMS separates the backend content repository from the frontend presentation layer. This decoupling allows content to be managed centrally and delivered across websites, mobile apps, and IoT devices via APIs.

• Flexibility: Choose any frontend technology like Next.js for content presentation
• Scalability: Reuse content across multiple channels without duplication
• Performance: Leverage SSG and SSR for faster load times and improved user experiences

1. Configure Drupal: Enable the JSON:API module and set up CORS in services.yml to allow Next.js requests
2. Initialize Next.js: Create a project with npx create-next-app and install the next-drupal package for simplified data fetching
3. Fetch Data: Use DrupalClient to retrieve content collections and individual resources via JSON:API endpoints
4. Dynamic Routing: Implement getStaticPaths and getStaticProps with ISR for dynamic article pages
5. Rich Media: Use JSON:API Extras for field-level control and handle nested media entities with include parameters

• Static Site Generation: Use getStaticProps() for most content pages with ISR via revalidate
• Image Optimization: Leverage Next.js <Image /> component for lazy loading and responsive images
• CDN & Caching: Use Fastly or Cloudflare CDN, Varnish for JSON:API endpoints, and SWR/react-query for client-side caching
• SEO Benefits: Full control over meta tags, schema, and Open Graph with improved Core Web Vitals

• GraphQL Support: Drupal’s GraphQL module provides more flexibility than REST/JSON:API
• Decoupled Menus: The Decoupled Menus Initiative simplifies menu exports via JSON:API
• Preview Mode: Next.js preview APIs integrate better with Drupal for real-time content previews
• AI Integration: Tighter integrations between AI-powered personalization and headless CMS setups

Drupal's JSON:API module (included in core since Drupal 9) exposes content entities as RESTful endpoints following the JSON:API specification. Every content type, taxonomy, media entity, and custom entity is automatically available with filtering, sorting, pagination, and relationship inclusion — no custom endpoint development required.

Configure JSON:API for production: enable read-only mode for public-facing APIs, configure field-level access control using Drupal's permission system, set up CORS headers for your Next.js domain, and implement API caching with Varnish or Drupal's internal page cache. Use the jsonapi_extras module to customize resource names, disable unused endpoints, and configure field aliasing for cleaner API responses.

Choose the right Next.js rendering strategy per page type: Static Site Generation (SSG) with getStaticProps for content that changes infrequently (blog posts, about pages), Incremental Static Regeneration (ISR) for content updated regularly (product pages, news), and Server-Side Rendering (SSR) with getServerSideProps for personalized or real-time content.

Use the next-drupal package for streamlined integration: it handles JSON:API fetching, entity resolution, preview mode, and path aliasing. Implement Drupal's preview mode to let editors see draft content in the Next.js frontend before publishing — connecting Drupal's editorial workflow with the decoupled frontend seamlessly.

Content preview is the biggest UX challenge in headless architectures — editors need to see how content looks on the frontend before publishing. Implement Next.js Preview Mode: Drupal sends a preview request to a Next.js API route that sets a preview cookie, enabling draft content rendering. The preview URL is configured in Drupal's content editing interface.

Enhance editorial experience with live preview: use Drupal's Simple OAuth module for secure API authentication, implement iframe-based preview in Drupal's admin sidebar, and add real-time content refresh using webhooks or polling. This closes the editorial gap that makes headless CMS adoption challenging for non-technical content teams.

MetaDesign Solutions builds headless Drupal architectures with Next.js frontends — combining Drupal's enterprise content management capabilities with Next.js's performance and developer experience. Our team handles API configuration, frontend development, content preview setup, and deployment architecture.

Services include headless Drupal architecture design, JSON:API configuration and optimization, Next.js frontend development, content preview and editorial workflow setup, migration from monolithic Drupal to headless, and ongoing CMS management. Contact MetaDesign Solutions for headless Drupal solutions that deliver fast frontends with powerful content management.