Headless Drupal 11 + Next.js 14: Complete Setup From Scratch

For years, Drupal was viewed primarily as a website platform.

Today, many organizations are using Drupal differently.

Instead of rendering HTML directly, Drupal increasingly serves as:

• A content platform
• An API platform
• A publishing platform
• A content governance platform

Presentation is handled elsewhere.

Modern frontend frameworks such as Next.js have become popular because they provide:

• Excellent developer experience
• Strong performance
• Flexible rendering strategies
• Modern component architectures

The combination of Drupal and Next.js has become one of the most common headless architectures I encounter.

This article walks through how I would approach a modern Drupal 11 + Next.js 14 implementation from an architectural perspective.

Before You Start

The first question should not be:

How do I build a headless Drupal platform?

The first question should be:

Should I build a headless Drupal platform?

Headless architecture introduces:

• Additional complexity
• Additional deployments
• Additional infrastructure
• Additional development effort

The approach makes sense when you have:

• Mobile applications
• Multiple frontend consumers
• Product-driven experiences
• Long-term API requirements

If you’re building a simple marketing website, traditional Drupal may still be the better choice.

Architecture Overview

A typical implementation looks like this:

• Drupal 11 ↓JSON:API ↓Next.js 14 ↓Users

Drupal manages:

• Content
• Users
• Workflows
• Media
• Permissions

Next.js manages:

• Rendering
• User interface
• Routing
• Interactive experiences

This separation creates flexibility.

It also requires discipline.

Step 1: Install Drupal 11

Start with a clean Drupal installation.

Example:

• composer create-project drupal/recommended-project my-site

Install Drupal normally.

Then configure:

• Media
• JSON:API
• Pathauto
• Metatag
• Simple OAuth (if needed)

At this stage, avoid adding unnecessary modules.

Start small.

Complexity can always be added later.

Step 2: Design Your Content Model First

This is where many projects fail.

Developers often rush directly into frontend development.

That’s backwards.

The content model should come first.

Questions include:

What content exists?

Examples:

• Articles
• Events
• Videos
• Authors
• Categories

How do they relate?

Examples:

• Article

→ Author

→ Category

→ Media

The quality of your API depends heavily on the quality of your content architecture.

Poor content models create poor APIs.

Step 3: Enable JSON:API

Drupal 11 includes JSON:API in core.

Enable it:

• drush en jsonapi

Immediately verify:

• /jsonapi

You should see available resources.

Example:

• /jsonapi/node/article

At this stage:

Do not optimize yet.

Simply confirm data is available.

Step 4: Configure Media Correctly

Media becomes extremely important in headless systems.

Common media types include:

• Images
• Videos
• Documents

Make sure:

• Media entities are used
• Image styles are configured
• Relationships are clean

Many headless projects struggle because media architecture was never planned properly.

Step 5: Create Your Next.js Application

Create a new project:

• npx create-next-app@latest

Recommended options:

• TypeScript
• App Router
• ESLint

A typical structure:

• app/components/lib/services/types/

The goal is separation.

Keep API logic isolated from UI components.

Step 6: Create an API Layer

One of the biggest mistakes I see is placing API requests directly inside components.

Instead:

• services/ drupalApi.ts

Example responsibilities:

• Fetch articles
• Fetch events
• Fetch authors

Centralized API logic creates:

• Reusability
• Maintainability
• Testability

Architecturally, this becomes important as projects grow.

Step 7: Use Sparse Fieldsets

Most teams over-fetch data.

Bad example:

• /jsonapi/node/article

Better:

• /jsonapi/node/article?fields[node--article]=title,path,field_image

Benefits:

• Smaller payloads
• Faster responses
• Better frontend performance

This should become standard practice.

Step 8: Handle Dynamic Routes

Example:

• /articles/my-article

In Next.js:

• app/articles/[slug]/page.tsx

The route becomes responsible for:

• Resolving content
• Fetching article data
• Rendering content

Keep routing predictable.

Complex routing usually indicates architectural issues elsewhere.

Step 9: Decide on Rendering Strategy

Next.js provides multiple options.

Static Generation

Best for:

• Content-heavy sites
• Marketing sites
• Publications

Benefits:

• Performance
• SEO
• Reliability

Server Rendering

Best for:

• Dynamic applications
• Personalized experiences

Benefits:

• Fresh data
• Runtime flexibility

Hybrid Approaches

Most real-world projects use a combination.

Architectural decisions should be driven by content requirements.

Not framework trends.

Step 10: Authentication

Many projects eventually require authentication.

Options include:

Anonymous Content

Simplest.

Session Authentication

Traditional approaches.

OAuth

Common in headless architectures.

When using Drupal:

Simple OAuth is often the preferred approach.

Especially for:

• Mobile applications
• SPAs
• API-driven systems

Authentication deserves intentional planning.

Do not treat it as a later feature.

Step 11: Performance Optimization

This is where many teams start.

It should actually come later.

First:

Build correctly.

Then optimize.

Review:

Payload Size

Includes

Cache Strategy

Image Optimization

CDN Usage

Frontend Caching

Most performance issues are architectural rather than infrastructural.

Step 12: Deployment Strategy

At minimum:

• Drupal deployment:

Git→ CI/CD→ Hosting

Next.js deployment:

• Git→ Build→ Deployment

Treat these as separate concerns.

Because they are.

One of the biggest mistakes organizations make is pretending headless architecture still behaves like a single application.

It doesn’t.

Common Mistakes

Mistake #1

Starting With Frontend Components

Start with content architecture.

Always.

Mistake #2

Ignoring Relationships

Relationships are where much of the value lives.

Mistake #3

Over-Fetching Data

Use sparse fieldsets.

Mistake #4

Treating Authentication As An Afterthought

Plan early.

Mistake #5

Choosing Headless Because It’s Trendy

Architecture should solve problems.

Not follow trends.

Production Readiness Checklist

Drupal

• Content model complete
• Media configured
• JSON:API configured
• Permissions reviewed

Next.js

• API layer created
• Routes implemented
• Rendering strategy selected

Performance

• Sparse fieldsets implemented
• CDN configured
• Images optimized

Security

• Authentication reviewed
• OAuth reviewed
• Secrets managed

Operations

• Deployment process documented
• Monitoring configured
• Backup strategy reviewed

Final Thoughts

Drupal 11 and Next.js 14 are an excellent combination when the requirements justify headless architecture.

Drupal provides:

• Structured content
• Governance
• Workflows
• Editorial capabilities

Next.js provides:

• Modern frontend experiences
• Performance
• Flexibility

Together they create a powerful platform.

But remember:

The success of a headless architecture depends less on the technology and more on the decisions surrounding it.

Content architecture.

Governance.

Relationships.

APIs.

Workflows.

Those are the areas that determine long-term success.

The frameworks simply make the architecture visible.

Need Help Designing a Headless Drupal Platform?

DrupalRX helps organizations evaluate headless architectures, content models, API strategies, authentication systems, and modernization initiatives.

If you’re planning a Drupal 11 + Next.js implementation, start with architecture before writing code.