Skip to content
Atlas Platform

Next.js Framework Guide


Next.js is the most popular open source React-based framework. It allows developers to use all the features you need for production in a front-end framework: hybrid static & server rendering, TypeScript support, smart bundling, route pre-fetching, and more. No config needed. Check out their documentation for guides to all these key features.

Deploy Steps

To get started, you can run the following command to create a new Next.js project and then follow the steps in their automatic setup guide:

npx create-next-app@latest

*This guide is for the legacy Next.js 12 Pages Router. When you pull down the Next.js package with @latest, you will be prompted to choose what version you want to use in the CLI. You can select “No” when asked if you want to use the App Router and this will tell Next that you want to use the Pages Router.*

Or, if you want to start with a template designed specifically for headless WordPress, you can clone one of these starter templates:

git clone

git clone

git clone

Push Initial Commits to Your Repository

To deploy your project to Atlas, it will need to be available on a remote GitHub or Bitbucket repository. The Next.js installation process lets us initialize a local repository for the project.

Create a new remote repository, and then run the following commands to initialize and configure your local and remote repositories:

# Add remote repository
$ git remote add origin https://<your-git-provider>/<username>/<repo>

# Stage all changed files
$ git add -A

# Commit the files to the current branch
$ git commit -m "initial commit"

# Push changes to remote repository
$ git push -u origin main

Build Details

Atlas detects that it is a Next.js app and runs the build scripts and configs necessary for the build details.

One thing to note is the next/cache folder within your Next.js project. Atlas caches common framework assets between builds to optimize build times. The build step will not override the folder.

Deploy Your Repository

Once your project is in your repository, you can follow the directions in our getting started guide to deploy your project to Atlas.

Best Practices

Next Image

The Next.js Image component, next/image, is an extension of the HTML <img> element, evolved for the modern web. It includes a variety of built-in performance optimizations to help you achieve good Core Web Vitals.

One thing to keep in mind is when switching over your domains on Atlas, you must declare them in the next.js.config file, otherwise the images will not render. Please reference Next Image Docs for guidance.

Known Limitations

Incremental Static Regeneration

Incremental Static Regeneration is supported in Atlas through the @wpengine/atlas-next package (see documentation ).

While our Node infrastructure will support path-based (on-demand) revalidation of the primary Next.js instance, this revalidation will currently not extend to edge cached versions of that path, nor will they apply to all instances of your application if it has scaled beyond a single instance.

Providing support for path-based on-demand ISR is under active investigation by our engineering team. If you need to perform a clean rebuild of your website, you can use the Clean Rebuild webhook or initiate one through the user portal. You can also use the Purge Cache webhook to programmatically clear your CDN cache (read more about how to create and use webhooks in our documentation)

Edge Runtime/Middleware

Because Atlas does not rely on serverless functions/edge functions, such functionality currently runs on the origin Node server. It is important to note that this means that such functions will run only on requests that terminate at the origin; any requests served from the edge will continue to serve whatever response is cached at the edge for that path.

The Next.js documentation has more in-depth details on framework features.

Next.js 14

Next.js 14 is a React framework for building full-stack web applications. It uses React Server Components to build user interfaces, while providing additional features and optimizations. In Next.js 14, the App Router is introduced as the new folder and routing structure. However, a limitation is that Atlas does not currently support its full range of functionality and features.

Was this page helpful?
👍 Yes  |  👎 No