
<Callout>

If you're using the [`DrupalClient`](/docs/client), see the new guide [here](/learn/quick-start-client).

</Callout>

This tutorial will guide you through how to get started with Next.js for Drupal.

You will learn how to setup Drupal, configure preview mode and connect a Next.js site to display your content.

**This tutorial assumes basic knowledge of Drupal and Next.js.**

Let's get started!


Introduction


## Install Drupal

Start by creating a new Drupal site using composer.

If you have an existing Drupal site, you can skip to the next part.

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

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

## Add Next.js module

Run the following command to install the [Next.js](https://drupal.org/project/next) module and dependencies.

```sh
composer require drupal/next
```


Install Drupal


At the time of this writing, there are two patches we need to wire everything together.

1. Open your Drupal `composer.json` file.
2. Add the following patches under `"extra"`.

```json title=composer.json
"extra": {
		// highlight-start
    "patches": {
        "drupal/subrequests": {
            "Get same results on different request": "https://www.drupal.org/files/issues/2019-07-18/change_request_type-63049395-09.patch"
        },
        "drupal/decoupled_router": {
            "Unable to resolve path on node in other language than default": "https://www.drupal.org/files/issues/2021-05-05/3111456-34.patch"
        }
    },
		// highlight-end
}
```

3. Run the following command:

```sh
composer require cweagans/composer-patches
```

You can read more about the patches here:

1. https://www.drupal.org/project/subrequests/issues/3049395
2. https://www.drupal.org/project/decoupled_router/issues/3111456


Apply Patches


## Enable Modules

1. Visit _/admin/modules_.
2. Enable the **Next.js** and **Next.js JSON:API** modules.


Enable Modules


The Next.js module, paired with the `next-drupal` plugin, makes it easy to create [Next.js preview routes](https://nextjs.org/docs/advanced-features/preview-mode).

We use an OAuth consumer to access preview routes.

Before we can create an OAuth consumer, we need to create a new role and a user for OAuth scopes.

## Create Role

1. Visit _/admin/people/roles_.
2. Click on **+ Add role**.
3. Fill in the **Role name**. Example: _Next.js Site_.

## Assign Permissions

Next, assign the following permissions to the newly created role.

- Bypass content access control
- Issue subrequests
- View user information

<Callout>

We are assigning the _Bypass content access control_ permission to allow Next.js to access unpublished content and revisions.

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

</Callout>

## Create User

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


Create Role and User


## Generate keys

Generate a pair of keys to encrypt the tokens. And store them outside of your document root (`web` directory) for security.

1. Visit _/admin/config/people/simple_oauth_
2. Click **Generate keys** to generate encryption keys for tokens
3. Fill in **Directory for the keys**.
4. Click **Generate**.

You can also use `openssl` to generate keys:

```
openssl genrsa -out private.key 2048
openssl rsa -in private.key -pubout > public.key
```

## Create Consumer

1. Visit _/admin/config/services/consumer/add_
2. Fill in the following values:

- **Label**: `Next.js site`
- **User**: `Select the user we created`
- **Secret**: `Your secret`
- **Scopes**: `Select the role we created`

3. Click **Save**

_Important: note the client id (uuid) and the secret. These are going to be used as environment variables for the Next.js site._


Create Consumer


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`

4. Click **Save**

<Img
  src="/images/next-drupal-add-site.jpg"
  width="600"
  height="390"
  layout="responsive"
  mb="10"
/>

You have created your first Next.js site.


Create Next.js Site


To display content on the Next.js site, we need to configure path aliases and preview mode for the content types.

## 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`

3. Click **Save**

<Img
  src="/images/next-drupal-pathauto.jpg"
  width="600"
  height="390"
  layout="responsive"
  mb="10"
/>

## Configure Preview

To enable content preview inside Drupal, we need to configure a site resolver for the **Article** content type.

<Callout>

A _site resolver_ tells Drupal how to resolve the preview URL for an entity.

</Callout>

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**

<Img
  src="/images/next-drupal-entity-type.jpg"
  width="600"
  height="390"
  layout="responsive"
  mb="10"
/>

Done. You have completed the Drupal configuration.


Configure Content Types


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

We are going to use the [basic starter](https://github.com/chapter-three/next-drupal/tree/master/starters/basic-starter).

## Create Project

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

### Using Basic Starter

```sh
npx create-next-app -e https://github.com/chapter-three/next-drupal-basic-starter
```

### Using Basic Starter with DrupalClient

If you would like to use the new [`DrupalClient`](/docs/client), use the following command instead:

```sh
npx create-next-app -e https://github.com/chapter-three/next-drupal-basic-starter-client
```

## Connect Drupal

To connect the Next.js project to Drupal, we use [environment variables](https://nextjs.org/docs/basic-features/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`._

## Start Development Server

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

Visit [http://localhost:3000](http://localhost:3000) to view the site.


Create Next.js project


You can now ready to create content.

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.

<Callout>

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

</Callout>


Create Content


Congratulations. You have successfully install, configure and connect a Next.js site to Drupal. 🎉

## What's Next?

Take a look at the [documentation](/docs) to learn more about:

1. [Data Fetching](/docs/data-fetching)
2. [Menus](/docs/data-fetching/menus)
3. [Authentication](/docs/authentication)
4. [Webforms](/docs/guides/webform)

## Need help?

We understand there's more than a few steps to properly configure Next.js for Drupal.

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](https://github.com/chapter-three/next-drupal).

You can also reach out on [Twitter](https://twitter.com/shadcn).


Done

Quick Start

Configure Path Aliases

Configure Preview


This tutorial will guide you through how to get started with Next.js for Drupal using the [`DrupalClient`](/docs/client).

You will learn how to setup Drupal and connect a Next.js site to display your content.

<Callout icon="⚠️">

The `DrupalClient` is available in `next-drupal ^1.3.0` as **experimental**.

</Callout>

Let's get started!



Start by creating a new site and adding the [Next.js](https://drupal.org/project/next) module.

## Install Drupal

If you have an existing Drupal site, you can skip to the next part.

Start by creating a new Drupal site using composer.

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

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

## Add Next.js module

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

```sh
composer require drupal/next
```



1. Visit `/admin/modules`.
2. Enable the following modules: **Next.js** and **Next.js JSON:API**.



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`

3. Click **Save**

<Img
  src="/images/next-drupal-pathauto.jpg"
  width="600"
  height="390"
  layout="responsive"
  mb="10"
/>

Done. You have completed the Drupal configuration.



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

We are going to use the [basic starter](https://github.com/chapter-three/next-drupal/tree/master/starters/basic-starter-client).

## Create Project

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

```sh
npx create-next-app -e https://github.com/chapter-three/next-drupal-basic-starter-client
```

## Connect Drupal

To connect the Next.js project to Drupal, we use [environment variables](https://nextjs.org/docs/basic-features/environment-variables).

1. Copy `.env.example` to `.env.local`.
2. Fill in the following **Environment variables**:

```txt title=.env.local
NEXT_PUBLIC_DRUPAL_BASE_URL=http://example.com
NEXT_IMAGE_DOMAIN=example
```

## Start Development Server

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

Visit [http://localhost:3000](http://localhost:3000) to view the site.



You can now ready to create content.

Add a new article on your Drupal site and refresh your Next.js site to see the published article.



Congratulations. You have successfully install, configure and connect a Next.js site to Drupal. 🎉

## What's Next?

Take a look at the [documentation](/docs) to learn more about decoupling Drupal with Next.js.

## Need help?

We understand there's more than a few steps to properly configure Next.js for Drupal.

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](https://github.com/chapter-three/next-drupal).

You can also reach out on [Twitter](https://twitter.com/shadcn).


Quick Start (DrupalClient)


The Next.js module, paired with the `next-drupal` plugin, makes it easy to create [Next.js preview routes](https://nextjs.org/docs/advanced-features/preview-mode).

To handle preview routes, we need to configure authentication.

The `DrupalClient` works with several authentication methods. We are going to look into two methods:

1. **Basic** tokens using the _basic_auth_ module.
2. **Bearer** tokens using the [_simple_oauth_](https://drupal.org/project/simple_oauth) module.

_Only one of the authentication methods is required for Preview Mode._


Preview Mode


The Basic authentication is relatively easy to set up. It requires less configuration and uses username and password as credentials.

## 1. Create Role

1. Visit `/admin/people/roles`.
2. Click on **+ Add role**.
3. Fill in the **Role name**. Example: _Next.js Site_.

## 2. Assign Permissions

Next, assign the following permissions to the newly created role.

- Bypass content access control
- Issue subrequests
- View user information

<Callout>

We are assigning the _Bypass content access control_ permission to allow Next.js to access unpublished content and revisions.

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

</Callout>

## 3. Create User

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

## 4. Enable module

Visit `/admin/modules` and enable the **Basic Auth** module.

## 5. Connect Drupal

To connect the Next.js project to Drupal, we use [environment variables](https://nextjs.org/docs/basic-features/environment-variables).

Fill in the following variables in your `.env.local` file.

```txt title=.env.local
BASIC_AUTH_USERNAME=
BASIC_AUTH_PASSWORD=
```

This is the username and password of the user we created above.

## 6. Update DrupalClient

Update the `DrupalClient` to use the **Basic** authentication header.

```ts title=lib/drupal.ts
import { Experiment_DrupalClient as DrupalClient } from "next-drupal"

export const drupal = new DrupalClient(
  process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
  {
    auth: () =>
      "Basic " +
      Buffer.from(
        `${process.env.BASIC_AUTH_USERNAME}:${process.env.BASIC_AUTH_PASSWORD}`
      ).toString("base64"),
  }
)
```


Authentication (Basic)


Before we can create an OAuth consumer, we need to create a new role and a user for OAuth scopes.

## 1. Create Role

1. Visit `/admin/people/roles`.
2. Click on **+ Add role**.
3. Fill in the **Role name**. Example: _Next.js Site_.

## 2. Assign Permissions

Next, assign the following permissions to the newly created role.

- Bypass content access control
- Issue subrequests
- View user information

<Callout>

We are assigning the _Bypass content access control_ permission to allow Next.js to access unpublished content and revisions.

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

</Callout>

## 3. Create User

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

## 4. Generate keys

Generate a pair of keys to encrypt the tokens. Store them outside of your document root (`web` directory) for security.

1. Visit `/admin/config/people/simple_oauth`
2. Click **Generate keys** to generate encryption keys for tokens
3. Fill in **Directory for the keys**.
4. Click **Generate**.

You can also use `openssl` to generate keys:

```
openssl genrsa -out private.key 2048
openssl rsa -in private.key -pubout > public.key
```

## 5. Create Consumer

1. Visit _/admin/config/services/consumer/add_
2. Fill in the following values:

- **Label**: `Next.js site`
- **User**: `Select the user we created`
- **Secret**: `Your secret`
- **Scopes**: `Select the role we created`

3. Click **Save**

_Important: note the client id (uuid) and the secret. These are going to be used as environment variables for the Next.js site._

## 6. Connect Drupal

To connect the Next.js project to Drupal, we use [environment variables](https://nextjs.org/docs/basic-features/environment-variables).

Fill in the following variables in your `.env.local` file.

```txt title=.env.local
DRUPAL_CLIENT_ID=
DRUPAL_CLIENT_SECRET=
```

## 6. Update DrupalClient

Update the `DrupalClient` to use the **Bearer** authentication header.

```ts title=lib/drupal.ts
import { Experiment_DrupalClient as DrupalClient } from "next-drupal"

export const drupal = new Experiment_DrupalClient(
  process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
  {
    auth: {
      clientId: process.env.DRUPAL_CLIENT_ID,
      clientSecret: process.env.DRUPAL_CLIENT_SECRET,
    },
  }
)
```


Authentication (Bearer)


<Callout>

If you're using the Basic Starter, preview routes are already configure for you.

</Callout>

To implement preview mode:

1. Set a `previewSecret` on the `DrupalClient`. This is the same secret used when creating your site on Drupal.
2. Implement preview mode using two API routes.

```ts title=pages/api/preview.ts
import { NextApiRequest, NextApiResponse } from "next"

import { drupal } from "lib/drupal"

export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse
) {
  return await drupal.preview(request, response)
}
```

```ts title=pages/api/exit-preview.ts
import { NextApiResponse } from "next"

export default function exit(_, response: NextApiResponse) {
  response.clearPreviewData()
  response.writeHead(307, { Location: "/" })
  response.end()
}
```


Configure Preview Routes


To display content on the Next.js site, we need to configure preview mode for the content types.

## Configure Preview

To enable content preview inside Drupal, we need to configure a site resolver for the **Article** content type.

<Callout>

A _site resolver_ tells Drupal how to resolve the preview URL for an entity.

</Callout>

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 **your site** under **Next.js sites**
6. Click **Save**

<Img
  src="/images/next-drupal-entity-type.jpg"
  width="600"
  height="390"
  layout="responsive"
  mb="10"
/>



Congratulations. You have successfully configured preview mode for your content types.

You should see the iframe preview when you visit your content pages.

If you need help, feel free to create an issue on [GitHub](https://github.com/chapter-three/next-drupal).

You can also reach out on [Twitter](https://twitter.com/shadcn).


Getting Started

Drupal Client Experimental

Data Fetching

Authentication

Reference

Hooks

Drupal

Configure Content Types

Configure Path Aliases

Configure Preview