Custom Incremental Cache Handler with Redis

[XEngine]

We are running Next.js 13+ in Kubernetes with 2+ pods. However, we have encountered an issue with file storage caching that leads to a revalidateTag issue.

The tags are not always validated because the API route only validates the filesystem where the load balancer points to.

To achieve our desired outcome, we are attempting to implement Redis so that Next.js can cache fetch results into a Redis key-value store in a shared pod.

According to Next.js's documentation, the incrementalCacheHandlerPath accomplishes exactly this, but the documentation on that particular topic is insufficient.

I have created my own cache handler, but when I look at the file-system-cache.ts file of Next.js, I see that it also handles other caches like ROUTE and IMAGE, which are cache types I am unfamiliar with. I am unsure how to proceed. Could you please review the code below and provide some guidance? It is currently functioning, but I am uncertain about its stability since it lacks support for other cache types.

My other question is are the cache keys same between pods for the same fetch requests?

const Redis = require("ioredis");
const {getDerivedTags} = require("next/dist/server/lib/incremental-cache/utils");
const redis = new Redis();

const TAG_MANIFESTS_KEY = 'tags-manifest'
module.exports = class CacheHandler {
    revalidatedTags = []

    constructor(options) {
        this.options = options
        this.revalidatedTags = options.revalidatedTags
    }

    async loadTagsManifest() {
        const tagManifest = await redis.get(TAG_MANIFESTS_KEY)
        if(!tagManifest) {
            return {version: 1, items: {}}
        }

        try {
            return JSON.parse(tagManifest)
        } catch (err) {
            console.log(err)
            return {version: 1, items: {}}
        }
    }

    async setTags(key, tags) {
        const tagsManifest = await this.loadTagsManifest()
        if (!tagsManifest) {
            return null
        }

        for (const tag of tags) {
            const data = tagsManifest.items[tag] || {keys: []}
            if (!data.keys.includes(key)) {
                data.keys.push(key)
            }
            tagsManifest.items[tag] = data
        }

        try {
            await redis.set(TAG_MANIFESTS_KEY, JSON.stringify(tagsManifest || {}))
        } catch (err) {
            console.warn('Failed to update tags manifest.', err)
        }
    }

    async get(key) {
        let data = JSON.parse(await redis.get(key))

        if(data) {
            const tagsManifest = await this.loadTagsManifest()

            const innerData = data.value.data
            const derivedTags = getDerivedTags(innerData.tags || [])

            const wasRevalidated = derivedTags.some((tag) => {
                if (this.revalidatedTags.includes(tag)) {
                    return true
                }

                return (
                    tagsManifest?.items[tag]?.revalidatedAt &&
                    tagsManifest?.items[tag].revalidatedAt >=
                    (data?.lastModified || Date.now())
                )
            })

            // When revalidate tag is called we don't return
            // stale data, so it's updated right away
            if (wasRevalidated) {
                data = undefined
            }
        }

        return data || null
    }

    async set(key, data) {
        await redis.set(key, JSON.stringify(
            {
                value: data,
                lastModified: Date.now(),
            }
        ))

        await this.setTags(key, data.data.tags || [])
    }

    async revalidateTag(tag) {
        const tagsManifest = await this.loadTagsManifest()
        if (!tagsManifest) {
            return null
        }

        const data = tagsManifest.items[tag] || { keys: [] }
        data.revalidatedAt = Date.now()
        tagsManifest.items[tag] = data

        try {
            await redis.set(TAG_MANIFESTS_KEY, JSON.stringify(tagsManifest || {}))
        } catch (err) {
            console.warn('Failed to update tags manifest.', err)
        }
    }
}

[XEngine]

any information about it, everyone?

[rybon]

Question to @timneutkens or @leerob, do both the Data Cache and the Full Route Cache make use of the incremental cache handler or is it just the Data Cache?

Can we plug in a custom cache handler for both of these, as documented here? https://nextjs.org/docs/app/api-reference/next-config-js/incrementalCacheHandlerPath

The use case is the same as what the OP described. You'd want to speed up slow I/O (for example fetches) with the Data Cache and slow or expensive CPU-intensive rendering with the Full Route Cache and share these caches across Next.js instances for consistency/predictability and efficiency reasons. I realize the Data Cache and Full Route Cache serve different purposes and am mostly interested in the latter. Ruby on Rails does something very similar to Full Route Caching using cache annotations around partials and composing smaller cached partials into larger (as yet) uncached partials (Russian Doll Caching) to avoid having to redo large and expensive re-renders whenever a small part of the UI is invalidated. This cache can be backed by various storage options such as Redis and shared between Rails instances. I'd like to achieve the same result (a shared cache) with Next.js.

[IgorBadanyuk]

Hi also ran into the file cache problem. Only in my case the file cache grows up to 30GB in a week, because there is no system to clear it, only rebuild with removing .next folder.

I also looked at file-system-cache.js. to try and make my own implementation.

1. In Next.js v13.4.2, the revalidateTag() function is not called in production, only in dev mode. I plan to install the latest version to see if it works.
2. The file-system-cache.js file has already changed between version 13.4.2 and 14.0.3, meaning you need either a constant watch for it, or a way to cover your implementation with tests.
3. As I understand, Next.js splits the cache into fetch-cache, page cache for specific storage within the file system. Also, finding tag data depends on the type of cached data.
4. In my solution, I simplified the work with tags. Instead of setting the revalidation state in revalidateTag(), I get the list of keys and delete it with single transaction, the next time I request such a key there will be no more, which will cause loading again.

There really is no PAGE cache processing in your solution. You need to store tags and keys for the PAGE in the manifest, and when you get the cache, retrieve the tags and check if they are out of date. This is exactly the same as it is done in the original file.

Also make sure that get, set, revalidateTag functions are called in production.
I hope this helps you in some way 😃

[gtjamesa]

Next now has examples for using a custom Redis cache handler @neshca/cache-handler

• https://github.com/vercel/next.js/tree/canary/examples/cache-handler-redis
• https://github.com/caching-tools/next-shared-cache/tree/canary/packages/cache-handler

[IgorBadanyuk]

Wow, thanks

[ats1999]

I am also looking for answers here vercel/vercel#10972

Facing issue with the website https://dsabyte.com which has been deployed on vercel and incrementalCacheHandlerPath is not working properly

[leerob]

That option does not work on Vercel, because Vercel already provides this: https://vercel.com/docs/infrastructure/data-cache

[dhmacs]

@leerob, is there no way to override the data cache when deploying on Vercel? We are currently deploying on Vercel and already have a caching solution in place. We would like to utilize the data cache, but we don't want to be locked into Vercel's Data Cache pricing.