docs: enhance documentation for Nuxt composables #33626

peterbud · 2025-11-01T13:31:03Z

🔗 Linked issue

Contributes to #30930

📚 Description

Improving the documentation for a few Nuxt composables according to the discussion at #30930

bolt-new-by-stackblitz · 2025-11-01T13:31:06Z

Run & review this pull request in StackBlitz Codeflow.

coderabbitai · 2025-11-01T13:32:55Z

Walkthrough

This pull request expands and restructures documentation for five composables within the API reference: useHeadSafe, useHead, useHydration, useLazyAsyncData, and useLazyFetch. The changes introduce consistent structural improvements across all files, including dedicated Usage sections with Vue code examples, Type signatures, Parameters tables, and Return Values sections. Notable additions include explicit security rationale and allowed attributes whitelist for useHeadSafe, reactive usage patterns for useHead, and clarifications on lazy-loading behaviour for useLazyAsyncData and useLazyFetch. One type signature correction addresses a stray character in the useHydration function signature, changing set: (value: T) => v to the correct set: (value: T) => void. All changes are documentation-only with no alterations to public API declarations.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Type signature correction in use-hydration.md (the v → void fix) should be verified for accuracy
Vue code examples across all five files should be checked for syntax correctness and practical applicability
Security-related content in use-head-safe.md (XSS rationale and attribute whitelist) warrants verification against actual implementation
Consistency of structural patterns (Usage, Type, Parameters, Return Values sections) across the five files should be spot-checked for completeness

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "docs: enhance documentation for Nuxt composables" accurately reflects the primary change in the pull request. The raw summary confirms that all five modified files (use-head-safe.md, use-head.md, use-hydration.md, use-lazy-async-data.md, and use-lazy-fetch.md) contain comprehensive documentation enhancements including expanded guides, restructured content, code examples, and corrected type signatures. The title is concise, specific, and clearly communicates that this is a documentation improvement PR focused on composables, meeting the standard for a well-scoped PR title.
Description Check	✅ Passed	The description is clearly related to the changeset. It explicitly states the PR is "improving the documentation for a few Nuxt composables according to the discussion at #30930," which directly aligns with the raw summary showing extensive documentation rewrites and enhancements across multiple composable documentation files. The reference to the linked issue provides appropriate context for the changes. Although the description is brief, it contains sufficient detail to relate to the actual changes being made.

✨ Finishing touches

🧪 Generate unit tests (beta)

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

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: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 456cc36 and 4f5e1e6.

📒 Files selected for processing (5)

docs/3.api/2.composables/use-head-safe.md (3 hunks)
docs/3.api/2.composables/use-head.md (2 hunks)
docs/3.api/2.composables/use-hydration.md (3 hunks)
docs/3.api/2.composables/use-lazy-async-data.md (1 hunks)
docs/3.api/2.composables/use-lazy-fetch.md (1 hunks)

🧰 Additional context used

🧠 Learnings (2)

📚 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/3.api/2.composables/use-lazy-async-data.md

📚 Learning: 2024-11-05T20:04:39.622Z

Learnt from: Tofandel
Repo: nuxt/nuxt PR: 26468
File: packages/nuxt/src/components/runtime/client-delayed-component.ts:62-62
Timestamp: 2024-11-05T20:04:39.622Z
Learning: In Vue components, when typing the `hydrate` prop for hydration strategies like `hydrateOnInteraction`, use `type: null as PropType<Arguments<typeof hydrateOnInteraction>[0]>` to get the type directly from Vue's hydration methods. Also, remember that `HTMLElementEventMap` is not a type but an object; use `keyof HTMLElementEventMap` when defining prop types for events.

Applied to files:

docs/3.api/2.composables/use-hydration.md

🪛 LanguageTool

docs/3.api/2.composables/use-lazy-async-data.md

[uncategorized] ~12-~12: Loose punctuation mark.
Context: ...y setting the lazy option to true. ::note By default, [useAsyncData](/docs...