Registry / database / payloadcms-redis-plugin

payloadcms-redis-plugin

library0.2.17jsnpmunverified

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.

database

npm install payloadcms-redis-plugin

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PAYLOADCMS-REDIS-P

payloadcms-redis-plugin

databasejavascriptv0.2.17

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

redisCache

✓ import { redisCache } from 'payloadcms-redis-plugin'

✗ const redisCache = require('payloadcms-redis-plugin')

Named export only; no default export. Package is ESM-only.

defaultCacheOptions

✓ import { redisCache } from 'payloadcms-redis-plugin'; const config = redisCache({ defaultCacheOptions: { ttl: 600 } })

✗ import { defaultCacheOptions } from 'payloadcms-redis-plugin'

defaultCacheOptions is not directly exported; it's a key of the plugin config object passed to redisCache.

RedisPluginConfig

✓ import type { RedisPluginConfig } from 'payloadcms-redis-plugin'

✗ import { RedisPluginConfig } from 'payloadcms-redis-plugin'

RedisPluginConfig is a TypeScript type, only importable via type import.

Sets up Payload CMS v3 with the Redis plugin, caching posts and articles collection queries with custom TTLs.

import { buildConfig } from 'payload' import { redisCache } from 'payloadcms-redis-plugin' export default buildConfig({ plugins: [ redisCache({ redis: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' }, collections: { posts: { ttl: 600 }, // 10 minutes articles: true, // default TTL (300s) }, debug: true, }), ], // ... rest of your config })

Debug

Known issues

breakingPlugin requires Payload v3.37.0 or higher. Older Payload versions will cause import errors or runtime failures.

fix

Upgrade Payload to >=3.37.0 or use an older version of this plugin (if exists).

affects: <0.1.0

deprecatedThe option `redis.client` is deprecated in favor of `redis.url`. Using `redis.client` will still work but may be removed in future versions.

fix

Use `redis.url` instead of `redis.client` if possible.

affects: >=0.2.0

gotchaTTL values are in seconds, not milliseconds. Setting a very large number may cause unexpected long caching.

fix

Ensure TTL is specified in seconds (e.g., 3600 for 1 hour).

affects: >=0.1.0

gotchaThe plugin caches all read operations by default; if you have sensitive data that should not be cached, set `skip: true` or exclude collections.

fix

Explicitly set `collections: { sensitiveCollection: false }` or `{ skip: true }`.

affects: >=0.1.0

gotchaUsing a custom `generateKey` function that includes the full query object can lead to huge cache keys and memory issues.

fix

Keep cache keys short; use a hash or include only essential parts of the query.

affects: >=0.1.0

Errors

Common errors & fixes

ERR_MODULE_NOT_FOUND

Using CommonJS require() instead of ESM import in a Node.js ESM context.

fix

Use import { redisCache } from 'payloadcms-redis-plugin'; ensure package.json has "type": "module" or use .mjs extension.

TypeError: db is not a function

Missing or invalid Payload database adapter configuration; plugin requires an active DB connection.

fix

Ensure Payload buildConfig includes a valid database adapter (e.g., postgresAdapter).

MissingRedisClientError: `redis.url` or `redis.client` must be provided.

Neither `redis.url` nor `redis.client` was passed in the plugin options.

fix

Add `redis: { url: 'redis://localhost:6379' }` or `redis: { client: new Redis() }` to the plugin config.

TypeError: Cannot read properties of undefined (reading 'collections')

Attempting to destructure 'collections' in custom code assuming it's always present, but plugin config may not define it.

fix

Check that collections is defined in plugin config or use optional chaining: config.collections?.posts.

Upgrade

Version history

0.2.17latest on npm

Audit

Dependencies

ioredisrequiredRedis client dependency required for all functionality

payloadrequiredPeer dependency; plugin integrates with Payload CMS v3.37.x

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/ianyimi/payloadcms-redis-plugin ↗

packagepayloadcms-redis-plugin ↗

homepagehttps://github.com/ianyimi/payloadcms-redis-plugin#readme ↗