Skip to content
Headless Platform
GitHubDiscordYouTube

Next.js ISR support

This manual provides instructions for utilizing Next.js Incremental Static Regeneration on our Headless Platform.

Overview

Headless Platform now offers beta support for Next.js Incremental Static Regeneration, including On-Demand ISR. This feature allows you to update static content without rebuilding your entire site, significantly improving performance and reducing build times for your Next.js or Faust.js projects.

To enable this functionality, you’ll need to install and configure the @wpengine/atlas-next npm package in your project.

Note that this beta release has some limitations, including specific version requirements and incompatibility with certain Next.js features like the App Router and rewrites.

Quick start

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

Install @wpengine/atlas-next

To install the @wpengine/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);

Using Faust.js

If you are using Faust.js and you intend to use it with On-Demand ISR, please note that you need to update your Next.js to a minimum of 13.5.1 and React versions to 18.3.1 for this feature to work in Faust. The npx utility command that pulls down the Faust.js boilerplate from the Faust docs comes with Next.js 12 by default. Please change this if using that package.

For regular ISR, it will work with the Faust.js boilerplate package from the docs that come with Next.js version 12 by default.

Once you have made sure your versions are correct, 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:

Our Headless Platform 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 a Headless Platform environment, this will automatically trigger a rebuild.

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

Headless Platform remote cache handler enabled

On-demand Incremental Static Regeneration

On-Demand Incremental Static Regeneration is a feature in Next.js that allows you to manually trigger the revalidation of static pages based on specific events. This ensures that your static pages are updated with the latest content without the need for a full site rebuild.

To create an API route for revalidation and configure it with WordPress to ensure your static pages reflect the latest content updates, follow the below instructions.

Create an API route

This API route will allow you to pass the path to be revalidated as a parameter:

  1. Create the API route file: Navigate to the pages/api directory in your Next.js project and create a new file named revalidate.js.
  2. Add the API Route code: Open revalidate.js and add the following code:
export default async function handler(req, res) {
  // Check for a secret token to authenticate the request
  if (req.query.secret !== process.env.MY_SECRET_TOKEN) {
    return res.status(401).json({ message: "Invalid token" });
  }

  const path = req.query.path;

  // Ensure the path parameter is provided
  if (!path) {
    return res
      .status(400)
      .json({ message: "Path query parameter is required" });
  }

  try {
    // Revalidate the specified path
    await res.revalidate(path);
    return res.json({ revalidated: true });
  } catch (err) {
    return res
      .status(500)
      .json({ message: "Error revalidating", error: err.message });
  }
}
  1. Configure the environment variables: Create a .env.local file in the root of your project if it doesn’t exist and add your secret token. This code sets up an API route that checks for a secret token for security, validates the presence of the path parameter, and triggers the revalidation of the specified path.:
MY_SECRET_TOKEN=your-secret-token

Use the API route to configure cache revalidation

To configure cache revalidation in the headless WordPress setup, you could follow one of the approaches below:

  1. Use a webhook plugin: You can use plugins like WP Webhooks to enable webhook functionality and trigger the API endpoint you’ve just created when relevant events occur, such as when a post is published or updated.
  2. Set up WordPress hooks: You can also add actions in your WordPress theme or plugin to send requests to your Next.js API route. Here’s an example using the wp_remote_post function, which will send a POST request to the Next.js API route whenever a post is saved in WordPress, triggering the revalidation of the corresponding path:
function trigger_revalidation($post_id) {
  $url = 'https://your-nextjs-site.com/api/revalidate?secret=your-secret-token&path=' . get_permalink($post_id);

  $response = wp_remote_post($url);

  if (is_wp_error($response)) {
    error_log('Error triggering revalidation: ' . $response->get_error_message());
  }
}
add_action('save_post', 'trigger_revalidation');

Limitations of the beta release

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 Headless 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 our Headless Platform. You can check the currently supported versions here.

Supported Next.js versions

The @wpengine/atlas-next package requires a minimum Next.js version of v12.2.0. On-demand ISR requires Next.js version v13.5.1 or higher.

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

Next.js 15 breaking change:

Please note that Next.js version 15 introduces changes that break the support for On-Demand ISR (ODISR) on our headless platform. We recommend that you refrain from updating to Next.js 15 until further support is provided. The Headless Platform team is actively working on resolving this issue and will update the documentation once a fix is in place.

Functional limitations

At the moment, Atlas supports On-Demand ISR with the following limitations:

  1. Requires @wpengine/atlas-next package: To enable On-Demand ISR on Atlas, you must use the @wpenngine/atlas-next package and follow the setup steps outlined in the previous sections of this document.
  2. On-demand ISR for App Router is not supported: The App Router is a new routing system in Next.js that enhances routing capabilities with features like server components and nested layouts. However, Atlas currently supports On-Demand ISR only in the context of the traditional Pages Router. This means that methods like revalidatePath and revalidateTag, which are used for revalidation in the App Router, are not compatible with Atlas’ ISR mechanism. For more details on the App Router and its data fetching methods, you can refer to the Next.js documentation here.
  3. Rewrites are not supported: Rewrites in Next.js allow you to change the destination URL of a request without altering the URL visible to the user. However, On-Demand ISR on Atlas does not support rewrites. This means that if your Next.js application relies on rewrites, the On-Demand ISR feature might not function as expected. You can learn more about rewrites here.
  4. Not compatible with Next.js I18N: Since Next.js uses rewrites for internationalization, this feature is not supported on Atlas due to the rewrite limitation mentioned above.
  5. Next.js >=13.5 is required: To be able to use this feature, you need to update your application to Next.js version 13.5 or higher.

Note: Redirects (which, unlike rewrites, actually change the URL in the user’s browser to the specified destination) are supported.

Feedback and product updates

Important updates about new releases to this feature will be posted in the WP Engine Headless Platform 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 support team.