Drupal Decoupled Local Setup with DDEV, Composer, and Next.js

The one-click Tugboat demo is the fastest way to see what Drupal Decoupled can do. But building real projects requires a local development environment where you control configuration, debugging, and workflow, and where you can see exactly how the Drupal backend connects to the frontend.

In a recent webinar walkthrough, we demonstrated the complete local setup process, from initial Composer template to a fully integrated environment where content changes in Drupal appear instantly in the Next.js frontend.

Here's how to get it running on your machine.

Setting Up the Drupal Backend with DDEV

The local setup starts with creating a Drupal project using our Composer template, which includes Drupal 11 core, the Drupal Decoupled recipe, and automated configuration scripts.

Step 1: Create the DDEV Project

Step 2: Run the Automated Setup

This single command handles multiple configuration steps that would otherwise require manual setup. 

As Omar, our CTO and Co-Founder, explains in the webinar: "We have a pretty handy script just to make the full installation and preconfigure all the Drupal configurations we are making, installing the recipe itself and we have to run a couple of scripts to set up the authentication, the keys, the secrets to allow the frontend to communicate with the Drupal instance."

The automated setup performs these essential tasks:

• Installs Drupal core and all dependencies via Composer.
• Applies the Drupal Decoupled recipe with all necessary modules.
• Configures GraphQL Compose for API exposure.
• Sets up Simple OAuth for frontend authentication.
• Generates client keys and secrets for secure communication.
• Creates sample content for immediate testing.

Step 3: Access Your Drupal Installation

After setup completes, access your local Drupal site through the URL in the terminal output. Everything needed for decoupled operation is already configured.

The Composer template means you're starting with a tested foundation rather than assembling individual components, which eliminates the configuration mistakes that derail most early decoupled projects.

Why We Waited for Drupal 11

We deliberately waited before adding Drupal 11 support. Instead of jumping in when it was released, we held off until the contributed modules powering the decoupled architecture had proven stability: GraphQL Compose, Simple OAuth, Decoupled Preview Iframe. Now that they're mature, we made the move.

This gives you module ecosystem maturity across the entire recipe, a clear upgrade path from Drupal 10, and production reliability without the risk of experimental support or breaking changes from early adoption.

The same philosophy extends to the frontend starters. For broader context on this approach, see our guide to Drupal Decoupled.

Configuring the Next.js Frontend

With the Drupal backend running, the next step involves setting up the Next.js frontend that will consume content via GraphQL. 

The process requires copying authentication credentials and configuring environment variables for local development.

Step 1: Clone the Frontend Starter

Step 2: Configure Environment Variables

Copy the client ID and client secret from the terminal output after running ddev setup-drupal-decoupled into your .env.local:

The DDEV site naming follows your project name, so the base URL adapts to whatever you called your project during setup.

Step 3: Choose DDEV or Lando

The starter supports both. For DDEV, the default configuration works out of the box. For Lando, uncomment the Lando-specific environment variables and comment out the DDEV ones.

What Ships in the Current Stack

When we updated Drupal 11 support, we also brought the frontend starters to their most recent stable versions. As Omar explains: "We are using Next 16.1.6 which doesn't have all the older version problems from the React server component things like that."

Here's what you get out of the box:

• Next.js 16.1.6 with React Server Components: Full RSC support without the compatibility issues from earlier versions.
• Storybook 10: Design system patterns and isolated component development.
• shadcn/ui with Base UI Components: A modern design system foundation.
• Tailwind CSS 4: Latest utility classes and performance optimizations.

We choose mature implementations over cutting-edge features that might introduce instability. Every version in this stack has been tested together.

Verifying Your Setup

Run npm run dev to start the Next.js development server on http://localhost:3000. It immediately begins fetching content from your local Drupal instance via GraphQL.

You should see the same content structure and components from the cloud demo, now running entirely on your machine. The real test is making content changes in Drupal and confirming they appear in the frontend after a refresh.

As I showed in the webinar: "Once we finish this configuration here we can go back to our CLI and just run npm run dev. The Next app is here. It's already preconfigured consuming data from the local Drupal installation we have here."

This integration also enables the preview functionality and editorial workflow covered in our Tugboat demo walkthrough.

Troubleshooting Common Issues

• Authentication errors: Verify that the client ID and secret in .env.local match exactly what was generated during setup. These are case-sensitive.
• Port conflicts: DDEV and other local services sometimes conflict on standard ports. Use DDEV's commands to restart services and resolve conflicts.
• GraphQL schema updates: After changing content types or fields, clear the cache with ddev drush cr to regenerate the schema.
• Frontend build errors: Check Node.js version compatibility. The starter includes a .nvmrc file for version management.

Ready to go? Clone the starter, follow this walkthrough, and start developing. For teams that need guidance on architecture or implementation strategy, schedule a call with us to discuss how Drupal Decoupled fits your requirements.

Still weighing whether Drupal Decoupled is the right fit? Watch our misconceptions webinar where we break down what actually holds teams back from adopting decoupled Drupal.