{"id":45744,"library":"payload-plugin-cache","title":"payload-plugin-cache","description":"Payload CMS v3 plugin for cache invalidation using stable cache tags. Version 0.9.8, pre-1.0.0 with regular releases. Connects Payload write events (afterOperation/afterChange hooks) to external cache systems via adapters. Ships TypeScript types, ESM-only, requires Next.js 15/16 and Payload ^3.80.0 as peer dependencies. Provides cache tag generation, revalidation strategies, and a registry for frontend-side tag resolution. Supports collection/global cache strategies, path-based invalidation, custom tags, and predicates.","status":"active","version":"0.9.8","language":"javascript","source_language":"en","source_url":"https://github.com/uxio-labs/payload-website-plugins","tags":["javascript","payload","payloadcms","plugin","cache","typescript"],"install":[{"cmd":"npm install payload-plugin-cache","lang":"bash","label":"npm"},{"cmd":"yarn add payload-plugin-cache","lang":"bash","label":"yarn"},{"cmd":"pnpm add payload-plugin-cache","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Next.js cache adapter (nextCacheAdapter) and revalidation","package":"next","optional":true},{"reason":"Peer dependency — core Payload CMS framework required","package":"payload","optional":false}],"imports":[{"note":"ESM-only package; CommonJS require will fail","wrong":"const cacheTags = require('payload-plugin-cache')","symbol":"cacheTags","correct":"import { cacheTags } from 'payload-plugin-cache'"},{"note":"Not a default export; named import from root","wrong":"import { defineCachePlugin } from 'payload-plugin-cache/defineCachePlugin'","symbol":"defineCachePlugin","correct":"import { defineCachePlugin } from 'payload-plugin-cache'"},{"note":"Adapter is exported from a subpath export 'payload-plugin-cache/next'","wrong":"import { nextCacheAdapter } from 'payload-plugin-cache'","symbol":"nextCacheAdapter","correct":"import { nextCacheAdapter } from 'payload-plugin-cache/next'"},{"note":"Not a default export; named import","wrong":"import findAllReferences from 'payload-plugin-cache'","symbol":"findAllReferences","correct":"import { findAllReferences } from 'payload-plugin-cache'"}],"quickstart":{"code":"import { buildConfig } from 'payload'\nimport { cacheTags, defineCachePlugin, findAllReferences } from 'payload-plugin-cache'\nimport { nextCacheAdapter } from 'payload-plugin-cache/next'\n\nconst { plugin: cachePlugin, registry: cacheRegistry } = defineCachePlugin({\n  adapter: nextCacheAdapter(),\n  collections: {\n    pages: {\n      path: ({ doc }) => (typeof doc.populatedUrl === 'string' ? doc.populatedUrl : undefined),\n      predicates: {\n        isSearchPage: ({ doc }) => doc.slug === 'search',\n      },\n      renderTags: async ({ doc, locale, path, searchParams, predicates }) => [\n        path ? cacheTags.route({ path, locale }) : null,\n        cacheTags.document({ collection: 'pages', id: doc.id, locale }),\n        ...findAllReferences(doc).map((reference) =>\n          cacheTags.document({\n            collection: reference.collection,\n            id: reference.id,\n            locale,\n          }),\n        ),\n        cacheTags.custom('sitemap'),\n        predicates.isSearchPage ? cacheTags.custom('searches') : null,\n        predicates.isSearchPage && searchParams?.get('q')\n          ? cacheTags.custom(`search:${searchParams.get('q')}`)\n          : null,\n      ],\n    },\n    team: {\n      revalidateOn: ['update', 'delete'],\n      renderTags: () => [cacheTags.custom('page')],\n    },\n  },\n  globals: {\n    settings: {\n      renderTags: () => [cacheTags.global('settings'), cacheTags.custom('sitemap')],\n    },\n    header: {\n      renderTags: () => [cacheTags.global('header')],\n      revalidatePaths: () => [{ path: '/', type: 'layout' }],\n    },\n    footer: {\n      renderTags: () => [cacheTags.global('footer')],\n      revalidatePaths: () => [{ path: '/', type: 'layout' }],\n    },\n  },\n})\n\nexport { cacheRegistry }\n\nexport default buildConfig({\n  plugins: [cachePlugin],\n  collections: [\n    { slug: 'pages', fields: [] },\n    { slug: 'team', fields: [] },\n  ],\n  globals: [\n    { slug: 'settings', fields: [] },\n    { slug: 'header', fields: [] },\n    { slug: 'footer', fields: [] },\n  ],\n})","lang":"typescript","description":"Full Payload CMS configuration using defineCachePlugin for pages collection and globals with Next.js cache adapter."},"warnings":[{"fix":"Use ES module imports (import/export) or configure Node.js to handle ESM","message":"ESM-only package — require() will throw at runtime","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Pin to exact version and monitor changelog","message":"Pre-1.0.0 API may change without major version bump","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure matching peer dependencies or use a different adapter","message":"nextCacheAdapter requires Next.js 15/16 and Payload ^3.80.0 peer deps","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use defineCachePlugin which returns both plugin and registry","message":"cachePlugin standalone export may be deprecated in favor of defineCachePlugin","severity":"deprecated","affected_versions":">=0.9.0"},{"fix":"Export cacheRegistry from config and import it in frontend code","message":"Registry must be exported or shared between Payload and frontend for tag resolution to work","severity":"gotcha","affected_versions":">=0.9.0"}],"env_vars":null,"search_vec":"'0.9.8':17 '1.0.0':19 '15/16':43 '3.80.0':46 'adapt':34 'afteroperation/afterchange':27 'base':71 'cach':4,10,14,31,51,67,81 'cms':6 'collection/global':66 'connect':23 'custom':73 'depend':49 'esm':39 'esm-on':38 'event':26 'extern':30 'frontend':61 'frontend-sid':60 'generat':53 'hook':28 'invalid':11,72 'javascript':77 'next.js':42 'path':70 'path-bas':69 'payload':2,5,24,45,78 'payload-plugin-cach':1 'payloadcm':79 'peer':48 'plugin':3,8,80 'pre':18 'predic':76 'provid':50 'registri':58 'regular':21 'releas':22 'requir':41 'resolut':64 'revalid':54 'ship':35 'side':62 'stabl':13 'strategi':55,68 'support':65 'system':32 'tag':15,52,63,74 'type':37 'typescript':36,82 'use':12 'v3':7 'version':16 'via':33 'write':25","created_at":"2026-06-07T12:56:30.939777+00:00","updated_at":"2026-06-07T12:56:30.939777+00:00","problems":[{"fix":"Use import { nextCacheAdapter } from 'payload-plugin-cache/next' (check package.json exports field)","cause":"Subpath export not configured or wrong import path","error":"Cannot find module 'payload-plugin-cache/next'"},{"fix":"Switch to import { defineCachePlugin } from 'payload-plugin-cache'","cause":"Using CommonJS require instead of ESM import","error":"defineCachePlugin is not a function"},{"fix":"Ensure adapter is imported correctly: import { nextCacheAdapter } from 'payload-plugin-cache/next'","cause":"Missing or incorrectly imported adapter","error":"TypeError: adapter is not a function or object"},{"fix":"Add adapter: nextCacheAdapter() (or custom adapter) to defineCachePlugin options","cause":"Missing adapter option in plugin configuration","error":"Error: No adapter provided to defineCachePlugin"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/uxio-labs/payload-website-plugins/tree/main/packages/payload-plugin-cache#readme","github":"https://github.com/uxio-labs/payload-website-plugins","docs":null,"changelog":null,"pypi":null,"npm":"payload-plugin-cache","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}