# Next Cache Components

> Next.js 16 Cache Components - PPR, use cache directive, cacheLife, cacheTag, updateTag

- **Type:** Skill
- **Install:** `agentstack add skill-leonardotrapani-better-skills-next-cache-components`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [LeonardoTrapani](https://agentstack.voostack.com/s/leonardotrapani)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [LeonardoTrapani](https://github.com/LeonardoTrapani)
- **Source:** https://github.com/LeonardoTrapani/better-skills/tree/master/.agents/skills/next-cache-components
- **Website:** https://better-skills.dev

## Install

```sh
agentstack add skill-leonardotrapani-better-skills-next-cache-components
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Cache Components (Next.js 16+)

Cache Components enable Partial Prerendering (PPR) - mix static, cached, and dynamic content in a single route.

## Enable Cache Components

```ts
// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
};

export default nextConfig;
```

This replaces the old `experimental.ppr` flag.

---

## Three Content Types

With Cache Components enabled, content falls into three categories:

### 1. Static (Auto-Prerendered)

Synchronous code, imports, pure computations - prerendered at build time:

```tsx
export default function Page() {
  return (
    
      Our Blog {/* Static - instant */}
      ...
    
  );
}
```

### 2. Cached (`use cache`)

Async data that doesn't need fresh fetches every request:

```tsx
async function BlogPosts() {
  "use cache";
  cacheLife("hours");

  const posts = await db.posts.findMany();
  return ;
}
```

### 3. Dynamic (Suspense)

Runtime data that must be fresh - wrap in Suspense:

```tsx
import { Suspense } from "react";

export default function Page() {
  return (
    <>
       {/* Cached */}
      Loading...}>
         {/* Dynamic - streams in */}
      
    
  );
}

async function UserPreferences() {
  const theme = (await cookies()).get("theme")?.value;
  return Theme: {theme};
}
```

---

## `use cache` Directive

### File Level

```tsx
"use cache";

export default async function Page() {
  // Entire page is cached
  const data = await fetchData();
  return {data};
}
```

### Component Level

```tsx
export async function CachedComponent() {
  "use cache";
  const data = await fetchData();
  return {data};
}
```

### Function Level

```tsx
export async function getData() {
  "use cache";
  return db.query("SELECT * FROM posts");
}
```

---

## Cache Profiles

### Built-in Profiles

```tsx
"use cache"; // Default: 5m stale, 15m revalidate
```

```tsx
"use cache: remote"; // Platform-provided cache (Redis, KV)
```

```tsx
"use cache: private"; // For compliance, allows runtime APIs
```

### `cacheLife()` - Custom Lifetime

```tsx
import { cacheLife } from "next/cache";

async function getData() {
  "use cache";
  cacheLife("hours"); // Built-in profile
  return fetch("/api/data");
}
```

Built-in profiles: `'default'`, `'minutes'`, `'hours'`, `'days'`, `'weeks'`, `'max'`

### Inline Configuration

```tsx
async function getData() {
  "use cache";
  cacheLife({
    stale: 3600, // 1 hour - serve stale while revalidating
    revalidate: 7200, // 2 hours - background revalidation interval
    expire: 86400, // 1 day - hard expiration
  });
  return fetch("/api/data");
}
```

---

## Cache Invalidation

### `cacheTag()` - Tag Cached Content

```tsx
import { cacheTag } from "next/cache";

async function getProducts() {
  "use cache";
  cacheTag("products");
  return db.products.findMany();
}

async function getProduct(id: string) {
  "use cache";
  cacheTag("products", `product-${id}`);
  return db.products.findUnique({ where: { id } });
}
```

### `updateTag()` - Immediate Invalidation

Use when you need the cache refreshed within the same request:

```tsx
"use server";

import { updateTag } from "next/cache";

export async function updateProduct(id: string, data: FormData) {
  await db.products.update({ where: { id }, data });
  updateTag(`product-${id}`); // Immediate - same request sees fresh data
}
```

### `revalidateTag()` - Background Revalidation

Use for stale-while-revalidate behavior:

```tsx
"use server";

import { revalidateTag } from "next/cache";

export async function createPost(data: FormData) {
  await db.posts.create({ data });
  revalidateTag("posts"); // Background - next request sees fresh data
}
```

---

## Runtime Data Constraint

**Cannot** access `cookies()`, `headers()`, or `searchParams` inside `use cache`.

### Solution: Pass as Arguments

```tsx
// Wrong - runtime API inside use cache
async function CachedProfile() {
  "use cache";
  const session = (await cookies()).get("session")?.value; // Error!
  return {session};
}

// Correct - extract outside, pass as argument
async function ProfilePage() {
  const session = (await cookies()).get("session")?.value;
  return ;
}

async function CachedProfile({ sessionId }: { sessionId: string }) {
  "use cache";
  // sessionId becomes part of cache key automatically
  const data = await fetchUserData(sessionId);
  return {data.name};
}
```

### Exception: `use cache: private`

For compliance requirements when you can't refactor:

```tsx
async function getData() {
  "use cache: private";
  const session = (await cookies()).get("session")?.value; // Allowed
  return fetchData(session);
}
```

---

## Cache Key Generation

Cache keys are automatic based on:

- **Build ID** - invalidates all caches on deploy
- **Function ID** - hash of function location
- **Serializable arguments** - props become part of key
- **Closure variables** - outer scope values included

```tsx
async function Component({ userId }: { userId: string }) {
  const getData = async (filter: string) => {
    "use cache";
    // Cache key = userId (closure) + filter (argument)
    return fetch(`/api/users/${userId}?filter=${filter}`);
  };
  return getData("active");
}
```

---

## Complete Example

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

export default function DashboardPage() {
  return (
    <>
      {/* Static shell - instant from CDN */}
      
        Dashboard
      
      ...

      {/* Cached - fast, revalidates hourly */}
      

      {/* Dynamic - streams in with fresh data */}
      }>
        
      
    
  );
}

async function Stats() {
  "use cache";
  cacheLife("hours");
  cacheTag("dashboard-stats");

  const stats = await db.stats.aggregate();
  return ;
}

async function Notifications() {
  const userId = (await cookies()).get("userId")?.value;
  const notifications = await db.notifications.findMany({
    where: { userId, read: false },
  });
  return ;
}
```

---

## Migration from Previous Versions

| Old Config                  | Replacement                        |
| --------------------------- | ---------------------------------- |
| `experimental.ppr`          | `cacheComponents: true`            |
| `dynamic = 'force-dynamic'` | Remove (default behavior)          |
| `dynamic = 'force-static'`  | `'use cache'` + `cacheLife('max')` |
| `revalidate = N`            | `cacheLife({ revalidate: N })`     |
| `unstable_cache()`          | `'use cache'` directive            |

### Migrating `unstable_cache` to `use cache`

`unstable_cache` has been replaced by the `use cache` directive in Next.js 16. When `cacheComponents` is enabled, convert `unstable_cache` calls to `use cache` functions:

**Before (`unstable_cache`):**

```tsx
import { unstable_cache } from "next/cache";

const getCachedUser = unstable_cache(async (id) => getUser(id), ["my-app-user"], {
  tags: ["users"],
  revalidate: 60,
});

export default async function Page({ params }: { params: Promise }) {
  const { id } = await params;
  const user = await getCachedUser(id);
  return {user.name};
}
```

**After (`use cache`):**

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

async function getCachedUser(id: string) {
  "use cache";
  cacheTag("users");
  cacheLife({ revalidate: 60 });
  return getUser(id);
}

export default async function Page({ params }: { params: Promise }) {
  const { id } = await params;
  const user = await getCachedUser(id);
  return {user.name};
}
```

Key differences:

- **No manual cache keys** - `use cache` generates keys automatically from function arguments and closures. The `keyParts` array from `unstable_cache` is no longer needed.
- **Tags** - Replace `options.tags` with `cacheTag()` calls inside the function.
- **Revalidation** - Replace `options.revalidate` with `cacheLife({ revalidate: N })` or a built-in profile like `cacheLife('minutes')`.
- **Dynamic data** - `unstable_cache` did not support `cookies()` or `headers()` inside the callback. The same restriction applies to `use cache`, but you can use `'use cache: private'` if needed.

---

## Limitations

- **Edge runtime not supported** - requires Node.js
- **Static export not supported** - needs server
- **Non-deterministic values** (`Math.random()`, `Date.now()`) execute once at build time inside `use cache`

For request-time randomness outside cache:

```tsx
import { connection } from "next/server";

async function DynamicContent() {
  await connection(); // Defer to request time
  const id = crypto.randomUUID(); // Different per request
  return {id};
}
```

Sources:

- [Cache Components Guide](https://nextjs.org/docs/app/getting-started/cache-components)
- [use cache Directive](https://nextjs.org/docs/app/api-reference/directives/use-cache)
- [unstable_cache (legacy)](https://nextjs.org/docs/app/api-reference/functions/unstable_cache)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [LeonardoTrapani](https://github.com/LeonardoTrapani)
- **Source:** [LeonardoTrapani/better-skills](https://github.com/LeonardoTrapani/better-skills)
- **License:** MIT
- **Homepage:** https://better-skills.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-leonardotrapani-better-skills-next-cache-components
- Seller: https://agentstack.voostack.com/s/leonardotrapani
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.