[Suggestion]: Clarification on react.cache Usage in Server Requests

[saengmotmi]

Summary

The use of the term "each server request" in the react.cache API documentation is ambiguous, potentially leading to confusion between React Server Components (RSC) and Server-Side Rendering (SSR). This ambiguity may result in a lower understanding of how react.cache operates and when cache expiration occurs.

Page

https://react.dev/reference/react/cache#caveats

Details

Hi, React Team,

While reading through the documentation, I came across the phrase "each server request" and found myself pausing to consider its implications. The term seems to encompass a broad range of server interactions, yet I believe it might be more beneficial to specify "each RSC server request" to distinguish it clearly from general SSR scenarios.

Many of us in the React community, especially those less familiar with server-side mechanisms like RSC, might inadvertently equate "server requests" with the typical requests sent to an SSR server. This could lead to some confusion about when and how cache expiration happens, particularly since react.cache is designed to work within the RSC server context, where each request is akin to a single rendering instance.

It's clear that react.cache plays a crucial role within the RSC environment, akin to how Next.js operates with its external server handling traditional SSR requests and an internal server dedicated to RSC rendering. This dual-server setup made me realize that react.cache is essentially functioning within this confined RSC server space. Given this setup, the concept of cache expiration becomes less conventional, akin to a closure in JavaScript where variables are bound to the function scope and are discarded once the execution context ends.

This analogy to closures might resonate well with developers, highlighting how react.cache retains data within the scope of a single RSC request and discards it afterward, similar to how a closure behaves. This perspective could add a layer of understanding to the documentation, making the concept more relatable and easier to grasp, especially for those familiar with the nuances of JavaScript closures.

I understand the importance of keeping the documentation agnostic to specific implementations like Next.js. However, as React continues to evolve and possibly embrace framework-based tools more closely, clarifying these nuances could prove invaluable, not just for Next.js developers but for all of us looking to harness the full potential of RSC and similar technologies.

It's with this in mind that I suggest a slight revision or an additional note in the documentation to help demystify the workings of react.cache within the RSC context. Such an update could greatly aid in alleviating any confusion and ensure a smoother development experience for the community.

Thank you for considering my input. I deeply appreciate the hard work and dedication that goes into maintaining the React documentation, and I'm eager to contribute in any way I can.