@riveo/payload-purge-cache-plugin

Payload Purge Cache plugin

A plugin for PayloadCMS that integrates cache purging functionalities directly into the admin panel, allowing administrators to efficiently manage and clear cached content across various platforms.

Features

• 🧹 One-click cache purge from the admin panel
• 🔧 Pluggable purgers, with built-in support for Cloudflare, Next.js and raw HTTP request
• 🔐 Optional access control
• ✅ Status feedback for every purge attempt

Installation

npm install @riveo/payload-purge-cache-plugin

Then register it in your payload.config.ts:

import purgeCachePlugin from '@riveo/payload-purge-cache-plugin';
import { getNextjsPurgerAction } from '@riveo/payload-purge-cache-plugin/purgers';

export const config = buildConfig({
  plugins: [
    purgeCachePlugin({
      purgers: [
        {
          label: 'NextJS',
          action: getNextjsPurgerAction(),
          default: true,
        },
      ],
    }),
  ],
});

Configuration

The plugin accepts an object with the following properties:

• enabled: boolean: Enable or disable the plugin. Default is true.
• path?: string: URL path for the admin page. Default is /riveo-purge-cache.
• access?: AccessCallback: Optional function to control access permissions.
• purgers: Purger[]: Array of purger configurations to be triggered on cache purge.

Example configuration:

purgeCachePlugin({
  enabled: true,
  path: '/custom-purge-cache',
  access: ({ req }) => req.user.role === 'admin',
  purgers: [
    {
      label: 'Next.js',
      action: getNextjsPurgerAction(),
      default: false,
    },
  ],
});

Built in purgers

Cloudflare

Purges Cloudflare cache for specified zone.

Usage: getCloudflarePurgerAction({ apiKey, zoneId })

Parameters:

• options
  • apiKey: string - Cloudflare API key
  • zoneId: string - ZoneID to purge cache for
  • hosts?: string[] - Optional list of hosts to purge
  • tags?: string[] - Optional list of tags to purge
  • prefixes?: string[] - Optional list of prefixes to purge. A prefix has to include hostname but not scheme e.g.: example.com/prefix
  • files?: string[] - Optional list of specific urls to purge. An url has to include scheme, hostname and path e.g.: https://example.com/full/path

Next.js

Purges internal Next.js cache. Internally it calls revalidatePath(basePath, 'layout') (Revalidating All Data - Next.js docs)

Usage: getNextjsPurgerAction('/')

Parameters:

• basePath: string [dafault: '/'] - base path to invalidate cache for. It defaults to /

HTTP

Calls specified HTTP endpoint using fetch. Useful when your app is separate from PayloadCMS instance and exposes an endpoint to clear the cache.

Usage: getHttpPurgerAction(endpoint, options)

Parameters:

• endpoint: RequestInfo
• options?: RequestInit

Usage

After setting it up:

• Go to your PayloadCMS admin panel.
• Click on the “Purge Cache” tab in the sidebar.
• Click the button to run all purgers.
• View real-time results for each purger.

Contributing

We welcome contributions! To contribute:

• Fork the Repository: Click the 'Fork' button at the top right of the repository page.
• Clone Your Fork: Clone your forked repository to your local machine.
• Create a Branch: Create a new branch for your feature or bugfix.
• Make Your Changes: Implement your changes and commit them with clear messages.
• Push to GitHub: Push your changes to your fork on GitHub.
• Submit a Pull Request: Open a pull request to the main repository.

License

This project is licensed under the MIT License.