feat(kit,nuxt): add component priority to allow overriding

[danielroe]

🔗 Linked issue

resolves #19221

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

In line with the priority option support by auto-imported composables/utils, this PR adds a priority to components to allow them to override other components. By default, user components have a higher priority than components injected by modules without an explicit priority, but not higher than any Nuxt built-in components.

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[codesandbox]

  Open in CodeSandbox Web Editor | VS Code | VS Code Insiders

[pi0]

I have initially removed priority (from Nuxt 2 => 3) in favor of respecting the order simply from the components: [] array (consistent with layers). Supporting kit utils seems a good idea 👍🏼 because it cannot control the array push order. (But maybe user components should have something higher than modules by default?)

Regarding built-ins, I agree with your comment in #19221 (comment). Same for built-in composables, fetch, etc, With auto imports and implicit sources, allowing a built-in to be overridden by the user, can cause unwanted behavior by any module, theme layer, and code that was depending on Nuxt behavior and now is changed! (a layer can break another layer too). So i believe we might give Nuxt Built-ins priority too and document only as advanced escape hatch to override them if really needed.

Default priority: Built-ins > User Components > Layer 1 > Layer 2 > Module Aded [can be overridden with priority ]

[Atinux]

What is the main advantage of overwriting built-ins components?

It can also create confusion for team members working on a Nuxt project with overwritten built-in components.

[danielroe]

The Nuxt component built-ins are:

• NuxtWelcome
• NuxtErrorBoundary
• ClientOnly
• DevOnly
• ServerPlaceholder
• NuxtLink
• NuxtLoadingIndicator
• NuxtIsland
• NuxtLayout
• NuxtPage
• NoScript, Link, Base, Title, Meta, Style, Head, Html and Body

Of those, I think that it would be safe (and good DX) if users could provide their own implementations for <NuxtLink> and <NuxtLoadingIndicator>. Part of the point would be that by overriding their custom behaviour would then be picked up by any modules or layers (for example) that did use those components.

For the other built-in components, their priority when registering them that ensures that it would require extra effort to override them, but still allows an escape hatch for advanced use cases.

wdyt?

maybe user components should have something higher than modules by default

That is the implementation here - user components are given a default priority of 1, which means they will override module components.

[pi0]

Nice summary and LGTM.

Btw this also opens a design in consistency in Nuxt where some built-ins are exceptions to be globally overriding. they both support custom slots for being customized. For the component libraries needing to extend, they could support opt-in NuxtCustomLink by registration detection (we used similar strategy for BV links integrating with Nuxt). Do you think there are common enough usecases that need this kind of overriding often in userland project?