Next.js for Drupal

How to decouple Drupal with Next.js and JSON:API

A step by step guide to build a Next.js site with Drupal content and preview mode.

Here is the list of tasks we will accomplish in this guide:

  1. Install and configure the Next.js module for Drupal
  2. Configure preview mode
  3. Create a Next.js site using create-next-app
  4. Connect the Next.js site to Drupal for content


1. Install Drupal

Start by creating a new Drupal site using composer:

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

Once this is done, you can open the site and proceed with installation.

2. Add Next.js module

Run the following command to install the Next.js module and dependencies.

composer require drupal/next:1.0.x-dev

Note: we are pulling the latest dev version since there are no stable releases at this moment.

Apply patch

Under the hood, the Next.js module uses Subrequests to resolve resources in getStaticProps.

At the time of writing, there is a bug in the module that causes validation to fail. We need to patch the module to fix this.

  1. Open composer.json file and add the following lines (see highlighted) under "extra".
"extra": {
"patches": {
"drupal/subrequests": {
"Subrequest failed validation": ""
  1. Run the following to apply the patch.
composer require cweagans/composer-patches

This will install cweagans/composer-patches which will apply the patch.

3. Enable Next.js

Visit /admin/modules and enable the Next.js and Next.js JSON API modules.

4. Create Site

Once the modules are enabled, we can now create our first Next.js site.

  1. Visit /admin/config/services/next
  2. Click Add Next.js site
  3. Fill in the following values:
  • Label: Blog
  • Base URL: http://localhost:300
  • Preview URL: http://localhost:3000/api/preview
  • Preview Secret: preview-secret-here
  1. Click Save

You have created your first Next.js site.

5. Configure Path Aliases

The next-drupal plugin uses paths to resolve resources for getStaticProps. To make this work, we need to configure path aliases for our content types.

Let's add a pattern for the Article content type.

  1. Visit /admin/config/search/path/patterns/add.
  2. Fill in the following values:
  • Pattern type: Content
  • Path pattern: blog/[node:title]
  • Content type: Article
  • Label: Article
  1. Click Save

6. Preview Mode

The Next.js module, paired with the next-drupal plugin, makes it easy to create Next.js preview routes.

To configure preview mode for an entity type, you must configure:

  1. An OAuth Consumer.
  2. A site resolver for the entity type

6.1 OAuth Consumer

Create Role
  1. Create a new Drupal role (example Next blog) by visiting /admin/people/roles/add
  2. Give the role the following permissions:
  • Bypass content access control
  • Issue subrequests
  • View user information

We are assigning the Bypass content access control permission to allow Next.js to access unpublished entites and their revisions.

You can safely skip this permission if you do not need to preview unpublished content.

Create User

Add a new user at /admin/people/create and assign it the role we created above.

Create Consumer
  1. Visit /admin/config/people/simple_oauth
  2. Click Generate keys to generate encryption keys for tokens
  3. Visit /admin/config/services/consumer/add
  4. Fill in a Label, User (select the user created above), Secret and under Scopes, select the role created above.
  5. Click Save

Important: note the client id (uuid) and the secret. This is going to be used as environment variables for the Next.js site.

6.2 Site Resolver

A site resolver tells Drupal how to resolve the preview URL for an entity.

For our site, we are going to configure a resolver for the Article content type.

  1. Visit /admin/config/services/next/entity-types
  2. Click Configure entity type
  3. Select Article from the the entity type list
  4. Select Site selector as the Site resolver
  5. Select Blog under Next.js sites
  6. Click Save


Now that we have completed the Drupal configuration, we can create our Next.js site.

We are going to use the basic starter.

1. Create Site

Run the following command to create a new Next.js site:

npx create-next-app -e

2. Connect Drupal

To connect the Next.js site to Drupal, we use environment variables.

  1. Copy .env.example to .env.local.
  2. On the Drupal site, visit admin/config/services/next.
  3. Click Environment variables.
  4. Copy and paste the values into the .env.local file created above.

Remember to fill in the DRUPAL_CLIENT_ID and the DRUPAL_CLIENT_SECRET.

3. Run Site

To start the Next.js site, run npm run dev or yarn dev. This starts the development server on http://localhost:3000.

Visit http://localhost:3000 to view the site.

Create Content

You can now add a new article on your Drupal site and refresh your Next.js site to see the published article.

If preview mode has been configured correctly, you should also see an iframe preview when you visit the article in the Drupal admin.

👉 Hint: Since we're not using the Drupal front end theme, set Claro or Seven as the default theme for a cleaner preview UI.

Need help?

We understand there's more than a few steps to properly configure preview mode.

It is built this way for flexibility. With the current setup, you can easily configure one Drupal backend and serve multiple Next.js sites (content hub).

You maintain control on which content is pushed to which sites and how.

If you need help, feel free to create an issue on GitHub.

You can also reach out on Twitter.

IntroductionList of nodes

© 2021 Next.js for Drupal - Development sponsored by Chapter Three.