docs: defineNuxtPlugin function documentation
#32328
Conversation
|
|
There was a problem hiding this comment.
Pull Request Overview
This PR adds comprehensive documentation for the defineNuxtPlugin utility, covering its type signature, parameters, and usage examples.
- Introduces a new markdown file detailing API definitions and object/plugin syntax.
- Provides TypeScript signatures and explanations of each option in
ObjectPlugin. - Includes basic and advanced usage examples with code snippets.
Comments suppressed due to low confidence (2)
docs/3.api/3.utils/define-nuxt-plugin.md:3
- Wrap the function name in backticks in the frontmatter description to match code formatting conventions:
description: "defineNuxtPlugin()is a helper function for creating Nuxt plugins."
description: defineNuxtPlugin() is a helper function for creating Nuxt plugins.
docs/3.api/3.utils/define-nuxt-plugin.md:95
- [nitpick] Rephrase the
env.islandsdescription to clarify its behavior, for example: "Ifislandsis set tofalse, the plugin will be skipped during island rendering mode."
Environment configuration. Set this value to `false` if you don't want the plugin to run when rendering server-only or island components.
|
Warning Rate limit exceeded@danielroe has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 17 minutes and 2 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 (1)
WalkthroughA new documentation file, define-nuxt-plugin.md, has been added to describe the defineNuxtPlugin helper function for Nuxt plugins. The document outlines how defineNuxtPlugin standardises plugin formats, provides TypeScript type definitions, and details the supported plugin formats: function plugins and object plugins with various configuration options. It explains properties such as name, enforce, dependsOn, order, parallel, setup, hooks, and env. The documentation includes parameter descriptions and usage examples for both basic and advanced plugin configurations. The public API for defineNuxtPlugin and its associated types is also documented. ✨ 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: 1
🧹 Nitpick comments (3)
docs/3.api/3.utils/define-nuxt-plugin.md (3)
2-2: Include parentheses in the title
To reflect that this documents a function, add()in the frontmatter title.- title: "defineNuxtPlugin" + title: "defineNuxtPlugin()"
13-17: Add import statement fordefineNuxtPlugin
It’s not immediately clear wheredefineNuxtPluginis imported from. Including an import in the example will help newcomers.13 ```ts [plugins/hello.ts] +14 import { defineNuxtPlugin } from '#app' 15 export default defineNuxtPlugin((nuxtApp) => { 16 // Doing something with nuxtApp 17 })
118-123: Remove extra space before parentheses inasync setup
Adhere to TypeScript style conventions by eliminating the space between the method name and its parameter list.- async setup (nuxtApp) { + async setup(nuxtApp) {
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/3.api/3.utils/define-nuxt-plugin.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/3.api/3.utils/define-nuxt-plugin.md
[uncategorized] ~18-~18: Loose punctuation mark.
Context: ...// Doing something with nuxtApp }) ``` :read-more{to="/docs/guide/directory-stru...
(UNLIKELY_OPENING_PUNCTUATION)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: lint-docs
- GitHub Check: link-checker
🔇 Additional comments (5)
docs/3.api/3.utils/define-nuxt-plugin.md (5)
19-19: Confirm:read-moredirective support
The:read-more{to="…"}syntax may be a custom shortcode. Please verify it is supported by the site generator, or convert it to a standard Docusaurus/link component if not.
42-95: Parameters section looks thorough.
Clear descriptions and formatting make it easy to understand each option.
99-112: Basic usage example is clear and accurate.
This snippet concisely demonstrates a simple function plugin.
114-140: Advanced usage example effectively demonstrates object plugin options.
It clearly showsname,enforce, asyncsetup, hooks andenvusage in context.
1-9:✅ Verification successful
Verify Source Link in Frontmatter
Theto:URL currently points topackages/nuxt/src/app/nuxt.ts. Please ensure this matches the actual location of thedefineNuxtPluginimplementation and update if necessary.
🏁 Script executed:
#!/bin/bash # Verify the defineNuxtPlugin declaration in the codebase rg -n "export function defineNuxtPlugin" -n .Length of output: 220
Source link verified
The frontmatter URL correctly points to thedefineNuxtPluginimplementation inpackages/nuxt/src/app/nuxt.ts(line 477). No update required.
…to docs-define-nuxt-plugin
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
docs/3.api/3.utils/define-nuxt-plugin.md (2)
87-90: Duplicate hyperlink feedback
(This feedback is already covered by the RuntimeNuxtHooks link correction above.)
26-27:⚠️ Potential issueCorrect the NuxtApp hyperlink
The link currently points to/docs/guide/going-further/internals#the-nuxtapp-interface. It should target the official API page for NuxtApp:- type Plugin<T> = (nuxt: [NuxtApp](/docs/guide/going-further/internals#the-nuxtapp-interface)) => … + type Plugin<T> = (nuxt: [NuxtApp](/docs/api/configuration-runtime#nuxtapp)) => …
🧹 Nitpick comments (13)
docs/3.api/3.utils/define-nuxt-plugin.md (13)
1-9: Review front-matter metadata
The YAML front-matter looks correct, but please verify that thelinks.toURL points to the canonicalnuxt.tssource on the default branch. Consider adding asidebarLabelif other util pages use it for consistency in navigation.
21-23: Consider renaming “Type” heading
The section title## Typecould be clearer as## Signatureor## Type Definitionsto match other API docs.
23-25: Cross-link Plugin and ObjectPlugin types
To improve discoverability, hyperlink the type names in the signature to their respective sections or to the TypeScript declarations in this doc.
42-50: Linkpluginparameter to its type
In the description ofplugin, consider linking the termPlugin<T>|ObjectPlugin<T>back to the Type Definitions section for easier navigation.
51-54: Reduce redundancy in Function Plugin section
The “Function Plugin” subsection re-states the signature. You could streamline by referring to the signature above, e.g.:See the signature in Type Definitions.
57-61: Clarifynameproperty usage
Mention thatnamealso appears in DevTools and is used by Nuxt for plugin identification—e.g. for dependency graphs.
67-71: EnhancedependsOnguidance
Note that the entries here must match other plugins’namevalues exactly, otherwise the dependency won’t be honoured.
72-76: Document defaultorderbehaviour
It may help to state the defaultorderif unspecified (e.g. inferred fromenforce).
77-81: Clarifyparallelexecution semantics
Explain what “parallel” means in practice (e.g. run alongside other parallel plugins after sorting).
82-86: Mergesetupdescription with Function Plugin
Sincesetupis identical to a function plugin, consider merging or cross-referencing these sections to avoid duplication.
92-96: Rewordenvdescription for clarity
Current phrasing could be misread. Perhaps:Run only in island mode when
env.islands: true. Set tofalseto skip in island-only rendering.
99-112: Enhance Basic Usage example
Include an import ofdefineNuxtPluginat the top for clarity and show a returned provider payload.
114-141: Expand advanced example
Consider demonstratingdependsOnandorderoptions to showcase the full object plugin capabilities.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/3.api/3.utils/define-nuxt-plugin.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/3.api/3.utils/define-nuxt-plugin.md
[uncategorized] ~18-~18: Loose punctuation mark.
Context: ...// Doing something with nuxtApp }) ``` :read-more{to="/docs/guide/directory-stru...
(UNLIKELY_OPENING_PUNCTUATION)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: link-checker
- GitHub Check: lint-docs
🔇 Additional comments (6)
docs/3.api/3.utils/define-nuxt-plugin.md (6)
11-12: Introduction is clear
The overview succinctly explains the purpose ofdefineNuxtPlugin.
13-17: Verify code-block path annotation
Ensure that the syntaxts [plugins/hello.ts]is supported by the docs renderer and that the file path appears in the UI as intended.
19-19: Check:read-moredirective syntax
Confirm that:read-more{to="/docs/guide/directory-structure/plugins#creating-plugins"}renders as an inline “Read more” link. If not, switch to a standard markdown link or the correct directive format.
55-56: Object Plugin introduction is clear
The note “Object Plugin Properties” correctly signals the following list.
62-66:enforcedescription is accurate
The explanation clearly covers plugin ordering.
97-97: Examples heading is appropriate
The## Examplessection aligns with other API pages.
Co-authored-by: Julien Huang <julien.h.dev@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/3.api/3.utils/define-nuxt-plugin.md (1)
93-95: ClarifyenvDescription
The phrasing "prevent the plugin running in specified environment" is ambiguous. Consider rewording to clearly state how theenvflags enable or disable plugin execution.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/3.api/3.utils/define-nuxt-plugin.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/3.api/3.utils/define-nuxt-plugin.md
[uncategorized] ~18-~18: Loose punctuation mark.
Context: ...// Doing something with nuxtApp }) ``` :read-more{to="/docs/guide/directory-stru...
(UNLIKELY_OPENING_PUNCTUATION)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: lint-docs
🔇 Additional comments (5)
docs/3.api/3.utils/define-nuxt-plugin.md (5)
1-9: Frontmatter Validity
YAML frontmatter is well structured and includes necessary metadata.
11-17: Introduction Clarity
The overview clearly explains the purpose ofdefineNuxtPluginand its integration within Nuxt.
42-49: Parameters Section
The parameter overview is comprehensive, matches the signature and clearly distinguishes between function and object plugins.
99-112: Basic Example Correctness
The basic usage example is clear and demonstrates the function plugin pattern effectively.
118-141: Advanced Example Accuracy
The object syntax example covers all configuration options and is correctly formatted.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
docs/3.api/3.utils/define-nuxt-plugin.md (2)
34-36: 🛠️ Refactor suggestionFix RuntimeNuxtHooks hyperlink
Thehooksproperty link directs to the advanced hooks guide. Update it to point to the runtime hooks API (/docs/api/configuration-hooks#runtime-nuxt-hooks) for accuracy.Suggested diff:
- hooks?: Partial<[RuntimeNuxtHooks](/docs/api/advanced/hooks#app-hooks-runtime)> + hooks?: Partial<[RuntimeNuxtHooks](/docs/api/configuration-hooks#runtime-nuxt-hooks)>
24-27: 🛠️ Refactor suggestionCorrect NuxtApp type hyperlink
The link forNuxtAppcurrently points to the internals guide. It should reference the runtime API docs forNuxtApp(/docs/api/configuration-runtime#nuxtapp) to improve discoverability.Suggested diff:
- type Plugin<T> = (nuxt: [NuxtApp](/docs/guide/going-further/internals#the-nuxtapp-interface)) => Promise<void> | Promise<{ provide?: T }> | void | { provide?: T } + type Plugin<T> = (nuxt: [NuxtApp](/docs/api/configuration-runtime#nuxtapp)) => Promise<void> | Promise<{ provide?: T }> | void | { provide?: T }
🧹 Nitpick comments (2)
docs/3.api/3.utils/define-nuxt-plugin.md (2)
50-53: Add hyperlink to NuxtApp in Parameters
In the Function Plugin section the type is shown as(nuxtApp: NuxtApp). Consider linkingNuxtAppto/docs/api/configuration-runtime#nuxtappto maintain consistency with the Type section.
87-90: Link RuntimeNuxtHooks in Parameters
The hooks parameter type doesn’t include a link to its API reference. Add a hyperlink onRuntimeNuxtHooks(/docs/api/configuration-hooks#runtime-nuxt-hooks) to guide users to the full runtime hooks documentation.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/3.api/3.utils/define-nuxt-plugin.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/3.api/3.utils/define-nuxt-plugin.md
[uncategorized] ~18-~18: Loose punctuation mark.
Context: ...// Doing something with nuxtApp }) ``` :read-more{to="/docs/guide/directory-stru...
(UNLIKELY_OPENING_PUNCTUATION)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: lint-docs
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
docs/3.api/3.utils/define-nuxt-plugin.md (2)
24-28: Correct NuxtApp hyperlink to runtime API docs
The link currently points to the internals guide. Update it to the runtime API section for better discoverability.-type Plugin<T> = (nuxt: [NuxtApp](/docs/guide/going-further/internals#the-nuxtapp-interface)) => Promise<void> | Promise<{ provide?: T }> | void | { provide?: T } +type Plugin<T> = (nuxt: [NuxtApp](/docs/api/configuration-runtime#nuxtapp)) => Promise<void> | Promise<{ provide?: T }> | void | { provide?: T }
34-36: Update RuntimeNuxtHooks link to correct section
The hyperlink references the advanced hooks guide; it should point to the runtime hooks API instead.-hooks?: Partial<[RuntimeNuxtHooks](/docs/api/advanced/hooks#app-hooks-runtime)> +hooks?: Partial<[RuntimeNuxtHooks](/docs/api/configuration-hooks#runtime-nuxt-hooks)>
🧹 Nitpick comments (4)
docs/3.api/3.utils/define-nuxt-plugin.md (4)
3-3: Wrap function name in code ticks
The description should format the utility name as inline code for clarity.-description: defineNuxtPlugin() is a helper function for creating Nuxt plugins. +description: `defineNuxtPlugin()` is a helper function for creating Nuxt plugins.
44-47: Fix NuxtApp link and grammar in parameters description
Update theNuxtApplink to the API docs and change "an potential" to "a potential".-1. **Function Plugin**: A function that receives the [`NuxtApp`](/docs/guide/going-further/internals#the-nuxtapp-interface) instance and can return a promise with an potential object with a [`provide`](/docs/guide/directory-structure/plugins#providing-helpers) property if you want to provide a helper on the [`NuxtApp`](/docs/guide/going-further/internals#the-nuxtapp-interface) instance. +1. **Function Plugin**: A function that receives the [`NuxtApp`](/docs/api/configuration-runtime#nuxtapp) instance and can return a promise with a potential object with a [`provide`](/docs/guide/directory-structure/plugins#providing-helpers) property if you want to provide a helper on the [`NuxtApp`](/docs/api/configuration-runtime#nuxtapp) instance.🧰 Tools
🪛 LanguageTool
[misspelling] ~45-~45: Use “a” instead of ‘an’ if the following word doesn’t start with a vowel sound, e.g. ‘a sentence’, ‘a university’.
Context: ... instance and can return a promise with an potential object with a [provide](/do...(EN_A_VS_AN)
55-56: Standardise inline code notation in table
Remove the{lang="ts"}specifier from inline code entries and use plain backticks for consistency.-| `setup` | `Plugin<T>`{lang="ts"} | `false` | The main plugin function, equivalent to a function plugin. | +| `setup` | `Plugin<T>` | `false` | The main plugin function, equivalent to a function plugin. | -| `hooks` | `Partial<RuntimeNuxtHooks>`{lang="ts"} | `false` | Nuxt app runtime hooks to register directly. | +| `hooks` | `Partial<RuntimeNuxtHooks>` | `false` | Nuxt app runtime hooks to register directly. |
56-57: Clarifyenvconfiguration semantics
The current description is vague. Explicitly state thatenv.islandstoggles plugin execution in Island rendering contexts and note default behaviour.- | `env` | `{ islands?: boolean }`{lang="ts"} | `false` | Set this value to `false` if you don't want the plugin to run when rendering server-only or island components. | + | `env` | `{ islands?: boolean }` | `false` | Environment flags object. For example, set `env.islands` to `false` to disable the plugin during Island rendering (default is `true`). |
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/3.api/3.utils/define-nuxt-plugin.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/3.api/3.utils/define-nuxt-plugin.md
[uncategorized] ~18-~18: Loose punctuation mark.
Context: ...// Doing something with nuxtApp }) ``` :read-more{to="/docs/guide/directory-stru...
(UNLIKELY_OPENING_PUNCTUATION)
[misspelling] ~45-~45: Use “a” instead of ‘an’ if the following word doesn’t start with a vowel sound, e.g. ‘a sentence’, ‘a university’.
Context: ... instance and can return a promise with an potential object with a [provide](/do...
(EN_A_VS_AN)
[uncategorized] ~58-~58: Loose punctuation mark.
Context: ...ng server-only or island components. | :video-accordion{title="Watch a video fro...
(UNLIKELY_OPENING_PUNCTUATION)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: lint-docs
🔗 Linked issue
Resolves #32211
📚 Description
This pull request adds comprehensive documentation for the
defineNuxtPluginutility, detailing its purpose, type definitions, parameters, and usage examples.