Skip to content

fix: Add useSuspenseQuery replacement rule for Solid docs #9815

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+2 −0
Open

fix: Add useSuspenseQuery replacement rule for Solid docs #9815

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/framework/solid/guides/request-waterfalls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,5 +11,7 @@ replace:
'useQuery[(]': 'useQuery(() => ',
'useQueries[(]': 'useQueries(() => ',
'useInfiniteQuery[(]': 'useInfiniteQuery(() => ',
'useSuspenseQuery': 'useQuery',
'useSuspenseQueries': 'useQueries',
Comment on lines +14 to +15
Copy link
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Verify that replacements produce accurate Solid documentation.

The replacement rules pragmatically map non-existent Solid Query Suspense variants to their standard equivalents. However, the PR objectives note uncertainty about whether React-specific Suspense explanations apply to Solid. After the replacements are applied, the explanatory text may still reference React's Suspense behavior, which could be misleading for Solid users.

Consider whether the documentation body itself (not just function names) needs adjustment to clarify Solid's Suspense semantics.

To verify the documentation renders correctly:

🏁 Script executed:

#!/bin/bash
# Description: Verify that the replacement rules are correctly applied to the documentation

# 1. Locate the React source file that is referenced
REACT_SOURCE="docs/framework/react/guides/request-waterfalls.md"

# 2. Check if the React source file exists
if [[ -f "$REACT_SOURCE" ]]; then
  echo "✓ React source file found: $REACT_SOURCE"
  
  # 3. Verify that useSuspenseQuery and useSuspenseQueries appear in React docs
  echo "Checking for useSuspenseQuery in React docs:"
  rg -n "useSuspenseQuery" "$REACT_SOURCE"
  
  echo "Checking for useSuspenseQueries in React docs:"
  rg -n "useSuspenseQueries" "$REACT_SOURCE"
else
  echo "✗ React source file not found: $REACT_SOURCE"
fi

# 4. Check the Solid docs frontmatter to ensure the replacements are defined
echo "Verifying Solid replacement rules are in place:"
rg -A 2 "useSuspenseQuery.*useQuery" docs/framework/solid/guides/request-waterfalls.md
rg -A 2 "useSuspenseQueries.*useQueries" docs/framework/solid/guides/request-waterfalls.md

Length of output: 1219

I need to examine the explanation text in the React source to assess whether the semantic content remains accurate after the replacements are applied.

Documentation replacement rules are pragmatic but require content review for semantic accuracy.

The replacement rules correctly map non-existent Solid Query variants to their equivalents. However, Solid Query uses Solid's Suspense API differently—wrapping components with a Suspense component and using an async suspense function from solid-query, rather than separate hook variants like React's useSuspenseQuery.

After replacements are applied, explanatory text (e.g., "use useQuery when...") will become misleading because it describes Solid's standard useQuery hook without clarifying the Suspense-specific setup that Solid Query actually requires. Verify that the documentation body is manually adjusted to explain Solid's Suspense pattern rather than simply relying on function name replacements.

🤖 Prompt for AI Agents 
In docs/framework/solid/guides/request-waterfalls.md around lines 14-15, the
automated replacement mapping 'useSuspenseQuery'→'useQuery' and
'useSuspenseQueries'→'useQueries' leaves explanatory text inaccurate for Solid:
Solid Query requires using Solid's Suspense component and the library's
async-suspense helpers (not React-style suspense hooks). Update the prose to
explain Solid's pattern — describe wrapping components with <Suspense>, using
solid-query's async suspense API (or async wrappers) and how to use
useQuery/useQueries within that pattern — and remove or reword any guidance that
implies React-style "useSuspense*" hooks exist.

}
---