Docs: Document caching mechanisms

[delbaoliveira]

This PR document the caching semantics in Next.js, how they interact, and what APIs affect them. We're also taking the opportunity to consolidate terminology, remove duplicate content, and update sections of the docs that relate to caching.

Documentation

• Create a new section for caching
• Explain how the different caching mechanisms work
  • Request Memoization (React Cache)
  • Persistent Data Cache
  • Persistent Full Route Cache
  • In-memory, client-side Router Cache
• Document how different APIs affect caching
• Document cache interactions
• Clean up stale information in the other docs sections
  • Routing Section
    • Move advanced navigation topics from fundamentals to How Navigation Works section
    • Rewrite the How Navigation Works section
  • Rendering Section
    • Simplify fundamentals page
    • Rewrite the Static and Dynamic Rendering pages
    • Create a page to explain how Client and Server Components are rendered. Moved to this PR: docs: Rewrite Rendering Section and React Essentials Page #51579
  • Data fetching section
    • Consolidate data fetching story for fetching, caching, and revalidating
    • Clarify data fetching story with 3rd party libraries and React cache
    • Create Data Fetching Patterns page
• Document other related behaviors:
  • Update information on scroll position for back/forward navigation
  • Remove the concepts of soft and hard navigation
  • Remove the concepts of static and dynamic data fetching
  • Use consistent terminology runtime 👉🏼 request time. Runtime for Edge and Node.js, request time to describe when dynamic stuff happens
  • generateStaticParams being able to seed the Full Route Cache
• Polish 💅🏼

---

Related PRs:

• Diagrams: https://github.com/vercel/front/pull/24142
• Redirects: https://github.com/vercel/front/pull/24179

[koichik]

@delbaoliveira Thanks for your great work! Could you please take a look at #52069?

[delbaoliveira]

Need to verify if these cases are correct

[delbaoliveira]

Thank you @manovotny, @TkDodo and @alvarlagerlof for the feedback! 🙏🏼

[IGassmann]

Looking forward to reading these! :)

[takefumi-yoshii]

It's also worth mentioning the Data Cache created by next dev.The Data Cache is a constant source of confusion during development.It's good to mention that .next/cache files needs to be removed explicitly.

[koichik]

@delbaoliveira 🎉🎉🎉🎉🎉🎉Congrats Marge!🎉🎉🎉🎉🎉🎉
What an unbelievable work!

I was able to see the diagram now, but I think the React Memoization and the Data Cache positions are inverted.

https://nextjs.org/_next/image?url=%2Fdocs%2Flight%2Fcaching-overview.png&w=1920&q=75&dpl=dpl_6jEE2o8UhNfkbiXNT6wnDf4UwJwt
https://nextjs.org/_next/image?url=%2Fdocs%2Flight%2Frequest-memoization.png&w=1920&q=75&dpl=dpl_6jEE2o8UhNfkbiXNT6wnDf4UwJwt

In fact, the Next.js' fetch is applied first, then the React's fetch applied only if the Data Cache misses.
Should I file a new issue?

[delbaoliveira]

Hey @koichik,

Thank you!

I hear your point about the implementation order. This is the limitation with a 2d graphic, I think it is slightly more important to show that Request Memoization is on the rendering server and the Data Cache is on a separate network. We have a similar challenge visualizing an initial visit request passing through the client-side Router Cache even though it wouldn't exist yet.