use cache and the migration traps

'use cache' is not just a new way to cache. It is the replacement for unstable_cache, the fetch cache options, fetchCache, and dynamic = 'force-static'. This lesson is the migration, plus the four things that surprise people who cached the old way.

1// Before: unstable_cache with manual keys2const getUser = unstable_cache(3  async (id) => db.users.find(id),4  ['user'],                 // keyParts — you maintained these by hand5  { tags: ['users'], revalidate: 60 },6)7 8// After: 'use cache' — keys are generated for you9async function getUser(id: string) {10  'use cache'11  cacheTag('users')12  cacheLife({ revalidate: 60 })13  return db.users.find(id)14}

No more keyParts. The key is built from the function id, the serializable arguments, and the captured closure variables. That last part is the trap: anything you close over is part of the key, whether you meant it or not.

1function Report({ orgId }: { orgId: string }) {2  const big = buildHugePolicyObject()   // captured in the closure below3 4  async function load(range: string) {5    'use cache'6    // Cache key = orgId (closure) + big (closure) + range (argument).7    // 'big' is serialized into the key on every call. That is the trap.8    return db.metrics(orgId, range)9  }10  return load('30d')11}

A cached result must be reusable, so cookies(), headers(), and searchParams throw inside 'use cache'. Read them outside and pass the value in; it becomes part of the key. The one escape hatch is 'use cache: private', which you will meet in Lesson 5, not the default.

Math.random(), Date.now(), new Date(), and crypto.randomUUID() inside a cache execute once when the entry fills, then serve that frozen value to everyone. If you want per-request values, use connection() to defer back to request time, outside the cache.

1import { connection } from 'next/server'2 3async function getBanner() {4  'use cache'5  // Runs ONCE when the cache fills, then frozen. Every user sees the same id.6  const id = crypto.randomUUID()7  return db.banner(id)8}9 10async function RequestId() {11  await connection()          // opt back into request time12  return <span>{crypto.randomUUID()}</span>  // fresh per request13}

Two changes from the invalidation you know. revalidateTag now takes a cacheLife profile as a second argument to enable stale-while-revalidate. And updateTag is new: it gives read-your-writes in the same request, which revalidateTag never guaranteed.

1'use server'2import { revalidateTag, updateTag } from 'next/cache'3 4export async function publishPost(data: FormData) {5  await db.posts.create({ data })6  // Next.js 16: revalidateTag now takes a cacheLife profile as a 2nd arg.7  revalidateTag('posts', 'max')     // background, stale-while-revalidate8}9 10export async function editPost(id: string, data: FormData) {11  await db.posts.update({ where: { id }, data })12  updateTag(`post-${id}`)            // immediate, same request reads its own write13}

• 'use cache' replaces unstable_cache, fetch options, and force-static.
• Keys are automatic from arguments and the closure; keep request data and heavy captures out.
• Non-deterministic calls freeze at fill time; use connection() for per-request values.
• revalidateTag takes a profile arg now; updateTag adds read-your-writes.
• In-memory cache is per instance; use 'use cache: remote' to share it.

Next: navigation. Your existing loading.tsx and top-level boundaries are about to become the thing that blocks the shell.