docs: clarify usage of await with useFetch #33745

Fuzzyma · 2025-11-22T13:31:24Z

Explain the pros and cons of awaiting useFetch

🔗 Linked issue

Well, just a discussion:
#33736 (reply in thread)

📚 Description

useFetch does not need to be awaited. It sometimes might even lead to better UX not to await it.
However, the docs only ever show useFetch being awaited and dont explain the implications.

Therefore I added a note explaining it a bit more.
Maybe we should put another note on useAsyncData?

Explain the pros and cons of awaiting useFetch

bolt-new-by-stackblitz · 2025-11-22T13:31:27Z

Run & review this pull request in StackBlitz Codeflow.

coderabbitai · 2025-11-22T13:34:08Z

Walkthrough

This change updates the useFetch documentation to clarify usage and runtime behaviour. It adds notes that awaiting useFetch is not required for SSR (Nuxt will await the underlying promise) and that omitting await changes client‑side behaviour (immediate navigation and manual loading state management). It clarifies that data, status, and error are Vue refs accessed via .value in script setup, while refresh/execute and clear are plain functions. Note blocks were inserted adjacent to existing usage/warning sections. No public API or behavioural changes were made.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

Documentation-only change; no code or API modifications.
Review focus:
- Verify factual accuracy of the new notes (SSR awaiting, client behaviour).
- Check clarity and correct placement of note blocks in the docs.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding documentation to clarify usage of await with useFetch, which directly matches the changeset.
Description check	✅ Passed	The description is directly related to the changeset, explaining why the documentation note was added and the context from a GitHub discussion, with clear rationale for the change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 74fb5d5 and 7ea4a87.

📒 Files selected for processing (1)

docs/4.api/2.composables/use-fetch.md (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-09-10T14:42:56.647Z

Learnt from: Tofandel
Repo: nuxt/nuxt PR: 33192
File: test/nuxt/use-async-data.test.ts:366-373
Timestamp: 2025-09-10T14:42:56.647Z
Learning: In the Nuxt useAsyncData test "should watch params deeply in a non synchronous way", the foo watcher intentionally updates both params.foo and params.locale using locale.value, simulating a scenario where one watcher consolidates multiple reactive values into a shared params object for testing debounced/non-synchronous behavior.

Applied to files:

docs/4.api/2.composables/use-fetch.md

🪛 LanguageTool

docs/4.api/2.composables/use-fetch.md

[uncategorized] ~34-~34: Loose punctuation mark.
Context: ...or your app but also means more effort. :: ::note data, status, and error ...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~36-~36: Loose punctuation mark.
Context: ...our app but also means more effort. :: ::note data, status, and error are ...

(UNLIKELY_OPENING_PUNCTUATION)

🔇 Additional comments (3)

docs/4.api/2.composables/use-fetch.md (3)

32-35: Excellent clarification on await behaviour.

The new note effectively explains that awaiting useFetch is optional and clarifies the behavioural differences between awaiting and not awaiting on both server and client sides. The guidance about UX trade-offs is practical and helpful for developers making this decision.

37-39: Helpful complementary note.

This note appropriately clarifies how to access the reactive values returned from useFetch, which is important context regardless of whether developers choose to await or not.

1-254: Documentation enhancement is clear and well-positioned.

The changes successfully address the PR objectives by clarifying that useFetch does not require awaiting and explaining the trade-offs between awaited and non-awaited usage patterns. The new note (lines 32–35) is well-placed within the documentation flow and complements the existing warning about custom useFetch wrappers. The writing is clear and actionable for developers.

The static analysis warnings about "loose punctuation" are false positives related to the :: markdown syntax for note blocks, which is standard in Nuxt documentation.

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

Provide your own instructions using the high_level_summary_instructions setting.
Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

📝 Description — Summarize the main change in 50–60 words, explaining what was done.

📓 References — List relevant issues, discussions, documentation, or related PRs.

📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.

📊 Contributor Summary — Include a Markdown table showing contributions:
| Contributor | Lines Added | Lines Removed | Files Changed |

✔️ Additional Notes — Add any extra reviewer context.
Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs/4.api/2.composables/use-fetch.md (1)
32-35: Add a comma in the compound sentence for clarity.

Line 34 contains a compound sentence that would benefit from a comma before the second independent clause for proper punctuation and readability.

Apply this diff:
-If you omit the `await`, navigation will happen immediately and you will have to handle loading states on your own. This will usually result in a better UX for your app but also means more effort.
+If you omit the `await`, navigation will happen immediately, and you will have to handle loading states on your own. This will usually result in a better UX for your app but also means more effort.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ffa14fe and 74fb5d5.

📒 Files selected for processing (1)

docs/4.api/2.composables/use-fetch.md (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-09-10T14:42:56.647Z

Learnt from: Tofandel
Repo: nuxt/nuxt PR: 33192
File: test/nuxt/use-async-data.test.ts:366-373
Timestamp: 2025-09-10T14:42:56.647Z
Learning: In the Nuxt useAsyncData test "should watch params deeply in a non synchronous way", the foo watcher intentionally updates both params.foo and params.locale using locale.value, simulating a scenario where one watcher consolidates multiple reactive values into a shared params object for testing debounced/non-synchronous behavior.

Applied to files:

docs/4.api/2.composables/use-fetch.md

🪛 LanguageTool

docs/4.api/2.composables/use-fetch.md

[uncategorized] ~34-~34: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...ait`, navigation will happen immediately and you will have to handle loading states ...

(COMMA_COMPOUND_SENTENCE)

[uncategorized] ~34-~34: Loose punctuation mark.
Context: ...or your app but also means more effort. :: ::note data, status, and error ...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~36-~36: Loose punctuation mark.
Context: ...our app but also means more effort. :: ::note data, status, and error are ...

(UNLIKELY_OPENING_PUNCTUATION)

🔇 Additional comments (1)

docs/4.api/2.composables/use-fetch.md (1)

32-39: Well-structured documentation clarifying awaiting behaviour.

The new note block directly addresses the gap in documentation regarding whether useFetch must be awaited. The explanation of the trade-off—improved UX through immediate navigation versus requiring manual loading state management—clearly communicates the implications of both patterns. The placement logically follows the custom wrapper warning and precedes the ref access clarification, making the flow coherent.

atinux · 2025-12-01T22:43:41Z

I would also add this note on useAsyncData 👍

ineshbose · 2025-12-16T14:57:34Z

I would also add this note on useAsyncData 👍

Yes - this note may be better suited as a section on https://nuxt.com/docs/4.x/getting-started/data-fetching and it can also tie into usage of NuxtLoadingIndicator.

Clarify usage of await with use-fetch

74fb5d5

Explain the pros and cons of awaiting useFetch

Fuzzyma requested a review from danielroe as a code owner November 22, 2025 13:31

github-actions bot added 4.x documentation labels Nov 22, 2025

coderabbitai bot reviewed Nov 22, 2025

View reviewed changes

docs: fix nitpick feedback from bot

7ea4a87

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

docs: clarify usage of await with useFetch #33745

docs: clarify usage of await with useFetch #33745

Uh oh!

Fuzzyma commented Nov 22, 2025

Uh oh!

bolt-new-by-stackblitz bot commented Nov 22, 2025

Uh oh!

coderabbitai bot commented Nov 22, 2025 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

atinux commented Dec 1, 2025

Uh oh!

ineshbose commented Dec 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

docs: clarify usage of await with useFetch #33745

Are you sure you want to change the base?

docs: clarify usage of await with useFetch #33745

Uh oh!

Conversation

Fuzzyma commented Nov 22, 2025

🔗 Linked issue

📚 Description

Uh oh!

bolt-new-by-stackblitz bot commented Nov 22, 2025

Uh oh!

coderabbitai bot commented Nov 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Estimated code review effort

Pre-merge checks and finishing touches

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

atinux commented Dec 1, 2025

Uh oh!

ineshbose commented Dec 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

coderabbitai bot commented Nov 22, 2025 •

edited

Loading