Community

GitHubDrupalSlack

Getting Started

IntroductionExamplesQuick Start

Data Fetching

Basic ExampleDynamic PagesAdvanced ExampleMenusBlocksFilter by Site

Authentication

IntroductionPassword GrantAuthorization Code GrantRefresh Token Rotation

Guides

Query ParamsTypeScriptInline ImagesLinksRoute SyncingWebform

Reference

getPathsFromContextgetResourceTypeFromContextgetResourcegetResourceFromContextgetResourceByPathgetResourceCollectiongetResourceCollectionFromContextgetMenu

Hooks

useMenu

Drupal

SitePreviewerSiteResolver
/
GitHub

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.

👉

We created a step by step video guide to help you get started with Next.js for Drupal. Check it out.

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

Drupal

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.

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:3000`
  • 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

Next.js

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 https://github.com/chapter-three/next-drupal-basic-starter

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.

ExamplesBasic Example