{"id":45746,"library":"payloadcms-redis-plugin","title":"PayloadCMS Redis Plugin","description":"A transparent Redis caching layer plugin for Payload CMS v3 (currently version 0.2.17, early development). It automatically caches database read queries (find, findOne, count) and invalidates them on writes (create, update, delete). Requires Payload ^3.37.0, Node.js 18.20.2+/20.9.0+, and ioredis. Supports per-collection/global configuration, custom TTL, debug logging, and custom cache key generation. Key differentiator: zero breaking changes integration with existing Payload apps and smart invalidation on write operations.","status":"active","version":"0.2.17","language":"javascript","source_language":"en","source_url":"https://github.com/ianyimi/payloadcms-redis-plugin","tags":["javascript","typescript"],"install":[{"cmd":"npm install payloadcms-redis-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add payloadcms-redis-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add payloadcms-redis-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Redis client dependency required for all functionality","package":"ioredis","optional":false},{"reason":"Peer dependency; plugin integrates with Payload CMS v3.37.x","package":"payload","optional":false}],"imports":[{"note":"Named export only; no default export. Package is ESM-only.","wrong":"const redisCache = require('payloadcms-redis-plugin')","symbol":"redisCache","correct":"import { redisCache } from 'payloadcms-redis-plugin'"},{"note":"defaultCacheOptions is not directly exported; it's a key of the plugin config object passed to redisCache.","wrong":"import { defaultCacheOptions } from 'payloadcms-redis-plugin'","symbol":"defaultCacheOptions","correct":"import { redisCache } from 'payloadcms-redis-plugin'; const config = redisCache({ defaultCacheOptions: { ttl: 600 } })"},{"note":"RedisPluginConfig is a TypeScript type, only importable via type import.","wrong":"import { RedisPluginConfig } from 'payloadcms-redis-plugin'","symbol":"RedisPluginConfig","correct":"import type { RedisPluginConfig } from 'payloadcms-redis-plugin'"}],"quickstart":{"code":"import { buildConfig } from 'payload'\nimport { redisCache } from 'payloadcms-redis-plugin'\n\nexport default buildConfig({\n  plugins: [\n    redisCache({\n      redis: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' },\n      collections: {\n        posts: { ttl: 600 }, // 10 minutes\n        articles: true,       // default TTL (300s)\n      },\n      debug: true,\n    }),\n  ],\n  // ... rest of your config\n})","lang":"typescript","description":"Sets up Payload CMS v3 with the Redis plugin, caching posts and articles collection queries with custom TTLs."},"warnings":[{"fix":"Upgrade Payload to >=3.37.0 or use an older version of this plugin (if exists).","message":"Plugin requires Payload v3.37.0 or higher. Older Payload versions will cause import errors or runtime failures.","severity":"breaking","affected_versions":"<0.1.0"},{"fix":"Use `redis.url` instead of `redis.client` if possible.","message":"The option `redis.client` is deprecated in favor of `redis.url`. Using `redis.client` will still work but may be removed in future versions.","severity":"deprecated","affected_versions":">=0.2.0"},{"fix":"Ensure TTL is specified in seconds (e.g., 3600 for 1 hour).","message":"TTL values are in seconds, not milliseconds. Setting a very large number may cause unexpected long caching.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Explicitly set `collections: { sensitiveCollection: false }` or `{ skip: true }`.","message":"The plugin caches all read operations by default; if you have sensitive data that should not be cached, set `skip: true` or exclude collections.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Keep cache keys short; use a hash or include only essential parts of the query.","message":"Using a custom `generateKey` function that includes the full query object can lead to huge cache keys and memory issues.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'/20.9.0':41 '/global':48 '0.2.17':16 '18.20.2':40 '3.37.0':38 'app':68 'automat':20 'break':62 'cach':7,21,56 'chang':63 'cms':12 'collect':47 'configur':49 'count':27 'creat':33 'current':14 'custom':50,55 'databas':22 'debug':52 'delet':35 'develop':18 'differenti':60 'earli':17 'exist':66 'find':25 'findon':26 'generat':58 'integr':64 'invalid':29,71 'ioredi':43 'javascript':75 'key':57,59 'layer':8 'log':53 'node.js':39 'oper':74 'payload':11,37,67 'payloadcm':1 'per':46 'per-collect':45 'plugin':3,9 'queri':24 'read':23 'redi':2,6 'requir':36 'smart':70 'support':44 'transpar':5 'ttl':51 'typescript':76 'updat':34 'v3':13 'version':15 'write':32,73 'zero':61","created_at":"2026-06-07T12:56:31.118722+00:00","updated_at":"2026-06-07T12:56:31.118722+00:00","problems":[{"fix":"Use import { redisCache } from 'payloadcms-redis-plugin'; ensure package.json has \"type\": \"module\" or use .mjs extension.","cause":"Using CommonJS require() instead of ESM import in a Node.js ESM context.","error":"ERR_MODULE_NOT_FOUND"},{"fix":"Ensure Payload buildConfig includes a valid database adapter (e.g., postgresAdapter).","cause":"Missing or invalid Payload database adapter configuration; plugin requires an active DB connection.","error":"TypeError: db is not a function"},{"fix":"Add `redis: { url: 'redis://localhost:6379' }` or `redis: { client: new Redis() }` to the plugin config.","cause":"Neither `redis.url` nor `redis.client` was passed in the plugin options.","error":"MissingRedisClientError: `redis.url` or `redis.client` must be provided."},{"fix":"Check that collections is defined in plugin config or use optional chaining: config.collections?.posts.","cause":"Attempting to destructure 'collections' in custom code assuming it's always present, but plugin config may not define it.","error":"TypeError: Cannot read properties of undefined (reading 'collections')"}],"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/ianyimi/payloadcms-redis-plugin#readme","github":"https://github.com/ianyimi/payloadcms-redis-plugin","docs":null,"changelog":null,"pypi":null,"npm":"payloadcms-redis-plugin","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"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}}