Upgrade Guide

Guide for upgrading your site to use DrupalClient.

next-drupal 2.0.0

  1. Upgrade to the latest version
yarn add next-drupal@latest

next-drupal 2.0.0 adds support for the App Router and maintains support for the Pages Router. For information on transitioning from the Pages Router to the App Router, see the App Router Incremental Adoption Guide guide on the Next.js site.

TODO - Outline breaking changes here.

next 2.0.0

  1. Upgrade your Drupal site to use next 2.0.0
composer require drupal/next
  1. Run updates:
drush updb

TODO - Describe changes as that will occur as a result of this upgrade.

next-drupal 1.6.0

  1. Upgrade to the latest version
yarn add next-drupal@latest

next-drupal 1.6.0 adds support for Next.js 13 and React 18. To update your site to Next.js 13, see the Upgrading from 12 to 13 guide on the Next.js site.

next 1.6.0

  1. Upgrade your Drupal site to use next 1.6.0
composer require drupal/next
  1. Run updates:
drush updb

Running the updates will migrate the legacy next_extras on-demand revalidation configuration to entity type config.

next 1.3.0

  1. Upgrade your Drupal site to use next 1.3.0
composer require drupal/next
  1. Run updates:
drush updb

  1. Edit the Next.js user and assign them all the roles that are going to be used for scopes, including the administrator role and the Next.js role. The granted roles will be filtered based on roles assigned to the current user.

  2. Upgrade the next-drupal package to 1.5.0. See the upgrade guide below.

next-drupal 1.5.0

  1. Upgrade to the latest version
yarn add next-drupal@latest

next-drupal 1.4.0

⚠️

The DrupalClient is an optional feature. If you're running a site using next-drupal 1.2 or below, you can safely upgrade your site without any breaking changes.

  1. Upgrade to the latest version
yarn add next-drupal@latest
  1. Create a new DrupalClient in lib/drupal.ts

lib/drupal.ts

import { DrupalClient } from "next-drupal"


export const drupal = new DrupalClient(
  process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
  {
    frontPage: "/home",
    auth: {
      clientId: process.env.DRUPAL_CLIENT_ID,
      clientSecret: process.env.DRUPAL_CLIENT_SECRET,
    },
  }
)

By default, all requests made to Drupal by DrupalClient are un-authenticated. See Step 5 below on how to configure permissions for un-authenticated calls.

To make authenticated requests, you opt-in on a method-basis.

If you want to have all requests authenticated, you can use the withAuth option on the DrupalClient:

import { DrupalClient } from "next-drupal"


export const drupal = new DrupalClient(
  process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
  {
    frontPage: "/home",
    auth: {
      clientId: process.env.DRUPAL_CLIENT_ID,
      clientSecret: process.env.DRUPAL_CLIENT_SECRET,
    },
    withAuth: true,
  }
)
  1. Update helpers to use the drupal client.
+ import { drupal } from "lib/drupal"


- await getPathsFromContext()
+ await drupal.getStaticPathsFromContext()


- await translatePathFromContext()
+ await drupal.translatePathFromContext()


- await getResourceFromContext()
+ await drupal.getResourceFromContext()
  1. Replace pages/api/preview.ts with the following:
- import { DrupalPreview } from "next-drupal"
-
- export default DrupalPreview()
+ import { drupal } from "lib/drupal"
+
+ export default async function (request, response) {
+  return await drupal.preview(request, response)
+ }

  1. On the Drupal site, visit /admin/people/permissions/anonymous and assign the Issue subrequests permission to the Anonymous user role:

    We do this because during the build phase, most of the requests for pages are anonymous requests. By assigning this permission, you can significantly decrease your site's build time.

    If you would rather keep requests authenticated, you can use the withAuth options.

  2. Done. You are now ready to run your site using the new DrupalClient.

If you see any bugs during the upgrade, feel free to create an issue on GitHub.

Frequenty Asked QuestionsKnown Issues