payload-smart-cache

payload-smart-cache

Intelligent, dependency-aware cache invalidation for Next.js + Payload CMS applications.

Overview

payload-smart-cache tracks document changes in a publish queue and builds a dependency graph from your collection relationships. When you publish, it walks the graph and revalidates all affected Next.js cache tags — including indirectly related documents. A publish button in the admin UI shows when unpublished changes exist.

Features

• Deferred publishing — changes are queued and only pushed to the cache when you explicitly publish.
• Dependency graph — automatically discovers relationships between collections, so changing a referenced document revalidates its dependents.
• Tag-based revalidation — precise, granular cache invalidation via Next.js revalidateTag().
• Request caching utility — createRequestHandler wraps data-fetching functions with entity-level cache tags for automatic revalidation.

Installation

pnpm add payload-smart-cache

Usage

Important: smartCachePlugin scans collection and global fields at config time to auto-discover referenced collections. It must be listed after any plugin that registers collections or injects relationship fields, so those are visible during the scan.

// payload.config.ts
import { buildConfig } from "payload";
import { discussionsPlugin } from "payload-discussions";
import { smartCachePlugin } from "payload-smart-cache";

export default buildConfig({
  // ...
  plugins: [
    discussionsPlugin({ collections: ["posts"] }), // registers collections & injects fields
    smartCachePlugin({
      collections: ["pages", "posts"],
      globals: ["site-settings"],
    }), // must come after
  ],
});

Wrap your data-fetching functions with createRequestHandler so they are cached by entity tags and automatically revalidated on publish:

import { createRequestHandler } from "payload-smart-cache";

const getPosts = createRequestHandler(
  async () => {
    const payload = await getPayload({ config });
    return payload.find({ collection: "posts" });
  },
  ["posts"], // cache tags — revalidated when posts change
);

Options

Option	Type	Default	Description
collections	CollectionSlug[]	[]	Collections to track changes for. Referenced collections are auto-tracked.
globals	GlobalSlug[]	[]	Globals to track changes for. Referenced collections are auto-tracked.
disableAutoTracking	boolean	false	Disable automatic tracking of collections referenced via relationship/upload fields.
publishHandler	(changes: ChangedDocuments) => void | Promise<void>	—	Custom handler called when changes are published. Receives a record mapping collection slugs to arrays of changed document IDs.

Contributing

This plugin lives in the payload-plugins monorepo.

Development

pnpm install

# watch this plugin for changes
pnpm --filter payload-smart-cache dev

# run the Payload dev app (in a second terminal)
pnpm --filter sandbox dev

The sandbox/ directory is a Next.js + Payload app that imports plugins via workspace:* — use it to test changes locally.

Code quality

• Formatting & linting — handled by Biome, enforced on commit via husky + lint-staged.
• Commits — must follow Conventional Commits with a valid scope (e.g. fix(payload-smart-cache): ...).
• Changesets — please include a changeset in your PR by running pnpm release.

Issues & PRs

Bug reports and feature requests are welcome — open an issue.

License

MIT