redis-stack
Handler example
In this example, we assume that in your deployment, you have REDIS_URL
environment variable set to the URL of your
Redis instance. You can use any other way to set the URL.
See the redis-stack
Handler documentation for more information and requirements for the Redis server.
Create a file called cache-handler.mjs
next to your next.config.js
with the following contents:
cache-handler.mjs
import { CacheHandler } from '@neshca/cache-handler';
import createLruHandler from '@neshca/cache-handler/local-lru';
import createRedisHandler from '@neshca/cache-handler/redis-stack';
import { createClient } from 'redis';
CacheHandler.onCreation(async () => {
let client;
try {
// Create a Redis client.
client = createClient({
url: process.env.REDIS_URL ?? 'redis://localhost:6379',
});
// Redis won't work without error handling. https://github.com/redis/node-redis?tab=readme-ov-file#events
client.on('error', (error) => {
if (typeof process.env.NEXT_PRIVATE_DEBUG_CACHE !== 'undefined') {
// Use logging with caution in production. Redis will flood your logs. Hide it behind a flag.
console.error('Redis client error:', error);
}
});
} catch (error) {
console.warn('Failed to create Redis client:', error);
}
if (client) {
try {
console.info('Connecting Redis client...');
// Wait for the client to connect.
// Caveat: This will block the server from starting until the client is connected.
// And there is no timeout. Make your own timeout if needed.
await client.connect();
console.info('Redis client connected.');
} catch (error) {
console.warn('Failed to connect Redis client:', error);
console.warn('Disconnecting the Redis client...');
// Try to disconnect the client to stop it from reconnecting.
client
.disconnect()
.then(() => {
console.info('Redis client disconnected.');
})
.catch(() => {
console.warn('Failed to quit the Redis client after failing to connect.');
});
}
}
/** @type {import("@neshca/cache-handler").Handler | null} */
let handler;
if (client?.isReady) {
// Create the `redis-stack` Handler if the client is available and connected.
handler = await createRedisHandler({
client,
keyPrefix: 'prefix:',
timeoutMs: 1000,
});
} else {
// Fallback to LRU handler if Redis client is not available.
// The application will still work, but the cache will be in memory only and not shared.
handler = createLruHandler();
console.warn('Falling back to LRU handler because Redis client is not available.');
}
return {
handlers: [handler],
};
});
export default CacheHandler;
Ensure that the Redis instance is running when you build your Next.js app. If you can not ensure that, see how to disable the Handler during a build stage in the Building the App Without Redis Cache Connection section.