use cache: private doesn't work in route handlers

[ellemedit]

Summary

both use cache and use cache: remote work in route handler but use cache: private doesn't work in route handler. it doesn't dedupe invocations and memoization during a request.

Additional information

I tested in local development.

RSC works:

import { cacheLife, cacheTag } from "next/cache";
import { headers } from "next/headers";
import { Suspense } from "react";

let cacheValue = 0;

async function getCachePrivateValue() {
  "use cache: private";
  cacheTag("test-private");
  cacheLife({ stale: 60 });
  
  const auth = (await headers()).get('Authorization') || 'guest';
  console.log('Called:', auth, cacheValue);
  cacheValue += 1;
  return cacheValue;
}

export default async function TestCachePage() {
  const results = [];
  for (let i = 0; i < 11; i++) {
    results.push(getCachePrivateValue());
  }
  
  return (
    <div>
      <h1>Cache Test</h1>
      <Suspense>
        {Promise.all(results).then(results => results.join(", "))}
      </Suspense>
    </div>
  );
}

it prints [1, 1, 1, ..., 1] or [2, 2, 2, ..., 2] at the same time.

but route handler doesn't:

import { cacheLife, cacheTag } from "next/cache";

export async function GET() {
  for (let i = 0; i < 10; i++) {
    await getCachePrivateValue(1);
  }
  const count = await getCachePrivateValue(1);
  return Response.json({ count });
}

let cacheValue = 0;

export async function getCachePrivateValue(id: number) {
  "use cache: private";
  cacheTag(`useCachePrivateCheck-${id}`);
  cacheLife({ stale: 60, revalidate: 60, expire: Infinity });
  cacheValue += 1;
  return cacheValue;
}

it prints 11, 22 or 33

all tests were validated at [email protected] canary

[icyJoseph]

@ellemedit sorry for the confusion here, and the AI answer clearly not having done any checks.

use cache: private works only on a browser, the calculation is done server side and sent to the client, which stores it in a client side ephemeral cache. While you can use the other directives, the key difference with use cache: private is that it is meant to not store things server side. So yeah, it won't work the way you are trying to use it.

[ellemedit]

I see, it would be good point for documentation. To me, it felt like a per-request cache store

[msha-spacestep]

you have to guess, collecting pieces of information all around =(

even though i love nextjs the primitives you are giving are not very easy to understand and DX is tough.
Would be great to give more examples, better documentation, etc. But still ty for support here.

extra few lines: "use cache:private" reminds me tanstack query cache - it stored client side, disappears on reload.
BUT "use cache:private" it prerenders by links....

do not know, very strange. we are using tanstack query at work with streaming and all that stuff and i see no reason to use this new directive use ("use cache:private")

correct me if i am wrong. ty

[icyJoseph]

Around runtime prefetching, the feature is still landing a few more bits, but AFAIK, it is not exclusive to private cache.

Private cache, as I understand it, is something you likely use a couple of times, if at all, in a project. I have an update to the page you linked, and a follow up to private, and then circle back to runtime prefetching as more pieces fall into place.

Like if you have a getSession function from a library, which calls cookies from next/headers, you can't really refactor out to use the other directives, so you could perhaps (but not always need to!) use the private cache to store the result in the client, and let Next.js do some optimizations with that information, or just fetch it on demand as needed.

[msha-spacestep]

thank you, will be trying to utilise these new things and watch if we gain some boost in speed