Edge Cache Purge Library

Previously, purging the edge cache for headless WordPress sites was only possible at the environment level, which meant clearing all cached content indiscriminately at the edge. While this approach ensured that content was refreshed, it also resulted in unnecessary purging of other assets, leading to inefficiencies.

WP Engine now provides a framework-agnostic npm package for purging the edge cache of your headless WordPress site at a granular level with @wpengine/edge-cache. Instead of purging the entire cache, you can execute the following:

• Purge individual pages by specifying their paths
• Purge groups of pages using custom cache tags

This package can be integrated into an API endpoint in your application, allowing selective edge cache purging triggered by various sources, such as WordPress plugins or hooks.

Getting Started

Installation

Install the package using npm

$ npm install --save @wpengine/edge-cache

Package API

View the up to date package API on the npm site: https://www.npmjs.com/package/@wpengine/edge-cache

Purge by Path

The following example will purge the paths /foo and /bar from the edge cache using purgePaths

import { purgePaths } from "@wpengine/edge-cache";

try {
  const paths = ["/foo", "/bar"];
  await purgePaths(paths);
} catch (error) {
  console.error(error);
}

Purge by Tag

Tags must first be added to the pages via the Cache-Tag response header. You can add multiple tags to a single page. For example:

Cache-Tag: foo,bar
Cache-Control: max-age=31536000

Now all pages with any one of the given tags can be purged using purgeTags like so:

import { purgeTags } from "@wpengine/edge-cache";

try {
  const tags = ["foo", "bar"];
  await purgeTags(tags);
} catch (error) {
  console.error(error);
}

Note: While Cache-Tag headers are used internally for cache management, they are not visible in browser network inspections. This is normal and does not affect the purging functionality.

Limitations

Running outside of the Headless Platform

Pages and tags can only be purged while your app is running on our platform. If your code is running locally or on another platform, a message will be logged instead.

Supported versions of npm and Node.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.

Functional Limitations

1. A maximum of 30 tags can be purged at once.
2. Edge cache purging is subject to rate limiting. Each environment is allocated 300 purge operations per hour. This limit may be adjusted in the future based on usage patterns. Note that purging multiple paths in a single API call counts as one operation against this limit.
3. Wildcards and other operators are not supported. If you require multiple paths to be purged, you must first add cache tags to the pages and then purge by tag.
4. This package only purges the Node.js edge cache, not the WordPress edge cache.

Note: Due to the rate limiting, it is recommended that you add authentication for the edge cache to be purged.

Debugging

To debug, add the HEADLESS_EDGE_CACHE_DEBUG=true environment variable and rebuild your environment - the following logs will be output:

EdgeCache: DEBUG: Purged edge cache for paths: (...)