---
title: Next.js ISR support
description: Guide for leveraging Next.js Incremental Static Regeneration on the WP Engine Headless Platform
url: https://developers.wpengine.com/docs/headless-platform/framework-guides/next-js/nextjs-isr-support/
image: https://developers.wpengine.com/og/docs/headless-platform/framework-guides/next-js/nextjs-isr-support.png
---

# Next.js ISR support

The Headless Platform offers 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**
>
> This release has some [limitations](https://developers.wpengine.com/docs/headless-platform/framework-guides/next-js/nextjs-isr-support/#functional-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](https://www.npmjs.com/package/@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:

```javascript
const { withWPEConfig } = require('@wpengine/atlas-next');


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


module.exports = withWPEConfig(nextConfig);
```

**Using Faust.js**

Once you have made sure your versions are correct, modify your `next.config.js` file using the `withFaust` wrapper:

```javascript
const { withFaust } = require('@faustwp/core');
const { withWPEConfig } = require('@wpengine/atlas-next');


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


module.exports = withFaust(withWPEConfig(nextConfig));
```

### Verify it’s working

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

```javascript
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:

```javascript
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:

```javascript
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 });
  }
}
```

3. **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:

```php
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');
```

### 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](https://developers.wpengine.com/docs/headless-platform/platform-guides/customizing-builds/#nodejs).

### Supported Next.js versions

- Next.js `>=v15.2.1` - require `@wpengine/atlas-next` `>=3.0.0`
- Next.js `>=v15.0.0` to `<=v15.2.1` - require `@wpengine/atlas-next` `>=2.0.0 <3.0.0`
- Next.js `>=v12.2.0` to `<v15.0.0` - require `@wpengine/atlas-next` `<2.0.0`

### Functional limitations

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

1. **Requires `@wpengine/atlas-next@>=13.15.1` package**: To enable On-Demand ISR on the Headless Platform, you must use the `@wpengine/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](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating).
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](https://nextjs.org/docs/pages/api-reference/next-config-js/rewrites).
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.1` is required**: To be able to use On-Demand ISR, you need to update your application to Next.js version 13.5.1 or higher.

> **Note**
>
> [Redirects](https://nextjs.org/docs/pages/api-reference/next-config-js/redirects) (which, unlike rewrites, actually change the URL in the user’s browser to the specified destination) are supported.

## Was this helpful?

Thanks for the feedback!

```json
{"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]}
```