
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, getResourceCollectionFromContext } from "next-drupal"
import { DrupalJsonApiParams } from "drupal-jsonapi-params"

export async function getStaticProps(context) {
  // highlight-start
  const params = new DrupalJsonApiParams()

  params
    .addFields("node--blog_post", ["title", "path", "body", "uid"])
    .addFilter("status", "1")
    .addInclude(["uid.user_picture"])
    .addSort("created", "DESC")
  // highlight-end

  const articles = await getResourceCollectionFromContext<DrupalNode[]>(
    "node--blog_post",
    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


We have included a few types you can use to properly type your JSON:API responses:

## DrupalNode

Retrieving an `article` node by id:

```tsx
import { DrupalNode } from "next-drupal"

const node = await getResource<DrupalNode>(
  "node--article",
  "e96869cb-2b58-4863-ba18-1480f6696bb9"
)
```

---

Retrieving a `news` node by path:

```tsx
import { DrupalNode } from "next-drupal"

const node = await getResourceByPath<DrupalNode>("/path/to/news")
```

---

Retrieving a collection of `articles` from context:

```tsx
import { DrupalNode } from "next-drupal"

const articles = await getResourceCollectionFromContext<DrupalNode[]>(
  "node--article",
  context
)
```

## Available types

- `DrupalNode`
- `DrupalMedia`
- `DrupalTaxonomyTerm`
- `DrupalBlock`
- `DrupalUser`
- `DrupalMenuLinkContent`

You can see a list of type definitions [here](https://github.com/chapter-three/next-drupal/blob/main/packages/next-drupal/src/types.ts).

## getStaticProps

You can use the type definition to type your getStaticProps responses as follows:

```tsx title=pages/index.tsx
import {
  getPathsFromContext,
  getResourceCollectionFromContext,
  DrupalNode,
} from "next-drupal"

interface BlogPageProps {
  nodes: DrupalNode[] // highlight-line
}

export default function BlogPage({ nodes }: BlogPageProps) {
  return // .....
}

// highlight-start
export async function getStaticProps(
  context
): Promise<GetStaticPropsResult<BlogPageProps>> {
  const nodes = await getResourceCollectionFromContext<DrupalNode[]>(
    "node--article",
    context
  )
  // highlight-end

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


TypeScript


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 } from "html-react-parser" // highlight-line
import { Element } from "domhandler/lib/node"
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"

export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse
) {
  try {
    if (request.method === "POST") {
      // Submit to Drupal.
      const result = await fetch(
        `${process.env.NEXT_PUBLIC_DRUPAL_BASE_URL}/webform_rest/submit`,
        {
          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,
  getPathsFromContext,
  getResourceFromContext,
  getView,
  translatePathFromContext,
} from "next-drupal"

export async function getStaticProps(
  context
): Promise<GetStaticPropsResult<NodePageProps>> {
  // Get information about the path.
  const path = await 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 type = path.jsonapi.resourceName
  const resource = await getResourceFromContext<DrupalNode>(type, 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
```

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 { getSearchIndex } from "next-drupal"

const results = await 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, getSearchIndex } from "next-drupal"

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

    const { index } = request.query

    const results = await 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 },
    },
  }),
})
```

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


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


Getting Started

Drupal Client Experimental

Data Fetching

Authentication

Reference

Hooks

Drupal

Guides