Skip to Content
🎉 Version 1.9.0 is out! This is the final release supporting Next.js 13.5.1-14.x. The upcoming version 2.0.0 will require Next.js 15.
Built-in Redis Handler

redis-stack Handler example

Note

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.

Last updated on