Use Cache

Next.JS Use Cache

3 min read

Published Jul 3 2025

JavascriptNextJS

nextjs-usecache-demo project on GitHub

A simple demo Next.JS application on GitHub to demonstrate points made in this guide

Open

Next.JS documentation page

Link to the official Next.JS documentation website article relating to use cache.

Open

Still experimental

The use cache functionality is currently still in-development. However, it is available in the main release branch if you turn on the experimental setting. It does not require you to use the Canary release branch.

To enable the use cache functionality while it is still in-development, make sure you are on an up to date version 15 release, and add this to your next.config file:

/next.config.ts

const nextConfig: NextConfig = {

experimental: {

useCache: true,

// rest of the config settings here...

};

Caching has been a bit of a mess in previous Next.JS versions. They had the fetch function that automatically applied caching, and then reverted that back to opt in only. If you wanted to not make API endpoints and make internal get data functions to pull data from a database, making use of an ORM such as Drizzle or Prisma, then there was the unstable_cache wrapper that you could use. This worked to a fashion, but made it incredibly difficult to invalidate the cache, other than a single overall tag. Trying to add a tag for a specific record based on the data returned got very messy.

Now Next.JS has redone how they have implemented caching and it is great. So easy to use. A combination of use cache, cacheLife and cacheTag functions allows you to easily define what is to be cached, for how long and simple to add tags for revalidating, even based on the returned data.

The use cache directive can be implemented at three levels:

Page/Layout level
Component level
Function level

In this guide we will be concentrating on the function level and how to use when getting data from a database in a function. You can refer to the official documentation link at the top of this page for more details on the other two levels.

Say you have a server function that queries and returns data from a database. This could be directly, using an ORM such as Prisma, Drizzle or Mongoose etc or maybe a CMS function such as payload.find. It may also manipulate and mold the data using the Javascript map function etc too, before returning the results.

eg. something like:

import config from '@payload-config'

import { getPayload } from 'payload'

import { categories, category_images } from '@/payload-generated-schema'

import { eq } from '@payloadcms/db-postgres/drizzle'

export const getCategory = async (slug: string) => {

const payload = await getPayload({ config })

const cats = await payload.db.drizzle

.select({

id: categories.id,

slug: categories.slug,

title: categories.title,

description: categories.description,

image: {

id: category_images.id,

prefix: category_images.prefix,

filename: category_images.filename,

width: category_images.width,

height: category_images.height,

})

.from(categories)

.leftJoin(category_images, eq(category_images.id, categories.image))

.where(eq(categories.slug, slug))

return cats[0] || undefined

}

In order to cache that response so that the database call isn't made with every request, it is as simple as adding this to the top of the function:

import config from '@payload-config'

import { getPayload } from 'payload'

import { categories, category_images } from '@/payload-generated-schema'

import { eq } from '@payloadcms/db-postgres/drizzle'

export const getCategory = async (slug: string) => {

+ 'use cache'

const payload = await getPayload({ config })

const cats = await payload.db.drizzle

.select({

id: categories.id,

slug: categories.slug,

title: categories.title,

description: categories.description,

image: {

id: category_images.id,

prefix: category_images.prefix,

filename: category_images.filename,

width: category_images.width,

height: category_images.height,

})

.from(categories)

.leftJoin(category_images, eq(category_images.id, categories.image))

.where(eq(categories.slug, slug))

return cats[0] || undefined

}

That's it! by default that will be cached for 15 minutes, so any other request to that function with the same slug value passed in will receive the cached version. No database call unless the time expires, or a different input parameter value is passed in.

If you call the function with a slug of category1 and a slug of category2, they will get cached separately. If your function has multiple input parameters then the combination of all the parameters combined define what is cached. Any unique combination will hit the database and the result cached, if no cache already exists.

To make this more useful, we need to look at how to define how long it will be cached for and how to revalidate the cache on demand, when a record updates etc. which we will look at in the next sections.