Skip to content

Unify caching story across the docs#90149

Merged
delbaoliveira merged 28 commits intocanaryfrom
docs-unify-caching-story
Mar 3, 2026
Merged

Unify caching story across the docs#90149
delbaoliveira merged 28 commits intocanaryfrom
docs-unify-caching-story

Conversation

@delbaoliveira
Copy link
Collaborator

@delbaoliveira delbaoliveira commented Feb 18, 2026

This PRs unifies the caching story across the docs, making Cache Components the happy path, while still providing guidance to users in the old model. However, instead of explaining the old model and its caching layers, we've created a new guide focusing on what APIs to use and when.

This follow-up PR aligns terminology across the docs: #90589

IA updates

Getting Started section:

  • Improves Getting Started progression:
    • Before: CC → Fetching Data → Updating Data → Caching and Revalidating (old and new model mixed)
    • After: Fetching Data (Dynamic) → Mutating Data (Dynamic) → Caching with CC (Prerendering) → Revalidating with CC.
  • New: caching.mdx (CC-first)
    • Structure:
      • Enabling Cache Components
      • Data vs UI-level caching
      • Working with request time APIs
      • Passing request values to cached functions
      • Working with non-deterministic operations
      • Working with synchronous operations
      • How rendering works (PPR and static shell story)
  • New: revalidating.mdx (CC-first)
    • Explains how to use cacheLife and cacheTag

Guides Section:

  • New: caching-and-revalidating.mdx (Previous Model)
    • For users who are not using CC, includes fetch options and route segment config
    • Moves route segment config options that don't apply to CC from API reference to this guide (for easy archiving in the future).
  • New: migrating-to-cache-components.mdx (WIP)
  • Del: caching.mdx 😌

Terminology

We should remove caching layers from the docs. Users only needed to be exposed to them when they were configured independently, but the new CC APIs work across layers.

To make it easier to review this PR, I'm consolidating terminology and fixing broken links in a new PR: #90589

@nextjs-bot nextjs-bot added created-by: Next.js DevEx team PRs by the DX team. Documentation Related to Next.js' official documentation. labels Feb 18, 2026
@github-actions
Copy link
Contributor

github-actions bot commented Feb 18, 2026

All broken links are now fixed, thank you!

@delbaoliveira delbaoliveira marked this pull request as ready for review February 19, 2026 15:05
@delbaoliveira delbaoliveira changed the title WIP: Unify caching story across the docs Unify caching story across the docs Feb 19, 2026
delbaoliveira and others added 9 commits February 26, 2026 13:26
**Terminology:**

- Dynamic APIs → Request-time APIs (explicit, this APIs that access
request information)
- Dynamic Data → Uncached data (data is either cached or uncached,
reserve dynamic for rendering)
- Pre-rendering → Prerendering
- Prefer prerendering over static rendering where possible. This aligns
with better with Partial Prerendering.
- Prefer dynamic rendering over runtime/request-time rendering (it's a
well established term and it just sounds better)
- Dropped caching layers: 
   - Router Cache
   - Full Route Cache
   - React Cache
   - Client Router Cache
- Caching layers become: **Client cache** and **Server cache**. The new
Cache Component APIs work across caching layers and are not configured
independently, allowing us to simplify the story.


**Other fixes:**
- Run docs through Vercel style guide
- Fixed broken links

---------

Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
delbaoliveira and others added 5 commits March 3, 2026 08:04
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
…anifest.mdx

Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Copy link
Collaborator

@icyJoseph icyJoseph left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LFG

@delbaoliveira delbaoliveira merged commit c2b4c08 into canary Mar 3, 2026
72 checks passed
@delbaoliveira delbaoliveira deleted the docs-unify-caching-story branch March 3, 2026 13:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

created-by: Next.js DevEx team PRs by the DX team. Documentation Related to Next.js' official documentation.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants