Seamless Headless Drupal integration with Next.js 15 (App Router)

Drupal is a mature and flexible content management system (CMS) trusted for building structured content models and managing complex workflows.

On the front end, Next.js is a widely adopted React framework known for its speed, developer experience, and production-grade features. With the release of Next.js 15, the new App Router brings powerful updates, including built-in support for async/streaming, granular caching, and improved routing patterns.

When connecting a decoupled Drupal backend to a Next.js 15 frontend, handling authentication becomes a key step, especially for gated content, personalisation, or editorial workflows.

This blog covers how to implement authentication in a headless Drupal + Next.js 15 setup using the latest App Router features and best practices around API routes, sessions, and token handling.

Why integrate Drupal with Next.js?
‍

Decoupled Architecture: Separates the back-end (Drupal) and front-end (Next.js) for increased flexibility.

Improved Performance: Next.js 15 introduces automatic caching and async rendering for faster load times.

Better User Experience: Provides a modern React-powered front-end for improved interactivity.

Scalability: Using Drupal as a headless CMS makes it easier to scale and manage content across platforms.

Setting up Next.js 15 with App Router

Create a Next.js application

Before starting, ensure you have Node.js installed. Then, run the following command to create a new Next.js 15 project:
‍

npx create-next-app@latest my-nextjs-app --ts --experimental-app
cd my-nextjs-app
npm install

‍

To start the development server:
‍

npm run dev

‍

Your Next.js app should now be running at http://localhost:3000.

Basic Project Structure
‍

my-nextjs-app/
├── app/                 # App Router directory
│   ├── layout.tsx       # Root layout (applies to all pages)
│   ├── page.tsx         # Home page (/)
│   ├── about/           # Example route: /about
│   │   └── page.tsx
│   └── api/             # API routes
│       └── user/route.ts
│
├── components/          # Reusable components (e.g., Header, Button)
│   └── Header.tsx
│
├── styles/              # Global and module CSS files
│   ├── globals.css
│   └── Home.module.css
│
├── public/              # Static assets (images, favicon, etc.)
│   └── favicon.ico
│
├── next.config.js       # Next.js configuration
├── tsconfig.json        # TypeScript configuration (if using TS)
└── package.json         # Project metadata and dependencies

Setting Up Drupal as a Headless CMS

Install Drupal new setup

Install and configure Drupal JSON: API

To enable API-based communication between Next.js and Drupal, install the JSON: API module:
‍

ddev composer require drupal/jsonapi
ddev drush en jsonapi -y

Enable CORS for API requests

To allow Next.js to access Drupal’s API, update services.yml:
‍

cors.config:
  enabled: true
  allowedOrigins: ['*']
  allowedHeaders: ['Content-Type', 'Authorisation']
  allowedMethods: ['GET', 'POST', 'OPTIONS', 'PATCH', 'DELETE']

Clear the cache:
ddev drush cr

Fetching Drupal data in Next.js 15 (Using Async and Cache)

Next.js 15 introduces improved async handling and caching. To fetch content from Drupal, install the required packages:
‍

npm install next-drupal drupal-jsonapi-params

‍

Set the variables
‍

# Required
NEXT_PUBLIC_DRUPAL_BASE_URL=https://my-site.ddev.site/
NEXT_IMAGE_DOMAIN=my-site.ddev.site


NEXT_PUBLIC_BASE_URL=http://localhost:3000

‍

Update the image dome in next.config.ts file
‍

Import type { NextConfig } from “next”;
const nextConfig: NextConfig = {
 images: {
   domains: ["my-site.ddev.site"], // Allow images from this domain
   remotePatterns: [
     {
       protocol: "https",
       hostname: "my-site.ddev.site",
       pathname: "/sites/default/files/**",
     },
   ],
 },
};


export default nextConfig;

Then, create a client to fetch data using the new fetch API with caching:
‍

import { NextDrupal } from "next-drupal"
import { DrupalJsonApiParams } from "drupal-jsonapi-params";


const drupal = new NextDrupal(process.env.NEXT_PUBLIC_DRUPAL_BASE_URL);


process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; // To fix the development fetch error


export async function fetchArticles() {
 const params = new DrupalJsonApiParams()
   .addFields("node--article", ["title", "id", "body", "field_image", "field_tags"])
   .addInclude(["field_image", "field_tags"])
   .addSort("created", "DESC");


 const response = await drupal.getResourceCollection("node--article", {
   params: params.getQueryObject(),
   cache: "force-cache" // Ensures fast loading
 });
 return response;
}

‍

Rendering the fetched content in Next.js 15:
‍

import { fetchArticles } from "../lib/drupal";
import Image from "next/image";


export default async function Page() {
 const data = await fetchArticles();
 console.log(data);
  return (
   <div className="">
     {data.map((article) => (
       <div key={article.id || article.title}> {/* ✅ Add key to top-level item */}
         <h2 className="article-title">{article.title}</h2>
        
         {article.field_image?.uri?.url && (
           <Image
             src={`${process.env.NEXT_PUBLIC_DRUPAL_BASE_URL}${article.field_image.uri.url}`}
             alt={article.title}
             width={400}
             height={250}
             className="image"
           />
         )}
        
         {article.body?.value ? <p>{article.body.value}</p> : <p></p>}
        
         {article.field_tags?.length > 0 && (
           <ul>
             {article.field_tags.map((tag, index) => (
               <li key={tag.id || `${tag.name}-${index}`}>{tag.name}</li>
             ))}
           </ul>
         )}
       </div>
     ))}
   </div>
 );
}

Conclusion

By integrating Drupal’s headless capabilities with Next.js 15 and its modern App Router, teams gain a powerful architecture that combines content flexibility with frontend performance.

Drupal continues to provide a structured, API-first backend for complex content models and editorial workflows, while Next.js 15 brings faster rendering through granular caching, improved async handling, and enhanced developer ergonomics.

This setup creates a future-ready foundation for scaling digital experiences. You can introduce personalisation, real-time updates, static generation for anonymous content, and even edge rendering with Next.js middleware, which also aligns well with the growing demand for composable architectures, enabling easy integration with third-party services like analytics, commerce, or AI-based recommendations.

As headless adoption grows, pairing Drupal with Next.js 15 offers a stable yet forward-looking path, supporting editorial flexibility, high performance, and extensibility for evolving digital products.

‍