--- title: "Next.js for Acquia CMS Headless Starter Kit" date: "2022-07-08T23:16:47+00:00" summary: image: type: "article" url: "/acquia-cloud-platform/help/91296-nextjs-acquia-cms-headless-starter-kit" id: "3dd07c10-1993-4051-bbc6-1bc18f6d1486" --- Table of contents will be added Goal ---- In this tutorial, you’ll connect your existing Acquia CMS Headless Starter Kit from the first tutorial to the Next.js for Acquia CMS Starter Kit. Prerequisites ------------- * A local machine where you have (or can install) node version 16.x or later * An existing installation of Acquia CMS Headless Starter Kit. See [first tutorial on settings up Acquia CMS](/tutorial/nextjs-acquia-setting-acquia-cms). * We recommend installing the Acquia CMS Starter Kit demo content so you can see content in your Next.js site. Overview -------- At Acquia, we’re creating a better developer experience for headless CMS. ------------------------------------------------------------------------- We’ve partnered with [Chapter 3](https://www.chapterthree.com/), maintainers of [Next.js for Drupal](https://next-drupal.org/), to build [Next.js for Acquia CMS](https://github.com/acquia/next-acms): a Next.js starter kit for the [Acquia CMS Headless Starter Kit for Drupal](https://www.acquia.com/products/drupal-cloud/acquia-cms). This is the second of three tutorials on using Next.js optimized for the Acquia CMS Starter Kit. Next.js is a framework built on top of React.js, with great support, stability, performance and security features. With [next-acms](https://github.com/acquia/next-acms) you get an out-of-the-box Next application that connects easily to the Acquia CMS Starter Kit default content model. Try it out yourself! Here is a guide on how to get a local Next application quickly connected to Acquia CMS. In this tutorial, you’ll connect your existing Acquia CMS Headless Starter Kit from the first tutorial to the Next.js Starter Kit. Specifically, we will: * Set up a local Next.js Starter Kit optimized for Acquia CMS Starter Kit * Configure Next.js to use a JSON:API endpoint of your Acquia CMS Starter Kit installation 1. Create the project ------------------ We’ll start by creating our codebase: npx create-next-app -e https://github.com/acquia/next-acms/tree/main/starters/basic-starter 2. Setup your local machine ------------------------ To use the starter kit locally, you’re going to need npm ([Node Package Manager)](https://www.npmjs.com/) which will give you a Node.js engine (node) and npx ([node package execute](https://www.npmjs.com/package/npx)). 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 Using Ubuntu: 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 serverdocker run -it --rm -v $PWD:/usr/src/app -w /usr/src/app -p 3000:3000 node:16 npm run dev# Build a production artifactdocker run -it --rm -v $PWD:/usr/src/app -w /usr/src/app node:16 npm run build# Run the production serverdocker 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/](http://localhost:3000/) on your local machine and connect to your node container. 3. Install Node packages --------------------- npm install 4. Connect Drupal -------------- To connect the Next.js site to your Acquia ACMS Starter Kit instance, we’ll pre-populate the Next.js for Drupal [environment variables](https://next-drupal.org/docs/environment-variables). These variables can be obtained from your site install through a handy Next.js starter kit built into Acquia CMS Headless Starter Kit. On your Acquia CMS site, visit **Tour > Get Started** and view the Headless section and enable the **Next.js starter kit**. ![CMS dashboard interface showing configuration options for enabling Next.js starter kit and Headless mode with save and ignore buttons.](https://acquia.widen.net/content/691b085b-056d-4c24-ae68-1529b0c436a6/web/url_041c6333fbe219543f3ab0a5bfcd66ed.png) This will setup all you need in Drupal to connect with your Next.js app. Once saved, you'll see a status message with the Environment Variables for your Next.js site: ![CMS Dashboard displaying a status message with environment variables for a Next.js application setup.](https://acquia.widen.net/content/8046c496-6684-4711-b64f-dff7cae67279/web/url_ce5a8122612657c41a2b69925e7011b5.png) Now, back in your Next.js application, copy .env.example to .env.local cp .env.example .env.local Then, change the contents of .env.local to the Environment Variables specified in Next.js site. Here is what these environment variables are doing: **Variable** **Purpose** NEXT\_PUBLIC\_DRUPAL\_BASE\_URL Where the Drupal instance lives. Required by Next.js. NEXT\_IMAGE\_DOMAIN The domain to pull Drupal images from. Required by Next.js. DRUPAL\_FRONT\_PAGE Helps Next.js for Drupal manage frontpage paths. DRUPAL\_CLIENT\_ID Drupal consumer UUID that grants access for the Next.js app. DRUPAL\_CLIENT\_SECRET Drupal consumer secret for the given DRUPAL\_CLIENT\_ID. The consumer UUID can be found at **Administration > Configuration > Web services > Consumer** **entities** ![Web interface showing "Consumer entities" with UUIDs and labels for "Headless Site" and "DrupalCon Headless Site Consumer."](https://acquia.widen.net/content/ae719f9b-cce5-477a-9a9d-3bf0b153e402/web/url_f787720d095d842b1e1405e2874d1bbf.png) The consumer secret is stored as an encrypted value in Drupal and cannot be retrieved so you must recall it from when it was set. If not, you can edit the Consumer and set a new secret. 5. Start Development Server ------------------------ To start the Next.js development server, run: npm run dev This starts the development server on [http://localhost:3000](http://localhost:3000). ![Terminal window showing a development server running, with information on server start, environment, and telemetry details for Next.js.](https://acquia.widen.net/content/854b2551-d524-49a9-8f3b-b85056513a63/web/url_269a87dda940748949ab08765eea02a3.png) Visit [http://localhost:3000](http://localhost:3000/) to view the headless site. ![Webpage listing two placeholder events with headings, dates, and descriptive text under "Events" section in Acquia CMS.](https://acquia.widen.net/content/aa9dc9e4-a3fc-4574-8e1b-f9d82fc1a50e/web/url_ea6ab99ae98ae61ecf68502f75c3c3be.png) 6. Let's run things faster. Much faster. ------------------------------------- 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 # Or run: npm run preview Notice that during the build process, Next.js is fetching data from Drupal 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! ![Terminal output displaying a Next.js build process with various logs, including page generation times and file sizes.](https://acquia.widen.net/content/8de12b09-7120-42bb-a1f2-bbb390fb4cd8/web/url_94d0e8a9c008d369018f389428bacc4a.png) ### 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)](https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration). 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 Drupal 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. 7. Customizing content types ------------------------- The next step in this Next.js tutorial series is learning how to create new content types in Drupal and surface them up through Next.js. [Customizing content types](/tutorial/nextjs-acquia-customizing-content-types) Hosting Next.js --------------- A big pain point of javascript applications is time-to-meaningful-paint. That’s the time it takes in the browser for a javascript application to show something that’s meaningful and interactive to the end user. That’s because the experience is dependent on the resources of the visitor’s device which also has to wait for all the dependencies to download. Hosting compatible JavaScript frameworks, like Next.js, serverside, allows you to pre-render JavaScript applications meaning the client browser can focus on painting immediately. This is what makes the production build in Next.js so fast. At Acquia [we host and support Node.js applications](https://www.acquia.com/blog/announcing-nodejs-acquia-cloud) (like Next.js) optimized for working with a content backend API built on Drupal. If you’re interested to find out more, [get in touch with one of our team](https://www.acquia.com/about-us/contact/request-a-demo). Additional Resources -------------------- * [Next.js on Acquia: Setting up the Acquia CMS Headless Starter Kit](/tutorial/nextjs-acquia-setting-acquia-cms) * [Next.js on Acquia: Customizing content types](/tutorial/nextjs-acquia-customizing-content-types) * [Acquia CMS Starter Kits on Github](https://github.com/acquia/acquia_cms) * [Next.js for Acquia CMS starter kit](https://github.com/acquia/next-acms) * [Acquia CMS Headless Starter Kit Documentation](/node/56700)