From 39b26e67498965f0114df67861c8a9d87c0a6a29 Mon Sep 17 00:00:00 2001 From: Maxwell Cohen Date: Wed, 24 Jun 2026 21:55:16 -0500 Subject: [PATCH 1/9] fix: update use.md pitfall to mention that bypassing use can corrupt React's internal state tracking --- src/content/reference/react/use.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index 0fc152c7fb1..3914ff5e8c3 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -662,10 +662,10 @@ This cache pattern is the foundation for [re-fetching data](#re-fetching-data-in -Don't conditionally call `use` based on whether a Promise is settled. Always call `use` unconditionally and let React handle reading the `status` field. This ensures React DevTools can show that the component may suspend on data. +Don't skip calling `use` based on whether a Promise is already settled. Unlike other hooks, `use` can be called inside conditions and loops — but it must always be called for the Promise itself. Never read `promise.status` or `promise.value` directly to bypass `use`; always pass the Promise to `use` and let React handle it. Bypassing `use` this way can corrupt React's internal state tracking, causing stale renders, missed updates, or incorrect Suspense behavior. This also ensures React DevTools can show that the component may suspend on data. ```js -// 🔴 Don't conditionally skip `use` +// 🔴 Don't bypass `use` by reading promise status directly if (promise.status === 'fulfilled') { return promise.value; } @@ -673,7 +673,7 @@ const value = use(promise); ``` ```js -// ✅ Always call `use` unconditionally +// ✅ Always pass the promise to `use` and let React track promise readiness const value = use(promise); ``` From 86037a509422ed3d92ce1dc3d779c0301739c1e9 Mon Sep 17 00:00:00 2001 From: Ricky Date: Thu, 25 Jun 2026 02:04:19 -0400 Subject: [PATCH 2/9] Apply suggestion from @rickhanlonii --- src/content/reference/react/use.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index 3914ff5e8c3..c8925e0274a 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -662,7 +662,11 @@ This cache pattern is the foundation for [re-fetching data](#re-fetching-data-in -Don't skip calling `use` based on whether a Promise is already settled. Unlike other hooks, `use` can be called inside conditions and loops — but it must always be called for the Promise itself. Never read `promise.status` or `promise.value` directly to bypass `use`; always pass the Promise to `use` and let React handle it. Bypassing `use` this way can corrupt React's internal state tracking, causing stale renders, missed updates, or incorrect Suspense behavior. This also ensures React DevTools can show that the component may suspend on data. +Don't skip calling `use` based on whether a Promise is already settled. + +Unlike other hooks, `use` can be called inside conditions and loops — but it must always be called for the Promise itself. Never read `promise.status` or `promise.value` directly to bypass `use`; always pass the Promise to `use` and let React handle it. + +Bypassing `use` this way can corrupt React's internal state tracking, and breaks React DevTools suspense data tracking: ```js // 🔴 Don't bypass `use` by reading promise status directly From d34d0035a0e5e8683c3c9f5de9d8cca6d6bc588b Mon Sep 17 00:00:00 2001 From: Ricky Date: Thu, 25 Jun 2026 02:05:20 -0400 Subject: [PATCH 3/9] Apply suggestion from @rickhanlonii --- src/content/reference/react/use.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index c8925e0274a..3bc298ada8f 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -677,7 +677,7 @@ const value = use(promise); ``` ```js -// ✅ Always pass the promise to `use` and let React track promise readiness +// ✅ Pass the promise to `use` and let React track the promise const value = use(promise); ``` From e53fc7ba5e2f8124d438096b18742c2ff665a124 Mon Sep 17 00:00:00 2001 From: Ricky Date: Thu, 25 Jun 2026 02:11:45 -0400 Subject: [PATCH 4/9] Apply suggestion from @rickhanlonii --- src/content/reference/react/use.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index 3bc298ada8f..f299799c85e 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -666,7 +666,6 @@ Don't skip calling `use` based on whether a Promise is already settled. Unlike other hooks, `use` can be called inside conditions and loops — but it must always be called for the Promise itself. Never read `promise.status` or `promise.value` directly to bypass `use`; always pass the Promise to `use` and let React handle it. -Bypassing `use` this way can corrupt React's internal state tracking, and breaks React DevTools suspense data tracking: ```js // 🔴 Don't bypass `use` by reading promise status directly From ff82da9dbbb0083788f9fe7cee5b1dc99954f61c Mon Sep 17 00:00:00 2001 From: Ricky Date: Thu, 25 Jun 2026 02:13:28 -0400 Subject: [PATCH 5/9] Apply suggestion from @rickhanlonii --- src/content/reference/react/use.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index f299799c85e..8f70ca0e257 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -678,7 +678,6 @@ const value = use(promise); ```js // ✅ Pass the promise to `use` and let React track the promise const value = use(promise); -``` From 367831de1310f8a391af56f1d20d05ca8496932b Mon Sep 17 00:00:00 2001 From: Ricky Date: Thu, 25 Jun 2026 02:17:07 -0400 Subject: [PATCH 6/9] Update use.md with caution on bypassing `use` Add warning about bypassing `use` and its effects on React Suspense. --- src/content/reference/react/use.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index 8f70ca0e257..d9c25b1c9a0 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -678,6 +678,9 @@ const value = use(promise); ```js // ✅ Pass the promise to `use` and let React track the promise const value = use(promise); +``` + +Bypassing `use` this way can break React Suspense optimizations and Suspense features for React DevTools. You can `use(promise)` conditionally, but don't conditionally `use(promise)` based on the promise itself. From 500dbba0b86d839b4ab1a51706a53598740fb289 Mon Sep 17 00:00:00 2001 From: Ricky Date: Thu, 25 Jun 2026 02:19:51 -0400 Subject: [PATCH 7/9] Apply suggestion from @rickhanlonii --- src/content/reference/react/use.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index d9c25b1c9a0..30f470e1d52 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -663,7 +663,6 @@ This cache pattern is the foundation for [re-fetching data](#re-fetching-data-in Don't skip calling `use` based on whether a Promise is already settled. - Unlike other hooks, `use` can be called inside conditions and loops — but it must always be called for the Promise itself. Never read `promise.status` or `promise.value` directly to bypass `use`; always pass the Promise to `use` and let React handle it. From d18c73acb8df0433ad7699968fd743ea523fc8d8 Mon Sep 17 00:00:00 2001 From: Ricky Date: Thu, 25 Jun 2026 02:27:41 -0400 Subject: [PATCH 8/9] Update guidance on using the `use` hook with Promises Clarify usage of `use` hook regarding Promise handling. --- src/content/reference/react/use.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index 30f470e1d52..e2f80d8e47a 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -662,7 +662,8 @@ This cache pattern is the foundation for [re-fetching data](#re-fetching-data-in -Don't skip calling `use` based on whether a Promise is already settled. +Don't skip calling `use` based on whether a Promise is already settled. + Unlike other hooks, `use` can be called inside conditions and loops — but it must always be called for the Promise itself. Never read `promise.status` or `promise.value` directly to bypass `use`; always pass the Promise to `use` and let React handle it. From 6e953e044e2cdf198f8786bbdcf74bcf66863edd Mon Sep 17 00:00:00 2001 From: Ricky Date: Thu, 25 Jun 2026 02:30:02 -0400 Subject: [PATCH 9/9] Clarify usage of `use` with Promises --- src/content/reference/react/use.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md index e2f80d8e47a..1780f82e7b5 100644 --- a/src/content/reference/react/use.md +++ b/src/content/reference/react/use.md @@ -664,7 +664,7 @@ This cache pattern is the foundation for [re-fetching data](#re-fetching-data-in Don't skip calling `use` based on whether a Promise is already settled. -Unlike other hooks, `use` can be called inside conditions and loops — but it must always be called for the Promise itself. Never read `promise.status` or `promise.value` directly to bypass `use`; always pass the Promise to `use` and let React handle it. +Unlike other hooks, `use` can be called inside conditions and loops — but it must always be called for the Promise itself. Never read `promise.status` or `promise.value` directly to bypass `use`; always pass the Promise to `use` and let React handle it. ```js