Next-Drupal 2.0


Today's release is a big one. We are announcing support for **Next.js 13** and **Drupal 10**.

We also rewrote the implementation for on-demand revalidation. The Drupal module now ships with **stable on-demand revalidation** built on top of Drupal events API and plugin system.

We are approaching **3000+** downloads per week. Thanks everyone. 🎉

---

## Next.js 13

We have updated `next-drupal` and the (JSON:API and GraphQL) starters to Next.js 13.

You can now safely update your site and start implementing new Next.js 13 features such as the new `<Image />` and `<Link />` components, add `@next/font`...etc.

```sh
yarn add next-drupal@latest
```

---

## Drupal 10

The `next` module has been updated to Drupal 10. We've removed all deprecated code and APIs.

**Note: This also means, as of `1.6.0`, we are stopping Drupal 8 support. You can upgrade your site to Drupal 9.3+ or Drupal 10 when it's released.**

---

## On-demand Revalidation

The implementation for On-demand Revalidation has been completely rewritten in `1.6.0` and is now stable.

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

You can provide your own `Revalidator` plugins to execute custom code when an entity is inserted, updated or deleted.

```php showLineNumbers title="custom_module/src/Plugin/Next/Revalidator/CustomRevalidator.php"
<?php

namespace Drupal\custom_module\Plugin\Next\Revalidator;

use Drupal\next\Event\EntityActionEvent;
use Drupal\next\Plugin\RevalidatorBase;

/**
 * Provides a custom revalidator.
 *
 * @Revalidator(
 *  id = "custom",
 *  label = "Custom Revalidator",
 *  description = "Description for the custom revalidator"
 * )
 */
class CustomRevalidator extends RevalidatorBase {

  /**
   * {@inheritdoc}
   */
  public function revalidate(EntityActionEvent $event): bool {
	// Called when entity is created, updated or deleted.
  }

}
```

See the [docs for Revalidator plugins](/docs/revalidator).

### Entity Events

We have also added entity events so you can build your own event subscribers for when an entity is inserted, updated or updated.

You can also use event subscribers to execute code **post revalidation**.

```php showLineNumbers title="custom_module/src/EventSubscriber/EventSubscriber.php"
<?php

namespace Drupal\next_tests\EventSubscriber;

use Drupal\next\Event\EntityEvents;
use Drupal\next\Event\EntityRevalidatedEventInterface;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

/**
 * Defines an event subscriber for entity revalidated events.
 */
class EventSubscriber implements EventSubscriberInterface {

  /**
   * {@inheritdoc}
   */
  public static function getSubscribedEvents() {
    $events[EntityEvents::ENTITY_REVALIDATED] = ['onRevalidated'];
    return $events;
  }

  /**
   * Responds to entity revalidated.
   *
   * @param \Drupal\next\Event\EntityRevalidatedEventInterface $event
   *   The event.
   */
  public function onRevalidated(EntityRevalidatedEventInterface $event) {
    if ($event->isRevalidated()) {
	 // Do something if entity has been successfully revalidated.
	}
  }

}
```

---

## Version Matching

As of `1.6.0`, we are going to match minor versions for `next-drupal` and `next` module.

Bumping a minor in `next-drupal` will bump same in `next` module.

<Callout>

Note: To match minor for `next-drupal 1.6.0`, we are skipping `next 1.5.0`.

</Callout>

---

## Upgrading

You can upgrade to `1.6.0` by following our upgrade guide [here](/docs/upgrade-guide).


Next-Drupal 1.6


One of the [most requested features](https://www.chapterthree.com/blog/nextjs-drupal-and-graphql-how-to-use-graphql-next-drupal) of Next.js for Drupal has been GraphQL support.

When we started working on Next.js for Drupal, GraphQL for Drupal was in between releases. We started looking into supporting GraphQL but version 4 shipped without schema definitions and onboarding took some learning.

We've been following the work done by the GraphQL team closely. A few months ago, [jmolivas](https://twitter.com/jmolivas) announced GraphQL Compose, _a GraphQL spec compliant schema generation for the GraphQL module v4.x_.

This is exactly what we've been waiting for.

Today, we are announcing `next 1.4` with support for GraphQL using GraphQL Compose.

```sh
composer require 'drupal/next:^1.4' 'drupal/graphql:^4.4' 'drupal/graphql_compose:^1.0@beta'
```

All the features of Next.js, including Preview Mode, work out of the box.

---

## GraphQL Starter

We built a new Next.js starter for GraphQL. Check it out:

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

---

## Getting Started

The Quick Start section now includes guides for configuring GraphQL for Next.js. You can see the guide [here](/learn/graphql).


Next 1.4


In this release of Next 1.3, the Drupal module, and Next-Drupal 1.5, we're introducing _Preview URL Generators_.

## Preview URL Generators

Preview URL Generators are used for generating URLs for preview mode with encrypted secrets.

<Img
  src="/images/preview-mode-encrypted-secrets.png"
  width="800"
  height="240"
/>

Compared to the preview secrets used in previous releases, the new secrets are:

- Generated per requests
- Encrypted and not re-usabled
- Scoped to the current URL and user
- With expiration dates
- Validated by Drupal (no client validation)
- Pluggable (bring your own secret generator)

Upgrading to Next 1.3 is easy. See the upgrade guide [here](/docs/upgrade-guide).

Note: You should also upgrade to the latest `next-drupal` to use the new encrypted secrets.

---

## JSON Web Tokens

We are also introducing a new module, **Next.js JWT**, for using JSON Web Tokens for authentication.

Next.js JWT ships with a Preview URL generator that enables user-level access control for more granularity.

Next.js JWT ships as **experimental** in Next 1.3.

---

## Thank You

Thanks [Lauri](https://www.drupal.org/u/lauriii) for helping with this release. 🥳


Next-Drupal 1.5 and Next 1.3


In April, we released `next-drupal 1.3` with `DrupalClient`, a powerful and customizable JSON:API client for fetching data from Drupal.

Two months in, `DrupalClient` is a success. We have seen an increasing number of new projects adopting `DrupalClient`, from small headless projects to big brands building on top of next-drupal.

**We just passed 1000+ weekly downloads** 🎉.

Today, we're announcing `next-drupal 1.4` with **stable** DrupalClient and **write-operations (CRUD)** for JSON:API.

```sh
yarn add next-drupal@latest
```

<Callout>

The `DrupalClient` is an incremental upgrade. You can safely upgrade your site to `next-drupal 1.4.0` without any breaking changes.

</Callout>

## Features

1. [DrupalClient is now stable and production-ready](#drupalclient-is-now-stable-and-production-ready)
2. [Write operations for JSON:API](#write-operations-for-jsonapi)
3. [Support for more authentication methods](#support-for-more-authentication-methods)
4. [New documentation site](#new-documentation-site)
5. [Umami Demo](#umami-demo)

---

## DrupalClient is now stable and production-ready

```ts
import { DrupalClient } from "next-drupal"

const drupal = new DrupalClient("https://example.com")

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

We have upgraded the [basic starter](http://github.com/chapter-three/next-drupal-basic-starter) to use the `DrupalClient`.

---

## Write operations for JSON:API

You can now create, update, delete and fetch JSON:API resources using `next-drupal`.

### getResource

```ts
const article = await drupal.getResource(
  "node--article",
  "dad82fe9-f2b7-463e-8c5f-02f73018d6cb"
)
```

### createResource

```ts
const article = await drupal.createResource("node--article", {
  data: {
    attributes: {
      title: "Title of Article",
      body: {
        value: "<p>Content of body field</p>",
        format: "full_html",
      },
    },
  },
})
```

### createFileResource

```ts
const file = await drupal.createFileResource("file--file", {
  data: {
    attributes: {
      type: "media--image",
      field: "field_media_image",
      filename: "filename.jpg",
      file: await fs.readFile("/path/to/file.jpg"),
    },
  },
})
```

### updateResource

```ts
const article = await drupal.updateResource(
  "node--article",
  "a937dd34-5407-4fff-8594-fccaaa5bb72a",
  {
    data: {
      attributes: {
        title: "Title of Article",
      },
    },
  }
)
```

## deleteResource

```ts
const deleted = await drupal.deleteResource(
  "node--article",
  "a937dd34-5407-4fff-8594-fccaaa5bb72a"
)
```

---

## Support for more authentication methods

The `DrupalClient` works with several auth types. You can use Bearer tokens, Basic tokens or bring your own authorization headers.

Authentication can now be set globally on the client or custom per method.

### Client Authentication

Set a global auth to be used on the client.

```ts
import { DrupalClient } from "next-drupal"

export const drupal = new DrupalClient(
  process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
  {
    auth: // Configure the global auth here.
  }
)
```

### Method Authentication

Provide a custom auth per method call.

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

const userArticles = await drupal.getResourceCollection("node--article", {
  params: {
    "filter[uid]": user.id,
  },
  withAuth: // Set the custom auth here.
})
```

We have also added support for `clientId/clientSecret`, `username/password`, `callback` and **NextAuth.js** authentication methods.

---

## New documentation site

The documentation site got an upgrade. Every doc, guide and example have been rewritten for `DrupalClient`.

We have also added API reference for every method, with examples.

```ts
const resource = await drupal.getResource<T = JsonApiResource>(
  type,
  uuid,
  options?: {
    params,
    withAuth,
    deserialize,
    locale,
    defaultLocale,
    withCache,
  }
): Promise<T>
```

- `type: string`
  - **Required**
  - The resource type. Example: `node--article`, `taxonomy_term--tags`, or `block_content--basic`.
- `uuid: string`
  - **Required**
  - The id of the resource. Example: `15486935-24bf-4be7-b858-a5b2de78d09d`.
- `options`
  - Optional
  - `params: JsonApiParams`: JSON:API params such as `filter`, `fields`, `include` or `sort`.
  - `withAuth: boolean | DrupalClientAuth`:
    - Set the authentication method to use. See the [authentication docs](/docs/authentication).
    - Set to `true` to use the authentication method configured on the client.
  - `deserialize: boolean`: Set to false to return the raw JSON:API response.
  - `locale: string`: The locale to fetch the resource in.
  - `defaultLocale: string`: The default locale of the site.
  - `withCache: boolean`: Set `withCache` if you want to store and retrieve the resource from cache.
  - `cacheKey: string`: The cache key to use.

You can find the old documentation site [here](https://v1.next-drupal.org).

---

## Umami Demo

We rebuilt the Umami demo as a headless site using `next-drupal`:

- Translation Support
- Contact Form
- Search
- Authentication
- Create new articles via JSON:API
- Restyled using Tailwind CSS
- 💯 Lighthouse scores

You can see the demo [here](https://demo.next-drupal.org).

<Img src="/images/umami-demo.jpg" width="800" height="500" />

---

## Upgrading

You can try the new `DrupalClient` today by following our upgrade guide [here](/docs/upgrade-guide).


Next-Drupal 1.4


Since releasing `next-drupal 1.0` last December, we have seen incredible adoption. Our community has grown beyond expectations. We are now approaching **1000+** downloads per week.

Today we're excited to release `next-drupal 1.3`, one of our most important releases.

Next-Drupal 1.3 ships a powerful and flexible JSON:API client for fetching data from Drupal.

It is a replacement for functional helpers such as `getResource` and `getResourceCollection` and provides tons of customizations.

<Callout>

The `DrupalClient` is an optional feature. You can safely upgrade your site to `next-drupal 1.3.0` without any breaking changes.

</Callout>

## Features

1. [Customizable JSON:API client for data fetching](#drupalclient).
2. [Helpers to fetching resources, menus, views and search indices](#data-fetching).
3. [Support for custom auth](#auth) - `Bearer`, `Basic` or bring your own.
4. [Support for custom serializer](#serializer).
5. [Support for custom fetcher](#fetcher).
6. [Support for cached resources](#caching) - memory cache, redis...etc.
7. [Improved error messages](#error-messages)

---

## DrupalClient

<Callout>

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

</Callout>

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

const drupal = new DrupalClient("https://example.com")

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

---

## Data Fetching

Every data fetching helper has been upgraded and made more flexible with options for authentication, localization and caching.

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

// Fetch articles.
const articles = await drupal.getResourceCollection("node--article")

// Fetch articles with translation.
const articles = await drupal.getResourceCollectionFromContext(
  "node--article",
  context
)

// Get static paths for resources.
const paths = await drupal.getStaticPathsFromContext(
  ["node--article", "node--page"],
  context
)

// Make an auth request to fetch a block.
const menu = await drupal.getResource(
  "block_content--basic",
  "42487873-3aad-44ab-8dd6-c2fb0d82bb8f",
  {
    withAuth: true,
  }
)

// Fetch a menu and cache the response during build.
const menu = await drupal.getMenu("main", {
  withCache: process.env.NEXT_PHASE === PHASE_PRODUCTION_BUILD,
  cacheKey: `menu:main`,
})
```

---

## Auth

In addition to Bearer tokens (via Simple OAuth), you can now provide own custom authentication implementation for fetching Drupal data.

### Bearer

To configure authentication, provide a `client_id` and `client_secret` as options.

```ts title=lib/drupal.ts
export const drupal = new DrupalClient(
  process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
  {
    auth: {
      clientId: process.env.DRUPAL_CLIENT_ID,
      clientSecret: process.env.DRUPAL_CLIENT_SECRET,
    },
  }
)
```

`DrupalClient` will fetch **Bearer** token and handle expiration for you.

### Basic

You can also use the basic authorization header as follows:

<Callout icon="⚠️">

You need to enable the `basic_auth` module on Drupal.

</Callout>

```ts title=lib/drupal.ts
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"),
  }
)
```

### Callback

You can also provide a custom callback for authentication. The callback must return an `Authorization` compatible header.

```ts title=lib/drupal.ts
export const drupal = new DrupalClient(
  process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
  {
    auth: () => {
      // Authenticate and return headers.
    },
  }
)
```

---

## Serializer

The `DrupalClient` uses [jsona](https://github.com/olosegres/jsona) as the default serializer for serializing and deserializing JSON:API data.

You can provide your own using the [`serializer`](/docs/client/configuration#serializer) option.

```ts title=lib/drupal.ts
import { Deserializer } from "jsonapi-serializer"

const customSerializer = new Deserializer({
  keyForAttribute: "camelCase",
})

export const drupal = new DrupalClient(
  process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
  {
    serializer: customSerializer,
  }
)
```

---

## Fetcher

You can now provide your own fetcher using the [`fetcher`](/docs/client/configuration#fetcher) option. This replaces Next.js' polyfilled `fetch` for JSON:API calls.

```ts title=lib/drupal.ts
import { DrupalClient } from "next-drupal"
import crossFetch from "cross-fetch"

const fetcher = (url, options) => {
  const { withAuth, ...opts } = options

  if (withAuth) {
    // Make additional requests to fetch a bearer token
    // Or any other Authorization headers.
  }

  return crossFetch(url, {
    ...opts,
    // Pass in additional options. Example: agent.
  })
}

export const drupal = new DrupalClient(
  process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
  {
    fetcher,
  }
)
```

---

## Caching

The `DrupalClient` has support for caching resources. You can provide your own cache implementation using the [`cache`](/docs/client/configuration#cache) option.

Here's an example on how you can use Redis to cache resources.

```ts title=lib/drupal.ts
import { DrupalClient, DataCache } from "next-drupal"
import Redis from "ioredis"

const redis = new Redis(process.env.REDIS_URL)

// Create a custom cache.
export const redisCache: DataCache = {
  async set(key, value) {
    return await redis.set(key, value)
  },

  async get(key) {
    return await redis.get(key)
  },
}

export const drupal = new DrupalClient(
  process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
  {
    cache: redisCache,
  }
)
```

Now when you make a `getResource` or `getMenu` call, you can tell the client to cache and re-use responses.

```ts title=lib/get-menu.ts
import { PHASE_PRODUCTION_BUILD } from "next/constants"

const menu = await drupal.getMenu("main", {
  withCache: process.env.NEXT_PHASE === PHASE_PRODUCTION_BUILD,
  cacheKey: `menu:main`,
})
```

---

## Error Messages

We have improved the error messages from the client with support for formatted JSON:API errors.

<Img
  src="/images/error-message.png"
  alt="Error messages"
  width="700"
  height="465"
/>

## Upgrading

You can try the new `DrupalClient` today by following our upgrade guide [here](/docs/client/upgrade).


Getting Started

NextDrupal Client

Working with JSON:API

Building Pages

Customization

Reference

Drupal

Blog

Next-Drupal 2.0

Next-Drupal 1.6

Next 1.4

Next-Drupal 1.5 and Next 1.3

Next-Drupal 1.4

Next-Drupal 1.3