Next.js on Acquia: Setting up Acquia CMS

  • Last updated
  • 1 minute read


Setup Acquia CMS for working with the Next.js


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

  • Composer should be installed


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.

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

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

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

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

  5. 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.
  6. 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
  7. 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.

Congratulations 🎉

You now have an Acquia CMS instance ready for integration with Next.js. So what's next?

Continue the tutorial series and checkout how to setup the Next.js starter kit.