From 11fcb72b42f21541a008a9ea723d56179c8c58bd Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Fri, 19 Jun 2026 17:05:48 +0000
Subject: [PATCH] docs(Suspense): warn against module-level cache in SSR

Add a Pitfall on the Suspense reference page explaining that the
hidden data.js cache must not be copied into server environments like
Next.js, where module-level state can leak data across requests.

Clarify the data.js comment in all Suspense examples accordingly.

Fixes reactjs/react.dev#8134
---
 src/content/reference/react/Suspense.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/src/content/reference/react/Suspense.md b/src/content/reference/react/Suspense.md
index c2fc0b6ef55..8a3c1e29b66 100644
--- a/src/content/reference/react/Suspense.md
+++ b/src/content/reference/react/Suspense.md
@@ -52,6 +52,12 @@ React will display your <CodeStep step={1}>loading fallback</CodeStep> until all
 
 In the example below, the `Albums` component *suspends* while fetching the list of albums. Until it's ready to render, React switches the closest Suspense boundary above to show the fallback--your `Loading` component. Then, when the data loads, React hides the `Loading` fallback and renders the `Albums` component with data.
 
+<Pitfall>
+
+Do not use a module-level cache like the one in `data.js` below in server environments such as Next.js. Module-level state persists across requests and can leak data between users. Use your framework's built-in caching, [`cache`](/reference/react/cache) in Server Components, or scope caches per request (for example, with a Context and `useRef`).
+
+</Pitfall>
+
 <Sandpack>
 
 ```js src/App.js hidden
@@ -121,6 +127,8 @@ export default function Albums({ artistId }) {
 // Note: the way you would do data fetching depends on
 // the framework that you use together with Suspense.
 // Normally, the caching logic would be inside a framework.
+// This module-level cache is only suitable for this client-only demo.
+// Do not copy it into server environments.
 
 let cache = new Map();
 
@@ -336,6 +344,8 @@ export default function Albums({ artistId }) {
 // Note: the way you would do data fetching depends on
 // the framework that you use together with Suspense.
 // Normally, the caching logic would be inside a framework.
+// This module-level cache is only suitable for this client-only demo.
+// Do not copy it into server environments.
 
 let cache = new Map();
 
@@ -598,6 +608,8 @@ export default function Albums({ artistId }) {
 // Note: the way you would do data fetching depends on
 // the framework that you use together with Suspense.
 // Normally, the caching logic would be inside a framework.
+// This module-level cache is only suitable for this client-only demo.
+// Do not copy it into server environments.
 
 let cache = new Map();
 
@@ -782,6 +794,8 @@ export default function SearchResults({ query }) {
 // Note: the way you would do data fetching depends on
 // the framework that you use together with Suspense.
 // Normally, the caching logic would be inside a framework.
+// This module-level cache is only suitable for this client-only demo.
+// Do not copy it into server environments.
 
 let cache = new Map();
 
@@ -966,6 +980,8 @@ export default function SearchResults({ query }) {
 // Note: the way you would do data fetching depends on
 // the framework that you use together with Suspense.
 // Normally, the caching logic would be inside a framework.
+// This module-level cache is only suitable for this client-only demo.
+// Do not copy it into server environments.
 
 let cache = new Map();
 
@@ -1225,6 +1241,8 @@ export default function Panel({ children }) {
 // Note: the way you would do data fetching depends on
 // the framework that you use together with Suspense.
 // Normally, the caching logic would be inside a framework.
+// This module-level cache is only suitable for this client-only demo.
+// Do not copy it into server environments.
 
 let cache = new Map();
 
@@ -1537,6 +1555,8 @@ export default function Panel({ children }) {
 // Note: the way you would do data fetching depends on
 // the framework that you use together with Suspense.
 // Normally, the caching logic would be inside a framework.
+// This module-level cache is only suitable for this client-only demo.
+// Do not copy it into server environments.
 
 let cache = new Map();
 
@@ -1848,6 +1868,8 @@ export default function Panel({ children }) {
 // Note: the way you would do data fetching depends on
 // the framework that you use together with Suspense.
 // Normally, the caching logic would be inside a framework.
+// This module-level cache is only suitable for this client-only demo.
+// Do not copy it into server environments.
 
 let cache = new Map();