Hello World: Next.js for Acquia CMS @ Drupalcon Portland
At Acquia, we’re creating a better developer experience for headless CMS.
With next-acms you get an out-of-the-box Next application that connects easily to the Acquia CMS default content model. Try it out yourself! Here is a guide on how to get a local Next application quickly connected to Acquia CMS.
Note: This is currently an alpha stability product that is not yet formally supported by Acquia. We will be making a stable release soon!
In this tutorial, you won’t set up a new Drupal site–you’ll use ours. This way you can focus on playing around exclusively with the Next.js starter kit.
Specifically, we will:
Set up a local Next.js starter kit for Acquia CMS
Configure Next.js to use a JSON:API endpoint powered by Acquia CMS and hosted on Acquia Cloud Next.
A local machine where you have (or can install) node version 16.x (17.x will work too).
To use the starter kit locally, you’re going to need npm (Node Package Manager) which will give you a Node.js engine (node) and npx (node package execute). If you already have it installed, go ahead and skip to the next step.
Option 1: Install Node directly to your local machine
Using Homebrew on Mac:
brew install npm
apt-get install npm
Now skip ahead to the “Install Node Packages” section.
Option 2: Use Docker
If you don’t want to run Node locally and prefer to keep things in a Docker container, then this section is for you!
With next-acms cloned on your host machine, you can now mount it to a standard node container to interact with it. Keeping the container ephemeral, the docker commands below spin containers up and down for each command:
# Install node dependencies.
docker run -it --rm -v $PWD:/usr/src/app -w /usr/src/app node:16 npm install
# Run the development server
docker run -it --rm -v $PWD:/usr/src/app -w /usr/src/app -p 3000:3000 node:16 npm run dev
# Build a production artifact
docker run -it --rm -v $PWD:/usr/src/app -w /usr/src/app node:16 npm run build
# Run the production server
docker run -it --rm -v $PWD:/usr/src/app -w /usr/src/app -p 3000:3000 node:16 npm run start
The docker commands here also connect port 3000 on your host machine to the docker instance. So from either `run dev` or `run start` you’ll be able to visit http://localhost:3000/ on your local machine and connect to your node container.
Install Node packages
To connect the Next.js site to our hosted Acquia ACMS instance, we’ll pre-populate the Next.js for Drupal environment variables.
Copy .env.example to .env.local
cp .env.example .env.local
Then, change the contents of .env.local to the following:
When running a development server, node is listening for changes to the codebase and reloading the server to reflect those changes. It’s also not caching anything as that can get in the way of development.
If you want to run things faster, you need a production build. While the development server builds and runs the application at the same time, production runtime is a two phase process:
npm run build
npm run start
Notice that during the build process, Next.js is fetching data from Acquia CMS and building static versions of the site. Then when you run that build, Next.js is loading those static pages directly from your filesystem making the performance lightning fast!
This two step process can be done with a single command
npm run preview
What about content updates in Drupal?
By default, next-acms will serve cached content, but after 15 minutes, the next request will revalidate the content with Drupal and update/sync it into Next.js using Incremental Site Regeneration (ISR). We configure next-acms to wait for the response from Drupal to ensure fresh content is sent instead of stale cached content.
Outside of this Hello World example, you can also configure Acquia CMS to notify Next.js of content events enabling event driven revalidation. In this mode, content is out-of-sync for only a second or so. We'll cover this in future blog posts or tutorials on dev.acquia.com.