
This tutorial will help you get started with Next.js for Drupal using the [`NextDrupal Client`](/docs/client) and **JSON:API**.

<Callout>

For **GraphQL**, see the [GraphQL quick start guide](/learn/graphql).

</Callout>

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

Let's get started!


Introduction


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

## Install Drupal

<Callout>

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

</Callout>

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, using the "Standard" profile.

If you want to install the Umami demo experience instead, please see the <a href="/guides/umami-demo">Umami Demo Guide</a>.

---

## Add Next.js module

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

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


Install Drupal


At the time of this writing, a patch is required in order to use multilingual features such as translation.

<Callout>

**Note:** If you're not using multilingual features such as translation, you can skip this step.

</Callout>

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

```json title=composer.json
"extra": {
		// highlight-start
    "patches": {
        "drupal/decoupled_router": {
            "Unable to resolve path on node in other language than default": "https://www.drupal.org/files/issues/2024-08-05/decouple_router-3111456-resolve-language-issue-63--get-translation-re-rolled-and-good-redirect.patch"
        }
    },
		// highlight-end
}
```

3. Run the following command:

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

You can read more about the patch here:

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


Apply Patches


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


Enable Modules


The `next-drupal` plugin uses paths to resolve resources for the Next.js Frontend. 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="420"
  layout="responsive"
  mb="10"
/>

Done. You have completed the Drupal configuration.


Configure Path Aliases


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:

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

---

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


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.


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 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).


Done

Quick Start


This tutorial will help you get started with Next.js for Drupal using the [`NextDrupal`](/docs/client) and **GraphQL**.

<Callout>

For **JSON:API**, see the [JSON:API quick start guide](/learn/quick-start).

</Callout>

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

Let's get started!



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

## Install Drupal

<Callout>

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

</Callout>

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, using the "Standard" profile.

---

## Add Next.js module

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

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

## Add GraphQL modules

Run the following command to install GraphQL and GraphQL Compose modules:

```sh
composer require 'drupal/graphql:^4.6' 'drupal/graphql_compose:^2.0'
```



1. Visit `/admin/modules`.
2. Enable the following modules: **Next.js**, **Next.js GraphQL**, **GraphQL Compose: Edges**, **GraphQL Compose: Routes**, **GraphQL Compose: Users**.

## Configure GraphQL Compose

1. Visit `/admin/config/graphql_compose`.
2. Under the Content tab, enable "GraphQL", "Single Query", "Edge Query", & "Loading by Route" for the Article content type.
3. Enable all of the fields for the Article content type.
4. Do the same for the Basic page content type.
5. Under the Users tab, do the same for the user entity.

## Try GraphQL

If you visit `/admin/config/graphql/servers/manage/graphql_compose_server/explorer` on your site, you should see an example server created for you.

You can start testing GraphQL queries. Let's make our first request to fetch the first 5 articles.

Copy and paste the following in the query text input and click the Execute Query (▶) button.

```graphql
query Articles {
  nodeArticles(first: 5) {
    nodes {
      title
    }
  }
}
```

You should see the first 5 articles returned on the right.



To make GraphQL requests to your Drupal site, we need to configure [authentication](/docs/authentication).

We will use an OAuth Client for authenticating GraphQL requests.

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.

- GraphQL Compose - Server: Execute arbitrary requests

---

## 3. Create User

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

---

## 4. Generate keys

Generate a pair of keys to encrypt the access 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**. For example a relative path like `../`
4. Click **Generate**
5. Click **Save configuration**

You can also use `openssl` to generate keys in the directory you used above:

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

---

## 5. Create Scope

1. Visit _/admin/config/people/simple_oauth/oauth2_scope/dynamic/add_
2. Fill in the following values:

- **Machine-readable Name**: `nextjs_site`
- **Description**: `Next.js Site`
- **Grant Types**: `Client Credentials`
- **Granularity**: `Role`
- **Role**: `Next.js Site`

3. Click **Save**

---

## 6. Create Consumer

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

- **Label**: `Next.js site`
- **Client ID**: `nextjs_site` (or generate a UUID if preferred)
- **Secret**: `Your secret`
- **Grant Types**: `Client Credentials`
- **Scopes**: `nextjs_site`
- **User**: `Select the user 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._


Configure Authentication


Let's configure path aliases 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="420"
  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 [GraphQL starter](https://github.com/chapter-three/next-drupal/tree/master/starters/graphql-starter).

---

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

---

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

# Authentication
DRUPAL_CLIENT_ID=
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.



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).


Quick Start (GraphQL)


The Next.js module, paired with the `next-drupal` plugin, makes it easy to create [Next.js draft routes](https://nextjs.org/docs/app/building-your-application/configuring/draft-mode).

To handle draft routes, we need to create a Next.js site on Drupal and configure authentication.


Draft Mode


Start by creating a Next.js site so that we can render the draft in Drupal.

1. Visit `/admin/config/services/next`.
2. Click **Add Next.js site**.
3. Fill in the following values:

- **Label**: `Next.js`
- **Base URL**: `http://localhost:3000`
- **Draft URL (or Preview URL)**: `http://localhost:3000/api/draft`
- **Secret key**: `secret`

<Callout>

As from `next-drupal 1.5`, encrypted secrets are automatically generated and validated by the Next module.

</Callout>

4. Click **Save**


Create Next.js site


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

<Callout>

As from `next-drupal 1.5`, user roles are used for OAuth scopes. The scopes are automatically handled for the preview based on the currently logged in user.

The OAuth related instructions below are based on the 6.x version of the Simple OAuth module.

</Callout>

---

## 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
- View all revisions

<Callout>

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

This scope is only going to be used when making authenticated requests from Next.js to Drupal.

```ts
const article = await drupal.getResource(
  "node--article",
  "dad82fe9-f2b7-463e-8c5f-02f73018d6cb",
  // highlight-start
  {
    withAuth: true,
  }
  // highlight-end
)
```

</Callout>

---

## 3. Create User

Add a new user at `/admin/people/create` and **assign them all the roles that are going to be used for scopes, including 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**. For example a relative path like `../`
4. Click **Generate**
5. Click **Save configuration**

You can also use `openssl` to generate keys in the directory you used above:

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

---

## 5. Create Scope

1. Visit _/admin/config/people/simple_oauth/oauth2_scope/dynamic/add_
2. Fill in the following values:

- **Machine-readable Name**: `nextjs_site`
- **Description**: `Next.js Site`
- **Grant Types**: `Client Credentials`
- **Granularity**: `Role`
- **Role**: `Next.js Site`

3. Click **Save**

---

## 6. Create Consumer

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

- **Label**: `Next.js site`
- **Client ID**: `nextjs_site` (or generate a UUID if preferred)
- **Secret**: `Your secret`
- **Grant Types**: `Client Credentials`
- **Scopes**: `nextjs_site`
- **User**: `Select the user 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._

---

## 7. 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
# Authentication (Bearer)
DRUPAL_CLIENT_ID=
DRUPAL_CLIENT_SECRET=
```

---

## 8. Update NextDrupal client.

Update the `NextDrupal` client to use the **Bearer** authentication header.

```ts title=lib/drupal.ts
import { NextDrupal } from "next-drupal"

const baseUrl = process.env.NEXT_PUBLIC_DRUPAL_BASE_URL as string
const clientId = process.env.DRUPAL_CLIENT_ID as string
const clientSecret = process.env.DRUPAL_CLIENT_SECRET as string

export const drupal = new NextDrupal(process.env.NEXT_PUBLIC_DRUPAL_BASE_URL, {
  auth: {
    clientId,
    clientSecret,
  },
  withAuth: true,
})
```


Create OAuth Client


Implement draft mode using two API routes.

<Callout>

If you're using the Basic Starter, draft routes are already created for you.

</Callout>

## /app/api/draft/route.ts

```ts title=app/api/draft/route.ts
import { drupal } from "@/lib/drupal"
import { enableDraftMode } from "next-drupal/draft"
import type { NextRequest } from "next/server"

export async function GET(request: NextRequest): Promise<Response | never> {
  return enableDraftMode(request, drupal)
}
```

---

## /app/api/disable-draft/route.ts

```ts title=app/api/disable-draft/route.ts
import { disableDraftMode } from "next-drupal/draft"
import type { NextRequest } from "next/server"

export async function GET(request: NextRequest) {
  return disableDraftMode()
}
```


Configure Draft Routes


Next, we need to configure draft mode for the content types. This will display an inline draft in an iframe when you visit the content pages.

---

## Configure Draft

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

<Callout>

A _site resolver_ tells Drupal how to resolve the draft 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. Click **Save**
5. Edit the newly created entity type.
6. On the Draft Mode tab, select **Site selector** as the **plugin**
7. Select **your site** under **Next.js sites**
8. Click **Save**

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


Configure Content Types


Congratulations. You have successfully configured draft 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).



[On-demand Revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation) makes it easy to update your Next.js site when content on Drupal is created, updated or deleted.

Next.js for Drupal supports On-demand Revalidation configurable per entity types. You can choose to revalidate content by path, or by tag. Tag-based invalidation is new as of Next Drupal 2.0 and allows you to invalidate content on your Next.js site using Drupal's powerful cache tag system.



Vist your Next.js site configuration page on Drupal to configure on-demand revalidation.

1. Visit `/admin/config/services/next`.
2. Click **Edit** next to your site.
3. Click **On-demand Revalidation**.
4. Fill in the following values:

- **Revalidate URL**: `http://localhost:3000/api/revalidate`
- **Revalidate secret**: `secret`

5. Click **Save**


Configure Next.js site


Next, we need to configure on-demand revalidation for the entity types.

To enable on-demand revalidation for an entity type, we need to configure a **revalidator** plugin.

<Callout>

A _revalidator_ tells Drupal how to revalidate an entity when it is created, updated or deleted.

</Callout>

### Configure Tag-based Revalidation

1. Visit `/admin/config/services/next/entity-types`
2. Click **Configure entity type** or **Edit** an existing one
3. Click **On-demand Revalidation**
4. Select **Cache Tag** as the revalidator **Plugin**
5. If using the **Path** plugin, check the **Revalidate page** checkbox
6. Click **Save**

### Configure Path-based Revalidation

7. Visit `/admin/config/services/next/entity-types`
8. Click **Configure entity type** or **Edit** an existing one
9. Click **On-demand Revalidation**
10. Select **Path** as the revalidator **Plugin**
11. Check the **Revalidate page** checkbox
12. Click **Save**

If you want to revalidate multiple pages, you can configure **Additional paths**. Example: you might want to revalidate the `/blog` landing page when an Article is created.


Configure Entity Types


Implement on-demand revalidation using an API route at `/revalidate`.

## Update Environment Variables

First, update `.env.local` to include the revalidate secret you specified.

```txt title=.env.local
# Required for On-demand Revalidation
DRUPAL_REVALIDATE_SECRET=secret
```

## Create the Revalidate Route

Next, create the API route that will be used for on-demand revalidation.

<Callout>

If you're using the Basic Starter, the revalidate route is already created for you. You can skip this step.

</Callout>

## /app/api/revalidate/route.ts

```ts title=app/api/revalidate/route.ts
import { revalidatePath, revalidateTag } from "next/cache"
import type { NextRequest } from "next/server"

async function handler(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams
  const path = searchParams.get("path")
  const tags = searchParams.get("tags")
  const secret = searchParams.get("secret")

  // Validate secret.
  if (secret !== process.env.DRUPAL_REVALIDATE_SECRET) {
    return new Response("Invalid secret.", { status: 401 })
  }

  // Either tags or path must be provided.
  if (!path && !tags) {
    return new Response("Missing path or tags.", { status: 400 })
  }

  try {
    path && revalidatePath(path)
    tags?.split(",").forEach((tag) => revalidateTag(tag))

    return new Response("Revalidated.")
  } catch (error) {
    return new Response((error as Error).message, { status: 500 })
  }
}

export { handler as GET, handler as POST }
```


Configure Revalidate Route


When fetching data using the Next Drupal Client, you will also need to set the necessary revalidation parameters. This tells Next.js that the content should be cached, and what metadata can be used to invalidate that cache.

<Callout>

If you're using the Basic Starter, most of this configuration is already created for you. You will only need to replace `revalidate` with `tags` in the options object when using Next Drupal Client methods like `getResource` if you'd prefer to use tag-based revalidation.

</Callout>

Consider the `getNode` function in the `[...slug]` dynamic route in the basic starter:

```ts title=app/[..slug]/page.tsx
async function getNode(slug: string[]) {
  const path = `/${slug.join("/")}`

  const params: JsonApiParams = {}

  // Translating the path also allows us to discover the entity type.
  const translatedPath = await drupal.translatePath(path)

  if (!translatedPath) {
    throw new Error("Resource not found", { cause: "NotFound" })
  }

  const type = translatedPath.jsonapi?.resourceName!
  const uuid = translatedPath.entity.uuid
  const tag = `${translatedPath.entity.type}:${translatedPath.entity.id}`

  if (type === "node--article") {
    params.include = "field_image,uid"
  }

  const resource = await drupal.getResource<DrupalNode>(type, uuid, {
    params,
    cache: "force-cache",
    next: {
      revalidate: 3600,
      // Replace `revalidate` with `tags` if using tag based revalidation.
      // tags: [tag],
    },
  })

  return resource
}
```

## Path-based Revalidation

The call to `getResource` in the above example is already configured to use path-based invalidation. The data will be cached for 3600 seconds unless revalidated on-demand.

```tsx
const resource = await drupal.getResource<DrupalNode>(type, uuid, {
  params,
  cache: "force-cache",
  next: {
    revalidate: 3600,
  },
})
```

## Tag-based Revalidation

To instead use tag-based invalidation, we can replace the `revalidate` option with the `tags` option:

```tsx
const resource = await drupal.getResource<DrupalNode>(type, uuid, {
  params,
  cache: "force-cache",
  next: {
    tags: [tag],
  },
})
```

In this example, the tag is set earlier in the function using data from the translated path:

```tsx
const type = translatedPath.jsonapi?.resourceName!
const uuid = translatedPath.entity.uuid
const tag = `${translatedPath.entity.type}:${translatedPath.entity.id}`
```

This option accepts an array of tags, and values should match the cache tag values set by Drupal. With this configuration, the data will be cached until Drupal makes a call to the revalidate route using any of the matching cache tags.


Set Revalidation Parameters


Congratulations. You have successfully configured on-demand revalidation for your entity types.

When you create, update or delete an entity in Drupal, your Next.js site will be revalidated to show the updates.

---

## What's next?

On-demand Revalidation is built on top of Drupal's Events API and Revalidator plugins.

If you'd like to customize, extend or provide your own revalidator plugin, see the documentation [here](/docs/revalidator).

See also the [Entity Events documentation](/docs/entity-events).

---

## Need help?

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


Getting Started

NextDrupal Client

Working with JSON:API

Building Pages

Customization

Drupal

Apply Patches