Next.js on Acquia: Setting up Acquia CMS

Last updated April 24, 2022
1 minute read

Goal

Setup Acquia CMS for working with the Next.js

Prerequisites

You should have a local Drupal development environment (e.g. brew or lando/ddev/docksal)
Composer should be installed

Overview

This is the first in a 3 part tutorial series in how to get started with Next.js and Acquia CMS. Next.js is an adaptable JavaScript framework, built on top of React.js, with great support, stability, performance and security features. We partnered with Chapter 3, maintainers of Next.js for Drupal, to build Next.js for Acquia CMS: a Next.js starter kit for Acquia CMS.

This tutorial will show you how to set Acquia CMS to work with our starter kit

Acquia CMS Headless is coming

We're currently working on an Acquia CMS build specifically for headless architectures. This tutorial contains a number of steps we'll be automating in future.

Create Acquia CMS project
Start by creating a new Acquia CMS project:

(If you have an existing Acquia CMS project, you can skip this step)
```
composer create-project --no-interaction acquia/drupal-recommended-project acms-headless
cd acms-headless
drush site-install
```
Next.js for Drupal documents two patches that should also be applied to the Subrequests and Decoupled Router also.
Add and enable modules
Enabling these three modules will also enable a number of dependencies you'll need to headless interactions with Next.js.
```
composer require drupal/next drupal/jsonapi_menu_items
drush en next_jsonapi jsonapi_menu_items next_extras -y
```
If you don't use Drush, you can turn these modules on from the Extend section of the Drupal UI Administration.
Add starter content
The next.js starter kit comes with built-in support for Acquia CMS's default content model for Page, Article, Event, Person and Place. Installing the Acquia CMS Starter module will install those content types into your Drupal site and add demo/dummy content that you'll be able to pull across into Next.js in a later tutorial.
```
drush en -y acquia_cms_starter
```
Remove Site Studio fields

Unless you have Acquia Site Studio keys configured in your Acquia CMS install, the Page content type will not work. To resolve this, go to /admin/structure/types/manage/page/fields and remove the Site Studio canvas field.
Create Role and User
To pull data from the Drupal back-end, the Next.js front-end requires authorization. To handle this, we are going to create a role.
1. Create a role (example Next.js site with Preview) at /admin/people/roles with the following permissions:
- Bypass content access control
- Issue subrequests
- View user information
1. Add a new user at /admin/people/create and assign it the role we created above.
We are assigning the Bypass content access control permission to allow Next.js to access unpublished content and revisions.

You can safely skip this permission if you do not need to preview unpublished content.
Configure Simple OAuth module
1. Visit /admin/config/people/simple_oauth
2. Click Generate keys to generate encryption keys for tokens
3. Fill in Directory for the keys.
4. Click Generate.
Create OAuth Client
1. Visit /admin/config/services/consumer/add
2. Fill in the following values:
Label Next.js site
User <Select the user we created>
Secret <Your secret>
Scopes <Select the next.js role created>
1. Click Save
Create Next.js site
1. Visit /admin/config/services/next
2. Click Add Next.js site
3. Fill in the following values:
- Label: Blog
- Base URL: http://localhost:3000
- Preview URL: http://localhost:3000/api/preview
- Preview Secret: preview-secret-here
1. Click Save
localhost:3000 is the default port Next.js will spin up on. If you're customising this in your next.js app later, be sure to update that here too.