GitHub

Getting Started with `@neshca/cache-handler`

This section guides you through the initial setup and basic usage of @neshca/cache-handler, helping you integrate advanced caching solutions into your Next.js applications seamlessly.

Prerequisites

Node.js: Version 18.17 or newer.
Next.js: Version 13.5.1 or newer.
Redis (optional): Version 4.6.0 or newer.

Quick Start Installation

npx create-next-app --example cache-handler-redis cache-handler-redis-app

yarn create next-app --example cache-handler-redis cache-handler-redis-app

pnpm create next-app --example cache-handler-redis cache-handler-redis-app

Manual installation

Install @neshca/cache-handler:
Execute this command in your Next.js project root directory:
```
npm install -D @neshca/cache-handler
```
Optional Redis Installation:
Install Redis if you plan to use it as your cache store:
```
npm install -D redis
```

Basic Custom Configuration

Create a Cache Handler File:
In your project root, create a file named cache-handler.mjs for your cache configuration.

Configure the Cache Handler:
Below is a basic setup example:

cache-handler.mjs

import { CacheHandler } from '@neshca/cache-handler';
 
CacheHandler.onCreation(async () => {
  // Let's imagine we're using a map
  // in which values are shared via the network
  // between all your Next.js app instances.
  const cacheStore = new MagicMap();
 
  const handler = {
    async get(key) {
      return await cacheStore.get(key);
    },
    async set(key, value) {
      await cacheStore.set(key, value);
    },
    async revalidateTag(tag) {
      // Iterate over all entries in the cache
      for (const [key, { tags }] of cacheStore) {
        // If the value's tags include the specified tag, delete this entry
        if (tags.includes(tag)) {
          await cacheStore.delete(key);
        }
      }
    },
    // Optional: Implement the delete method
    // if your cache store doesn't support automatic time-based key expiration.
    // It will be called when the get method returns expired data.
    async delete(key) {
      await cacheStore.delete(key);
    },
  };
 
  return {
    handlers: [handler],
  };
});
 
export default CacheHandler;

Integrate with Next.js:
Update your next.config.js to utilize the cache handler, ensuring it's only active in production:

next.config.js

const nextConfig = {
  cacheHandler: process.env.NODE_ENV === 'production' ? require.resolve('./cache-handler.mjs') : undefined,
  // Use `experimental` option instead of the `cacheHandler` property when using Next.js versions from 13.5.1 to 14.0.4
  /* experimental: {
        incrementalCacheHandlerPath:
            process.env.NODE_ENV === 'production' ? require.resolve('./cache-handler.mjs') : undefined,
    }, */
};
 
module.exports = nextConfig;

Do not import @neshca/cache-handler to your components or pages. It is only meant to be used in cache-handler.mjs files.

Running Your Application

Start Your Next.js Application:

Build and start your application in production mode to see the cache handler in action:

npm run build
npm run start

Next Steps

With the setup complete, explore @neshca/cache-handler's advanced features:

Check out the Redis Integration Example.
Learn how to use the API.
See how to debug and troubleshoot your cache handler configuration.

Introduction onCreation

Getting Started with @neshca/cache-handler