docs: enhance documentation for Nuxt composables #32218
Conversation
Contributes to nuxt#30930
|
|
There was a problem hiding this comment.
Pull Request Overview
This pull request updates and enhances the documentation for several Nuxt composables. The changes include restructured parameter and return value sections, updated examples, and improved clarity in the documentation across four files.
- Enhanced documentation for useFetch with parameter and return value tables.
- Revised usage and type definitions for useError.
- Updated examples and expanded details for useCookie.
- Clarified the usage of onPrehydrate with improved type signatures and advanced key options.
Reviewed Changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/3.api/2.composables/use-fetch.md | Reorganized Parameters and Return Values sections with a new table format. |
| docs/3.api/2.composables/use-error.md | Improved wording and type definitions with added Usage and Type sections. |
| docs/3.api/2.composables/use-cookie.md | Updated document structure with clearer examples and parameter tables. |
| docs/3.api/2.composables/on-prehydrate.md | Revised language and type annotations to clarify prehydrate usage. |
| } | ||
|
|
||
| type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error' | ||
| ``` | ||
|
|
||
| ## Parameters |
There was a problem hiding this comment.
Consider adding a brief introductory sentence immediately before the Parameters section to explain the role of the parameters and how they affect the fetch behavior, which may help users quickly understand what to configure.
Copilot uses AI. Check for mistakes.
|
|
||
| ```ts | ||
| interface { | ||
| // HTTP response status code | ||
| interface NuxtError<DataT = unknown> { |
There was a problem hiding this comment.
[nitpick] Consider adding brief inline comments for the optional 'data' and 'error' fields within the NuxtError interface to further clarify their intended usage.
Copilot uses AI. Check for mistakes.
|
|
||
| Cookie composable accepts several options which let you modify the behavior of cookies. | ||
| `options`: Options to control cookie behavior. The object can have the following properties: |
There was a problem hiding this comment.
[nitpick] Consider explicitly stating that each option supports static values, refs, or computed values to reinforce the composable’s reactivity features.
Copilot uses AI. Check for mistakes.
| ::note | ||
| This is an advanced utility and should be used with care. For example, [`nuxt-time`](https://github.com/danielroe/nuxt-time/pull/251) and [`@nuxtjs/color-mode`](https://github.com/nuxt-modules/color-mode/blob/main/src/script.js) manipulate the DOM to avoid hydration mismatches. | ||
| :: | ||
|
|
||
| ## Usage | ||
|
|
||
| `onPrehydrate` can be called directly in the setup function of a Vue component (for example, in `<script setup>`), or in a plugin. | ||
| It will only have an effect when it is called on the server, and it will not be included in your client build. | ||
| Call `onPrehydrate` in the setup function of a Vue component (e.g., in `<script setup>`) or in a plugin. It only has an effect when called on the server and will not be included in your client build. |
There was a problem hiding this comment.
[nitpick] Consider adding a note that the provided callback should avoid external dependencies as reiterated later, to prevent unexpected behavior before the Nuxt runtime initializes.
Copilot uses AI. Check for mistakes.
|
Warning Rate limit exceeded@danielroe has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 3 minutes and 56 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (3)
WalkthroughThe documentation for several composable functions was revised to enhance clarity, detail, and structure. The ✨ Finishing Touches🧪 Generate Unit Tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/3.api/2.composables/on-prehydrate.md (2)
26-29: Refine TypeScript overload signatures.
Consider making the second overload’s return type strictlystringand requiring thekeyparameter to avoid overload ambiguity. For example:export function onPrehydrate(callback: (el: HTMLElement) => void): void; export function onPrehydrate(callback: string | ((el: HTMLElement) => void), key: string): string;
49-52: Clarify example comment wording.
To explicitly indicate client-side prehydrate execution, consider rephrasing:- // Run code before Nuxt hydrates + // Run this callback on the client immediately before hydration
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/3.api/2.composables/on-prehydrate.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/3.api/2.composables/on-prehydrate.md
[uncategorized] ~15-~15: Loose punctuation mark.
Context: ...ediately before Nuxt hydrates the page. ::note This is an advanced utility and sh...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~17-~17: Loose punctuation mark.
Context: ... the DOM to avoid hydration mismatches. :: ## Usage Call onPrehydrate in the ...
(UNLIKELY_OPENING_PUNCTUATION)
🔇 Additional comments (5)
docs/3.api/2.composables/on-prehydrate.md (5)
15-15: Concise hook description.
The one-line overview clearly explains the purpose ofonPrehydrate.🧰 Tools
🪛 LanguageTool
[uncategorized] ~15-~15: Loose punctuation mark.
Context: ...ediately before Nuxt hydrates the page. ::note This is an advanced utility and sh...(UNLIKELY_OPENING_PUNCTUATION)
22-22: Usage section is precise.
It correctly notes server-side registration and exclusion from the client bundle.
33-37: Parameter table is comprehensive and clear.
The descriptions clearly state the requirements and limitations for bothcallbackandkey. Nice work!
54-58: Example for root element access is clear.
The snippet effectively demonstrates how to inspect the element passed to the callback.
60-60: Advanced usage note is helpful.
The comment appropriately signals the advanced nature of manually handling thedata-prehydrate-id.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/3.api/2.composables/use-cookie.md (1)
57-71: Re-emphasise that option values can be static or reactiveIt is still not obvious that every property in the options object may be passed as a static literal or as a
ref/computedfor full reactivity at runtime. An explicit sentence (as suggested previously) would avoid any ambiguity for newcomers.
🧹 Nitpick comments (2)
docs/3.api/2.composables/use-cookie.md (2)
90-96: Avoid implicit ref reassignment in the template snippet
counteris aRef, and Vue’s template compiler rewritescounter++/counter = nulltocounter.value++/counter.value = nullinternally.
That magic is handy, but showing the explicit.valueaccess keeps the example unambiguous for readers who copy-paste the code into plain JS/TS (e.g. inside composables or composable helpers) where the rewrite does not happen.-<button @click="counter = null">reset</button> -<button @click="counter--">-</button> -<button @click="counter++">+</button> +<button @click="counter.value = null">reset</button> +<button @click="counter.value--">-</button> +<button @click="counter.value++">+</button>
62-62: Minor grammar – add a hyphen to “top-level”- i.e. data changes for only top level properties + i.e. data changes for only top-level properties
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/3.api/2.composables/use-cookie.md(5 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/3.api/2.composables/use-cookie.md
[uncategorized] ~24-~24: Loose punctuation mark.
Context: ... and deserialize cookie values to JSON. :: # Type ```ts [Signature] import type...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~51-~51: Loose punctuation mark.
Context: ...: CookieRef ``` # Parameters name: The name of the cookie. `options`: Opt...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~53-~53: Loose punctuation mark.
Context: ...ame: The name of the cookie. options`: Options to control cookie behavior. The...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~62-~62: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...allow watch, i.e. data changes for only top level properties, false to disable.
*...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[uncategorized] ~62-~62: A punctuation mark might be missing here.
Context: ...manually when a cookie has changed with [refreshCookie](/docs/api/utils/refresh-...
(AI_EN_LECTOR_MISSING_PUNCTUATION)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: lint-docs
🔗 Linked issue
Contributes to #30930
📚 Description
Improving the documentation for a few Nuxt composables according to the discussion at #30930