Skip to content
Atlas Platform
GitHubDiscordYouTube

Next.js ISR support on Atlas

This manual provides instructions for utilizing the latest enhancement of the Atlas platform: support for Next.js Incremental Static Regeneration.

Overview

In most cases, Next.js Incremental Static Regeneration (ISR) works as expected on Atlas - however, there are two issues:

  1. Traffic Spikes: When traffic spikes, new replicas of the application are spawned. These replicas mirror the version of the application that was originally built, which includes statically generated content that may now be outdated.
  2. Low Traffic Periods: Conversely, if a site receives no traffic for an extended period, the application scales down. When traffic picks up again, the initial visitors encounter this outdated content. This content isn’t cached; instead, it initiates a background revalidation process. After this process is complete, any subsequent requests will receive the freshly updated content, which is then cached.

Our solution for ISR support effectively addresses both issues, ensuring your site always displays the most recent content, regardless of traffic patterns. If your sites use Next.js Incremental Static Regeneration, we recommend completing the steps described below.

Quick start

To start using the feature, please follow the steps outlined below.

Note: We recommend beginning your testing on non-production environments - this approach allows you to familiarize yourself with the feature’s functionality and iron out any potential issues in a controlled setting before rolling out changes to your live environment.

Install @wpengine/atlas-next package

To install the atlas-next package, run:

$ npm install --save @wpengine/atlas-next

Modify your next.config.js file

Edit your next.config.js file to activate the new feature:

const { withAtlasConfig } = require("@wpengine/atlas-next")

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Your existing Next.js config
}

module.exports = withAtlasConfig(nextConfig)

Note: If you’re using Faust.js, make sure to modify your next.config.js file using the withFaust wrapper:

const { withFaust } = require("@faustwp/core")
const { withAtlasConfig } = require("@wpengine/atlas-next")

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Your existing Next.js config
}

module.exports = withFaust(withAtlasConfig(nextConfig))

Verify it’s working

Run your application locally and check your runtime logs. You should see the following message:

Atlas remote cache handler enabled (local storage mode)

Push your changes live

After ensuring your local setup works as expected, it’s time to deploy your changes. Commit your changes to your local repository using git commit and push them to your remote branch with git push. If this branch is connected to an Atlas environment, this will automatically trigger a rebuild.

Once the rebuild is complete, navigate to the Runtime logs tab of your Atlas environment dashboard. Verify the successful deployment by looking for the following line:

Atlas remote cache handler enabled

Limitations

This feature is currently in the Beta phase, which entails:

  1. Functional completeness, offering comprehensive support for Next.js Incremental Static Regeneration.
  2. Ongoing assessment by Atlas Platform teams regarding the feature’s effect on website performance and application scalability.

Supported versions of npm, Node.js and Next.js

Make sure you’re using versions of npm and Node.js that are supported by the Atlas platform. You can check the currently supported versions here.

The atlas-next package requires a minimum Next.js version of v12.2.0

Next.js versions >= 13.4.13 < 13.5.1 are not supported due to a bug in Next.js.

FAQ

  1. Does Atlas support on-demand Incremental Static Regeneration now?

Currently, on-demand ISR is not supported on Atlas. However, our team is actively working on adding this feature to our platform. Once it’s available, the use of the atlas-next package will be required to enable on-demand ISR on Atlas.

Feedback and product updates

Important updates about new releases to this feature will be posted in the WP Engine Atlas Changelog.

Should you have any feedback, please submit it using the our feedback form (make sure to include your account name in the issue description) or reach out to the WP Engine Atlas support team.