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

Introduction

In the rapidly evolving landscape of web development, the decoupling of content management systems (CMS) from frontend frameworks has become a prevailing trend. This approach, known as headless architecture, offers enhanced flexibility, scalability, and performance. As we navigate through 2025, integrating Drupal—a robust and versatile CMS—with Next.js—a powerful React-based framework—has emerged as a leading solution for developers aiming to build dynamic, high-performance websites. This comprehensive guide delves into the process of building a headless Drupal application with Next.js, highlighting the benefits, setup procedures, best practices, and future trends in API-first development.

Understanding Headless CMS and Its Advantages

A headless CMS separates the backend content repository from the frontend presentation layer. This decoupling allows developers to manage content centrally and deliver it across various platforms—websites, mobile apps, IoT devices—via APIs. The key advantages include:

Flexibility: Developers can choose any frontend technology to present content, enabling the use of modern frameworks like Next.js.
Scalability: Content can be reused and delivered across multiple channels without duplication, streamlining content management.
Performance: By leveraging static site generation and server-side rendering, applications can achieve faster load times and improved user experiences.

Why Combine Drupal with Next.js?

Drupal development services has long been recognized for its robust content management capabilities, while Next.js offers a powerful framework for building fast and user-friendly interfaces. Integrating the two provides:

Robust Content Management: Drupal’s mature CMS features facilitate complex content organization and workflows.
Modern Frontend Development: Next.js enables the creation of responsive, dynamic, and performant user interfaces.
Enhanced Developer Experience: The combination allows for the use of React components, facilitating component-based development and reusability.

This synergy enables developers to harness the strengths of both platforms, resulting in a seamless and efficient development process.

Setting Up Headless Drupal with Next.js

Prerequisites

Before initiating the integration, ensure you have the following:

Drupal Installation: A running instance of Drupal 10 or 11.
Node.js Environment: Node.js installed on your system to run Next.js applications.
Basic Knowledge: Familiarity with React and JavaScript ES6+ syntax.

Step 1: Configure Drupal for Headless Operation

Enable JSON:API Module: Drupal’s core includes the JSON:API module, which exposes entities as JSON endpoints. Ensure it’s enabled by navigating to Extend and activating the JSON:API module.

Set Up CORS (Cross-Origin Resource Sharing): To allow your Next.js application to fetch data from Drupal, configure CORS by editing the services.yml file:

yaml code:

🚀 Building Headless in 2025? Let’s Future-Proof Your Drupal Stack!

Harness the power of Headless Drupal with Next.js for lightning-fast performance, seamless user experiences, and true API-first flexibility. Whether you’re building SPAs, PWAs, or enterprise-grade platforms, we specialize in crafting decoupled solutions that scale.

🧠 Stay ahead of the curve with expert guidance from a leading Drupal development company.

📩 Get in touch today for a free consultation and start your journey to modern, headless architecture!

				
					cors.config:
  enabled: true
  allowedHeaders: ['*']
  allowedMethods: ['GET', 'POST', 'PATCH', 'DELETE', 'OPTIONS']
  allowedOrigins: ['*']
  exposedHeaders: true
  maxAge: 1000
  supportsCredentials: false

2. Adjust the allowedOrigins to match your Next.js application’s domain in a production environment.

3. Create and Manage Content: Utilize Drupal’s admin interface to create content types and add content. These will be accessible via JSON:API endpoints.

Step 2: Set Up Next.js Application

Initialize Next.js Project: Create a new Next.js application:

bash code:

				
					npx create-next-app my-nextjs-app

Navigate to the project directory:

bash code:

				
					cd my-nextjs-app

Install Required Packages: To interact with Drupal’s JSON:API, install the next-drupal package:

bash code:

				
					npm install next-drupal

2. This package simplifies data fetching and integration between Next.js and Drupal.

Configure Environment Variables: Create a .env.local file in the root of your Next.js project and add your Drupal site’s base URL:

ini code:

				
					NEXT_PUBLIC_DRUPAL_BASE_URL=https://your-drupal-site.com

3. Replace https://your-drupal-site.com with your actual Drupal URL.

Step 3: Fetch Data from Drupal in Next.js

Set Up the Drupal Client: In your Next.js project, create a lib directory and add a drupal.js file:

javascript code:

				
					import { DrupalClient } from "next-drupal"

export const drupal = new DrupalClient(
  process.env.NEXT_PUBLIC_DRUPAL_BASE_URL
)

Fetch and Display Data: In your Next.js pages or components, use the drupal client to fetch data. For example, to retrieve articles:

javascript code:

				
					import { drupal } from "../lib/drupal"

export async function getStaticProps() {
  const articles = await drupal.getResourceCollection("node--article")

  return {
    props: {
      articles,
    },
  }
}

export default function ArticlesPage({ articles }) {
  return (
    <div>
      {articles.map((article) => (
        <div key={article.id}>
          <h2>{article.title}</h2>
          <p>{article.body.summary}</p>
        </div>
      ))}
    </div>
  )

Step 4: Dynamic Routing in Next.js for Drupal Content

To handle dynamic pages (e.g., individual articles, pages, or custom content types), you can use dynamic routes in Next.js.

Example: Dynamic Route for Articles

Create a new file: pages/articles/[slug].js

js code:

				
					import { drupal } from "../../lib/drupal"
import { useRouter } from "next/router"

export async function getStaticPaths() {
  const articles = await drupal.getResourceCollection("node--article")

  const paths = articles.map((article) => ({
    params: { slug: article.path.alias.replace("/articles/", "") },
  }))

  return {
    paths,
    fallback: "blocking",
  }
}

export async function getStaticProps({ params }) {
  const article = await drupal.getResourceFromPath(`/articles/${params.slug}`)

  if (!article) {
    return { notFound: true }
  }

  return {
    props: {
      article,
    },
    revalidate: 60,
  }
}

export default function ArticlePage({ article }) {
  const router = useRouter()
  if (router.isFallback) return <p>Loading...</p>

  return (
    <article className="prose mx-auto">
      <h1>{article.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: article.body.processed }} />
    </article>
  )
}

This setup enables SSG (Static Site Generation) for individual article pages using their Drupal path alias.

Step 5: Content Modeling and Rich Media Handling

Drupal’s field API and media module are powerful for content modeling. Ensure the following when integrating:

Use JSON:API Extras: To control field-level exposure and alias routes.
Media Entities: For images, you’ll often need to fetch nested data. Use include and fields query params with next-drupal.

js code:

				
					await drupal.getResourceCollection("node--article", {
  params: {
    "include": "field_image",
    "fields[node--article]": "title,field_image",
    "fields[media--image]": "name,field_media_image",
    "fields[file--file]": "uri,url",
  },
})

For image rendering, you may want to create a helper to convert Drupal file paths into public URLs using:

js code:

				
					function absoluteURL(uri) {
  return `${process.env.NEXT_PUBLIC_DRUPAL_BASE_URL}${uri.url}`
}

Step 6: Authentication and Access Control

While most headless sites are publicly accessible, you may need authenticated access:

Basic Auth or OAuth: Use Drupal’s OAuth2 server (OAuth2 Client) to get tokens.
Session Management: Handle token refreshes or session storage in local/sessionStorage.
Protected Content: Use Drupal permissions to expose specific resources only to certain user roles.

You can fetch authenticated resources using the drupal.fetch() method with headers:

js code:

				
					await drupal.fetch("/jsonapi/node/article", {
  headers: {
    Authorization: `Bearer ${token}`,
  },
})

Performance Optimization for Headless Drupal with Next.js

Static Site Generation (SSG)

Next.js enables pre-rendering content at build time, significantly improving load speed and SEO.

Use getStaticProps() for most content pages.
Use revalidate to enable Incremental Static Regeneration (ISR).

Image Optimization

Use Next.js <Image /> component for performance gains like lazy loading and responsive images. For Drupal images:

js code:

				
					import Image from "next/image"

<Image
  src={absoluteURL(article.field_image.uri)}
  width={800}
  height={500}
  alt={article.field_image.alt}
/>

CDN and Caching

Use Drupal’s Fastly or Cloudflare CDN.
Enable Varnish or reverse proxy caching for JSON:API endpoints.
Use SWR or react-query for client-side caching and revalidation.

SEO with Headless Drupal + Next.js

Benefits of Headless SEO

Next.js enables full control over meta tags, schema, and Open Graph.
Improved Core Web Vitals via SSG and optimized JS delivery.

Implementing SEO

In your pages/_app.js or Head tag:

js code:

Additionally:

Generate sitemaps via next-sitemap
Implement robots.txt
Use structured data/schema.org where applicable

Future of Headless Drupal in 2025

GraphQL Support: Drupal’s GraphQL module is improving, providing more flexibility than REST/JSON:API.
Decoupled Menu & Routing: The Decoupled Menus Initiative has simplified menu exports via JSON:API.
Preview Mode: Next.js preview APIs now integrate better with Drupal for real-time content previews.
AI Integration: Expect tighter integrations between AI-powered personalization systems and headless CMS setups.

Final Thoughts: Should You Build with Headless Drupal + Next.js?

In 2025, building API-first applications is no longer cutting edge—it’s best practice. If you’re:

Looking for modern performance gains
Needing advanced content workflows
Seeking frontend flexibility with React

…then Headless Drupal with Next.js is a powerful, scalable, and future-proof solution.

When configured correctly, this combination gives you the best of both worlds: Drupal’s mature backend and Next.js’s powerful frontend rendering capabilities.

Related Hashtags:

#HeadlessDrupal #NextJS #APIFirst #DecoupledCMS #Drupal10 #DrupalNextJS #ModernWebDev #FullStackDevelopment #ReactJS #WebPerformance #SSG #ISR #JSONAPI