
JSON:API has a hard limit of 50 resources per page. You can read more about this decision [here](https://www.drupal.org/docs/core-modules-and-themes/core-modules/jsonapi-module/pagination#s--cant-i-set-a-page-limit-higher-than-50).

When building a decoupled site with Next.js, there are some cases, example in `getStaticPaths`, where you might want to fetch more than 50 resources.

We added a spec-compliant override to bypass this limit in next-drupal.

<Callout icon="⚠️">

Tip: If you have a site with a large number of pages, consider using on-demand generation using `fallback: blocking` instead of increasing the page limit.

</Callout>

## Configuration

To override the page max size, set the following `parameter` in your Drupal `settings.yml` file and clear caches.

```yaml
parameters:
  next_jsonapi.size_max: 100 // Set your max limit here.
```

You should now be able to request up to 100 resources **using the `path` field as the first field in sparse fieldsets**.

## Examples

The following will return 50 items (JSON:API hard limit - No override):

```ts
const articles = await drupal.getResourceCollection("node--article")
```

The following will return 10 items (No override):

```ts
const articles = await drupal.getResourceCollection("node--article", {
  "page[limit]": 10,
})
```

The following will return 100 items (Overridden using `path`):

```ts
const articles = await drupal.getResourceCollection("node--article", {
  "field[node--article]": "path,title",
})
```

The following will return 60 items (Overridden using `path`):

```ts
const articles = await drupal.getResourceCollection("node--article", {
  "field[node--article]": "path,title",
  "page[limit]": 60,
})
```

The following will return 100 items (`next_jsonapi.max_size` hard limit - Overridden using `path`):

```ts
const articles = await drupal.getResourceCollection("node--article", {
  "field[node--article]": "path,title",
  "page[limit]": 999,
})
```


Page Limit


## Drupal

1. Create a new Drupal project

```bash
composer create-project drupal/recommended-project umami
```

2. Edit `composer.json` file and add the following patches under `extra`.

```json
"extra": {
    "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"
        }
    },
}
```

3. Add dependencies

```bash
composer require drupal/next drupal/jsonapi_menu_items drupal/jsonapi_views 'drupal/jsonapi_resources:^1.0@beta'
```

4. Install Drupal. Make sure you select **Demo: Umami Food Magazine (Experimental)** as the installation profile.

   For a quick installation, you may also use the `quick-start` command:

```bash
php -d memory_limit=256M ./web/core/scripts/drupal quick-start demo_umami
```

4. Enable the following modules:

- Next
- Next JSON:API
- JSON:API Menu Items
- JSON:API Views

---

## Next.js

1. Grab a copy of the Next.js code:

```bash
git clone https://github.com/chapter-three/next-example-umami
```

2. Install dependencies

```
yarn install
```

3. Copy `.env.example` to `.env.local` and update the values to point to your Drupal site:

```
NEXT_PUBLIC_DRUPAL_BASE_URL=http://drupal.test
NEXT_IMAGE_DOMAIN=drupal.test
```

4. Start the development server

```
yarn dev
```

5. Visit `http://localhost:3000` to see the Next.js site.

---

## How to enable authentication

We use the [simple_oauth](https://drupal.org/project/simple_oauth) module for authentication.

1. Visit `/admin/config/people/simple_oauth`.
2. Click on **Generate Keys**.
3. Enter `sites/default/files` for **Directory for the keys** and click **Generate**.
4. Visit `/admin/config/services/consumer` and edit the default client.
5. Enter `weDKc7PD845kq49JfPeYmsZ48e`under **New Secret** and **Save**.
6. Update your `.env.local` with the following:

```diff
# Required
NEXT_PUBLIC_DRUPAL_BASE_URL=http://localhost:8888
NEXT_IMAGE_DOMAIN=localhost

+ # Authentication (Bearer)
+ NEXTAUTH_SECRET=zdauNuBL7lLAHT9zIpxExCThVHSSOfIwouGOhr5cjWQ
+ NEXTAUTH_URL=http://localhost:3000
+ DRUPAL_CLIENT_ID=YOUR_DEFAULT_CLIENT_UUID_HERE
+ DRUPAL_CLIENT_SECRET=weDKc7PD845kq49JfPeYmsZ48e
```

7. Restart the Next.js development server.
8. If you visit `http://localhost:3000/login`, you should now be able to login with the Drupal admin username and password.

---

## How to enable JSON:API Write Operations

1. Visit `/admin/config/services/jsonapi`
2. Under **Allowed Operations**, select **Accept all JSON:API create, read, update, and delete operations.**.
3. **Save configuration**

You can now visit `http://localhost:3000/articles/new` to create a new article.


Umami Demo


next-drupal has support for [Drupal JSON:API Params](https://github.com/d34dman/drupal-jsonapi-params), a helper for building query params.

You use query params for filtering, sorting and paginating resources returned by JSON:API.

---

## Installation

```
yarn add drupal-jsonapi-params
```

## Usage

```tsx
import { DrupalNode } from "next-drupal"
import { DrupalJsonApiParams } from "drupal-jsonapi-params"

export async function getStaticProps(context) {
  // highlight-start
  const params = new DrupalJsonApiParams()
    .addFields("node--blog_post", ["title", "path", "body", "uid"])
    .addFilter("status", "1")
    .addInclude(["uid.user_picture"])
    .addSort("created", "DESC")
  // highlight-end

  const articles = await drupal.getResourceCollectionFromContext<DrupalNode[]>(
    "node--article",
    context,
    {
      params: params.getQueryObject(), // highlight-line
    }
  )
}
```

You can read more about Drupal JSON:API Params [here](https://github.com/d34dman/drupal-jsonapi-params).


JSON:API Params


Starting with `v12.1.0`, Next.js added support for [on-demand Incremental Static Regeneration](https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration).

<Callout icon="⚠️">

On-demand revalidation is experimental in Next.js 12.1.0, so we're shipping it in the `next_extras` module as experimental as well.

</Callout>

## Implementation

1. On your Drupal site, visit `/admin/modules` and enable the **Next Extras** module.
2. Next, visit `/admin/config/services/next/entity-types` and click edit next to an entity type.
3. Under **Experimental** are the settings for revalidation.
4. You can provide additional paths for revalidation under **Paths**.

On the Next.js site, implement the following route.

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

export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse
) {
  let slug = request.query.slug as string
  const secret = request.query.secret as string

  // Validate secret.
  if (secret !== process.env.DRUPAL_PREVIEW_SECRET) {
    return response.status(401).json({ message: "Invalid secret." })
  }

  // Validate slug.
  if (!slug) {
    return response.status(400).json({ message: "Invalid slug." })
  }

  try {
    await response.revalidate(slug)

    return response.json({})
  } catch (error) {
    return response.status(404).json({
      message: error.message,
    })
  }
}
```

## Usage

Now whenever the configured entity type is updated or deleted on your Drupal site, the `next_extras` module will ping your Next.js site to purge the cache and revalidate the page.


On-demand Revalidation


To handle inline images and media entities added via a WYSIWYG editor, we can use an html parser
to replace the `img` tags with the Next.js `Image` component.

---

## Dependencies

Install [html-react-parser](https://github.com/remarkablemark/html-react-parser).

```sh
yarn add html-react-parser
```

---

## Component

Let's create a component to render a `text_long` (example: `node.body.processed`) field type.

```tsx title=components/body.tsx
import { HTMLReactParserOptions } from "html-react-parser"
import { Element } from "domhandler/lib/node"
import parse from "html-react-parser"
import Image from "next/image"

const options: HTMLReactParserOptions = {
  replace: (domNode) => {
    // Look for an img tag and replace it with Image.
    if (domNode instanceof Element && domNode.name === "img") {
      const { src, alt, width, height } = domNode.attribs

      return (
        <Image
          src={`${process.env.NEXT_PUBLIC_DRUPAL_BASE_URL}/${src}`}
          width={`${width}px`}
          height={`${height}px`}
          alt={alt}
          layout="intrinsic"
          objectFit="cover"
        />
      )
    }
  },
}

export function Body({ value }: { value: string }) {
  return <>{parse(value, options)}</>
}
```

<Callout>

We use `intrinsic` layout so that images scale down for smaller viewports but maintain the original dimensions for larger viewports.

</Callout>

## Usage

```tsx title=pages/index.tsx
import { Body } from "components/body"

export default function Page({ node }) {
  return (
    <div variant="container">
      <h1>{node.title}</h1>
      <Body value={node.body.processed} /> // highlight-line
    </div>
  )
}
```

Learn more about [next/image](https://nextjs.org/docs/api-reference/next/image).


Inline Images


To replace inline `<a />` tags with the Next.js `Link` component, we can use an html parser like we did for [images](/docs/guides/inline-images).

---

## Dependencies

Install [html-react-parser](https://github.com/remarkablemark/html-react-parser).

```sh
yarn add html-react-parser
```

---

## Component

Update the component from [images](/docs/guides/inline-images) to handle inline links.

```tsx title=components/body.tsx
import { HTMLReactParserOptions, domToReact, Element } from "html-react-parser" // highlight-line
import parse from "html-react-parser"
import Image from "next/image"
import Link from "next/link" // highlight-line

const options: HTMLReactParserOptions = {
  replace: (domNode) => {
    if (domNode instanceof Element && domNode.name === "img") {
      const { src, alt, width, height } = domNode.attribs

      return (
        <Image
          src={`${process.env.NEXT_PUBLIC_DRUPAL_BASE_URL}/${src}`}
          width={`${width}px`}
          height={`${height}px`}
          alt={alt}
          layout="intrinsic"
          objectFit="cover"
        />
      )
    }

    // highlight-start
    if (domNode.name === "a") {
      const { href, class: className } = domNode.attribs

      return (
        <Link href={href} passHref>
          <a className={className}>{domToReact(domNode.children)}</a>
        </Link>
      )
    }
    // highlight-end
  },
}

export function Body({ value }: { value: string }) {
  return <>{parse(value, options)}</>
}
```

---

## Usage

```tsx title=pages/index.tsx
import { Body } from "components/body"

export default function Page({ node }) {
  return (
    <div variant="container">
      <h1>{node.title}</h1>
      <Body value={node.body.processed} /> // highlight-line
    </div>
  )
}
```

Learn more about [next/link](https://nextjs.org/docs/api-reference/next/link).


Links


Route syncing is a feature of the iframe preview. It captures route changes inside the iframe preview and syncs with the Drupal site.

_Example: if you navigate to an article node inside the iframe preview, route syncing will listen for this route change and redirect the Drupal site to the article node._

This is handy as it maintains editing context.

Route syncing supports translations and revisions.

<Callout>

Route syncing uses the [Window.postMessage()](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) API to safely communicate the route change to the Drupal site.

The `targetOrigin` is pulled from the configured `NEXT_PUBLIC_DRUPAL_BASE_URL` inside `.env`.

</Callout>

## Demo

<Video src="/videos/next-drupal-route-syncing.mp4" />

## Configuration

1. On your Drupal site, visit `/admin/config/services/next/settings`.
2. Check **Sync routes**
3. Save.

Next add the following code to your `_app.js` file on your Next.js site.

```jsx
// highlight-start
import Router from "next/router"
import { syncDrupalPreviewRoutes } from "next-drupal"

Router.events.on("routeChangeStart", function (path) {
  syncDrupalPreviewRoutes(path)
})
// highlight-end

export default function App({ Component, pageProps }) {
  // ...
}
```

<Img
  src="/images/route-syncing.gif"
  width="960"
  height="740"
  layout="responsive"
  alt="Route syncing"
  mb="10"
>
  <>Turn on route syncing</>
</Img>

Restart your dev server.

If you visit a node on your Drupal site and click on any link inside the iframe preview, you should now see the route changes synced.

### Skipping Routes

If you want to disable syncing for some routes, say routes defined in your Next.js site and not in Drupal, you can do so by specifying the route paths under **Skip routes**.

<Img
  src="/images/route-syncing-skip.png"
  width="960"
  height="780"
  layout="responsive"
  alt="Route syncing"
  mb="10"
>
  <>Skip routes</>
</Img>


Route Syncing


There are two ways to handle [Webform](http://drupal.org/project/webform) in Next.js for Drupal.

1. [Client Side](/docs/guides/webform#client-side)
2. [Server Side](/docs/guides/webform#server-side) (API Route)

Both implementations use the [Webform REST](http://drupal.org/project/webform_rest) module.

---

## Demo

See [https://example-webform.next-drupal.org](https://example-webform.next-drupal.org).

---

## Installation

1. Install the Webform REST module: `composer require drupal/webform_rest`
2. Visit `/admin/config/services/rest` and enable the **Webform Submit** resource.
3. Select _POST_ for the **Methods**, _json_ for **Accepted request formats** and _cookie_ for **Authentication providers**
4. **Save configuration**
5. Next, visit `/admin/people/permissions` and give anonymous users the **Access POST on Webform Submit resource** permission.

---

## Client Side

We use the Webform REST module to submit the form values directly to Drupal.

<Callout>

Note: when submitting webform values client-side, the `webform_id` and the Drupal base URL is exposed.

</Callout>

```tsx
export default function ContactPage() {
  async function handleSubmit(event) {
    event.preventDefault()

    const response = await fetch(
      `${process.env.NEXT_PUBLIC_DRUPAL_BASE_URL}/webform_rest/submit`,
      {
        method: "POST",
        body: JSON.stringify({
          webform_id: "contact",
          name: event.target.name.value,
          email: event.target.email.value,
        }),
        headers: {
          "Content-Type": "application/json",
        },
      }
    )

    if (response.ok) {
      // Show success.
    }

    // Handle error.
  }

  return (
    <div>
      <form onSubmit={handleSubmit}>
        <p>Implement your form here</p>
        <div>
          <label htmlFor="name">Name</label>
          <input type="text" id="name" name="name" />
        </div>
        <div>
          <label htmlFor="email">Email</label>
          <input type="email" id="email" name="email" />
        </div>
        <button type="submit">Submit</button>
      </form>
    </div>
  )
}
```

---

## Server side

We submit the form values to a custom API route first. The API route then submits the form to Drupal using the Webform REST module.

This is useful if we need to hide client IDs and secrets or our Drupal implementation.

1. Create a `/pages/api/contact` API route to handle our POST request.

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

export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse
) {
  try {
    if (request.method === "POST") {
      const url = drupal.buildUrl("/webform_rest/submit")

      // Submit to Drupal.
      const result = await drupal.fetch(url.toString(), {
        method: "POST",
        body: JSON.stringify({
          webform_id: "contact",
          name: request.body.name,
          email: request.body.email,
        }),
        headers: {
          "Content-Type": "application/json",
        },
      })

      if (!result.ok) {
        throw new Error()
      }

      response.status(200).end()
    }
  } catch (error) {
    return response.status(400).json(error.message)
  }
}
```

2. Next, update our contact form to submit to this API route.

```tsx
export default function ContactPage() {
  async function handleSubmit(event) {
    event.preventDefault()

    const response = await fetch(`/api/contact`, {
      method: "POST",
      body: JSON.stringify({
        name: event.target.name.value,
        email: event.target.email.value,
      }),
    })

    if (response.ok) {
      // Show success.
    }

    // Handle error.
  }

  return (
    <div>
      <form onSubmit={handleSubmit}>
        <p>Implement your form here</p>
        <div>
          <label htmlFor="name">Name</label>
          <input type="text" id="name" name="name" />
        </div>
        <div>
          <label htmlFor="email">Email</label>
          <input type="email" id="email" name="email" />
        </div>
        <button type="submit">Submit</button>
      </form>
    </div>
  )
}
```

## Example

See [example-webform](https://github.com/chapter-three/next-drupal/tree/main/examples/example-webform) for a real-life example of building webform with **react-hook-form** and handling validation using **yup**.


Webform


<Callout>

This guide uses `translatedPathFromContext` which is available in `next-drupal ^1.1.0`.

</Callout>

---

## Next.js

To use redirects in Next.js you can configure a `redirects` key in `next.config.js`.

```js title=next.config.js
module.exports = {
  async redirects() {
    return [
      {
        source: "/about",
        destination: "/",
        permanent: true,
      },
    ]
  },
}
```

---

## Redirect Module

To handle redirects coming from Drupal ([redirect module](https://www.drupal.org/project/redirect)), you can use `translatedPathFromContext`.

Here's how you can handle redirect in `getStaticProps`.

```tsx title=pages/[...slug].tsx
import { DrupalNode } from "next-drupal"

export async function getStaticProps(
  context
): Promise<GetStaticPropsResult<NodePageProps>> {
  // Get information about the path.
  const path = await drupal.translatePathFromContext(context)

  if (!path) {
    return {
      notFound: true,
    }
  }

  // Check for redirect.
  if (path.redirect?.length) {
    const [redirect] = path.redirect
    return {
      redirect: {
        destination: redirect.to,
        permanent: redirect.status === "301",
      },
    }
  }

  // No redirect. Fetch the resource for this type.
  const resource = await drupal.getResourceFromContext<DrupalNode>(
    path,
    context
  )
}
```

With `fallback: "blocking"` in `getStaticPaths`, this will cache and handle redirects configured in Drupal and still work with incremental static regeneration.


Redirects


<Callout>

You need to install the [JSON:API Search API](https://www.drupal.org/project/jsonapi_search_api) module to query your Search API indexes.

</Callout>

---

## Installation

1. Start by installing the [Search API](https://www.drupal.org/project/search_api) module. If you want faceted search, install the [Facets](https://www.drupal.org/project/facets) module as well.

```sh
composer require drupal/search_api drupal/facets drupal/jsonapi_search_api drupal/jsonapi_search_api_facets
```

2. Enable the following modules: **Search API**, **Database Search**, **Facets**, **JSON:API Search API** and **JSON:API Search API Facets**.
3. Create a **server** and **index** by following the guide [here](https://www.drupal.org/docs/contributed-modules/search-api).

For every index created, a **facet source** is available. You can use this source to create filters.

4. Visit `/admin/config/search/facets` and click on **Add facet**.
5. Under **Facet source**, select the server created above. For **Field**, select the field to filter on. Save.
6. Next, edit the facet and make sure **JSON:API Search API** is selected under widget.
7. You can now make queries to your indexes via JSON:API.

```ts
import { drupal } from "lib/drupal"

const results = await drupal.getSearchIndex(indexName, {
  params: {
    filter: { name_of_field: value },
  },
})
```

## Implementation

We recommend using an [API route](https://nextjs.org/docs/api-routes/introduction) for querying the search index. Using an API route means you can share search indexes, implement rate limiting and filtering using middlewares.

1. Create the following API route.

```ts title=api/pages/[index].tsx
import { NextApiRequest, NextApiResponse } from "next"
import { DrupalNode } from "next-drupal"

import { drupal } from "lib/drupal"

export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse
) {
  try {
    const body = JSON.parse(request.body)

    const { index } = request.query

    const results = await drupal.getSearchIndex<DrupalNode>(
      index as string,
      body
    )

    response.json(results)
  } catch (error) {
    return response.status(400).json(error.message)
  }
}
```

2. To make a search request from your React component, you can use a simple fetch request.

```tsx
const response = await fetch("/api/search/INDEX-NAME-HERE", {
  method: "POST",
  body: JSON.stringify({
    params: {
      filter: { name_of_field: value },
    },
  }),
})
```

## Localized Search Results

Next.js API Routes have no context of the current locale. For localized search results, you should pass the `locale` and `defaultLocale` from the router.

```tsx
const router = useRouter()

const response = await fetch("/api/search/INDEX-NAME-HERE", {
  method: "POST",
  body: JSON.stringify({
    params: {
      filter: { name_of_field: value },
    },
    locale: router.locale,
    defaultLocale: router.defaultLocale,
  }),
})
```

## Demo

See [https://example-search-api.next-drupal.org](https://example-search-api.next-drupal.org).

## Example

See [https://github.com/chapter-three/next-drupal/tree/main/examples/example-search-api](https://github.com/chapter-three/next-drupal/tree/main/examples/example-search-api)


Search API


<Callout>

Note: This is available for Drupal **9.3.x** only. See the change record [here](https://www.drupal.org/node/3218910).

</Callout>

If you have multiple Next.js sites built from one Drupal source, you can filter JSON:API resources by site using the site `machine_name`.

---

## Collection

You can filter resource collection using `FIELD_NAME.meta.drupal_internal__target_id`.

```tsx
// Fetch all Article nodes where the entity reference field `field_sites` has value blog.
const nodes = await drupal.getResourceCollection<DrupalNode[]>(
  "node--article",
  {
    params: {
      filter: {
        "field_sites.meta.drupal_internal__target_id": "blog", // highlight-line
      },
    },
  }
)
```

<Callout>

- `field_sites` is a **Next.js site** entity reference field on the `Article` content type.
- `blog` is the ID of the Next.js site.

</Callout>

In `getStaticProps` you can use:

```tsx
export async function getStaticProps(
  context
): Promise<GetStaticPropsResult<IndexPageProps>> {
  const nodes = await drupal.getResourceCollectionFromContext<DrupalNode[]>(
    "node--article",
    context,
    {
      params: {
        include: "field_image,uid",
        sort: "-created",
        filter: {
          "field_sites.meta.drupal_internal__target_id": "blog",
        },
      },
    }
  )

  return {
    props: {
      nodes,
    },
  }
}
```

---

## Dynamic Routes

In `getStaticPaths` you can filter by site by passing `params`:

```tsx
export async function getStaticPaths(context): Promise<GetStaticPathsResult> {
  const paths = await drupal.getStaticPathsFromContext(
    ["node--article"],
    context,
    {
      params: {
        filter: {
          "field_sites.meta.drupal_internal__target_id": "blog",
        },
      },
    }
  )

  return {
    paths,
    fallback: false,
  }
}
```


Getting Started

Drupal Client

Working with JSON:API

Building Pages

Customization

Reference

Drupal

Guides