DrupalRX Field Guide
Enterprise Drupal diagnosis, architecture, and implementation notes.
Tutorials

DDEV for Headless Drupal and Next.js in 2026

Sun, 03/08/2026 - 13:00 admin
DDEV Headless Next.js Local Development Headless Drupal

Ask a room full of Drupal developers about local development and you’ll probably hear war stories.

Years ago, getting a project running often meant spending hours—or days—configuring:

  • Apache
  • PHP
  • MySQL
  • Virtual hosts
  • SSL certificates
  • Environment variables

Every developer’s machine was slightly different.

Every onboarding experience was painful.

Every project seemed to have its own unique setup instructions.

Thankfully, those days are largely behind us.

Today, DDEV has become my default recommendation for Drupal development, particularly when working with modern headless architectures involving:

  • Drupal 11
  • Next.js
  • JSON:API
  • OAuth
  • Mobile applications

Not because DDEV is trendy.

Because it solves real operational problems.

The Goal Is Consistency

Many teams think local development is a technical challenge.

It’s actually an operational challenge.

The question isn’t:

Can I get Drupal running?

The question is:

Can every developer get Drupal running consistently?

That’s where DDEV shines.

Consistency reduces:

  • Onboarding time
  • Environment drift
  • Deployment surprises
  • Team frustration

Those benefits compound over time.

A Modern Headless Stack

A typical architecture looks like this:

  • text id="9ik8rw" Drupal 11 ↓ JSON:API ↓ Next.js 14 ↓ Users

Locally, that becomes:

  • ```text id=“m5x6lq” DDEV ├── Drupal ├── Database └── Supporting Services

Next.js └── Frontend Application

The goal is making the environment predictable.Not clever.---# Why DDEV Has Become The DefaultSeveral years ago, developers often debated:- Lando- Docker Compose- Vagrant- Custom environmentsMost of those conversations have become less important.Today, DDEV offers:### SimplicityDevelopers can become productive quickly.### ConsistencyEnvironments remain aligned.### FlexibilitySupports modern Drupal workflows.### Community SupportStrong Drupal ecosystem adoption.The result is less time configuring infrastructure and more time solving business problems.---# Installing DDEVInstallation instructions change over time, so I won't duplicate official documentation here.Instead, I'll focus on principles.A successful installation should provide:- Docker support- DDEV CLI- HTTPS support- Reliable local DNSOnce installed, verify:```bash id="9r4s9h"ddev version

before configuring projects.

Creating A Drupal Project

Inside your Drupal directory:

  • bash id="k6r7u1" ddev config

Common selections:

  • text id="s2s7bn" Project Type: drupal11 Docroot: web

Then:

  • bash id="j8c8la" ddev start

At this point, Drupal becomes accessible through a local HTTPS URL.

No Apache configuration.

No manual SSL setup.

No virtual hosts.

That’s a major improvement over older workflows.

Keep Drupal And Next.js Separate

One mistake I frequently see:

Developers attempting to force Drupal and Next.js into the same project structure.

Avoid this.

Instead:

  • text id="b9p2gn" projects/ ├── drupal-backend/ └── nextjs-frontend/

Treat them as separate applications.

Because they are.

This separation creates:

  • Cleaner deployments
  • Cleaner repositories
  • Cleaner ownership boundaries

The architecture becomes easier to reason about.

Configure Environment Variables Early

Headless projects rely heavily on configuration.

Examples:

  • Drupal:

text id="0qjlwm" DATABASE_URL HASH_SALT API_KEYS

Next.js:

  • text id="vdb10t" NEXT_PUBLIC_API_URL AUTH_URL OAUTH_CLIENT_ID

One of the easiest ways to create onboarding problems is inconsistent environment management.

Document variables early.

Future developers will appreciate it.

JSON:API Testing

As soon as Drupal is running, verify:

  • text id="kmh0ol" /jsonapi

and:

  • text id="0m1v7u" /jsonapi/node/article

before building frontend integrations.

Many teams begin building React components before confirming APIs are working correctly.

That’s backwards.

Validate the content platform first.

Then build consumers.

Working With Next.js

Once Drupal is running:

  • bash id="0j3z7w" npm run dev

starts the frontend.

A typical local architecture becomes:

  • ```text id=“rm5efx” Drupal https://project.ddev.site

Next.js http://localhost:3000

The frontend consumes Drupal APIs while remaining independently deployable.This mirrors production architecture more closely.---# Authentication ConsiderationsMost simple tutorials skip authentication.Real projects can't.Common approaches include:### Anonymous ContentSimplest.### Session-Based AuthenticationUseful in some scenarios.### OAuth + PKCERecommended for many headless applications.Particularly:- Mobile applications- SPAs- React Native- Next.js authenticated experiencesAuthentication architecture should be decided early.Retrofitting authentication later is expensive.---# Team OnboardingThis is where DDEV provides some of its greatest value.A healthy onboarding process looks something like:```bash id="hrbdur"git cloneddev startcomposer installdrush cimdrush cr

Developer productive.

Done.

Not:

Follow this 40-page setup guide and hope nothing breaks.

The simpler onboarding becomes, the faster teams move.

Environment Drift Is The Real Enemy

Many development teams underestimate environment drift.

Examples:

  • Developer A:

text id="66k3lm" PHP 8.4

Developer B:

  • text id="o8hxfm" PHP 8.3

Developer C:

  • text id="2my70w" PHP 8.2

Problems emerge.

Bugs become difficult to reproduce.

Confidence decreases.

Containerized environments dramatically reduce this risk.

Local Development Should Mirror Production

Perfect parity is rarely possible.

But the closer environments become, the fewer surprises appear.

Questions worth asking:

Same PHP version?

Same database version?

Similar caching behavior?

Similar environment variables?

The closer these answers are to “yes,” the healthier the deployment process becomes.

Common Mistakes

Mistake #1

Treating Local Development As An Individual Problem

It’s a team problem.

Mistake #2

Combining Drupal And Next.js Into One Application

Keep responsibilities separate.

Mistake #3

Ignoring Environment Variables

Configuration drift eventually causes issues.

Mistake #4

Building Frontends Before Validating APIs

Verify content delivery first.

Mistake #5

Optimizing Too Early

Get the workflow working.

Then improve it.

Headless Development Checklist

Drupal

  • DDEV configured
  • JSON:API enabled
  • Content model established

Next.js

  • Environment variables configured
  • API layer created
  • Routes implemented

Team

  • Setup documented
  • Onboarding validated
  • Environment consistency verified

Operations

  • Deployment strategy documented
  • Configuration management reviewed

Security

  • Secrets managed
  • Authentication planned

Final Thoughts

DDEV isn’t valuable because it runs Drupal.

Many tools can do that.

DDEV is valuable because it reduces friction.

It makes local development:

  • Predictable
  • Repeatable
  • Consistent

And in modern headless architectures, consistency matters.

Especially when projects involve:

  • Drupal
  • Next.js
  • APIs
  • Authentication
  • Multiple developers

The less time a team spends fighting environments, the more time it spends delivering value.

That’s ultimately the goal.

Need Help Designing a Headless Drupal Development Workflow?

DrupalRX helps organizations evaluate local development strategies, headless Drupal architectures, API workflows, team onboarding processes, and modernization initiatives.

If your team spends more time troubleshooting environments than building software, it may be time to simplify the workflow.

standard