feat(module): add experimental.componentDetection option

[benjamincanac]

🔗 Linked issue

Resolves #5212

❓ 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)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Adds an experimental.componentDetection option for automatic tree-shaking of component styles which only generates theme files for components actually used in your application, reducing CSS bundle size and improving LCP performance

📝 Checklist

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

[pkg-pr-new]

npm i https://pkg.pr.new/@nuxt/ui@5222

commit: bbb572d

[maxarias-io]

Heads up:

[nuxi 1:39:42 PM]  ERROR  Nuxt Build Error: [vite:load-fallback] Could not load /Users/myprojectpathhere/node_modules/.cache/nuxt/.nuxt//ui/accordion (imported by node_modules/@nuxt/ui/dist/runtime/components/Accordion.vue): ENOENT: no such file or directory, open '/Users/myprojectpathhere/node_modules/.cache/nuxt/.nuxt//ui/accordion'

Look like you got a double slash

[benjamincanac]

@maxarias-io I'm having a hard-time reproducing your error, do you have a simple reproduction? Since the error reports node_modules/.cache have you tried a clean install?

[maxarias-io]

@maxarias-io I'm having a hard-time reproducing your error, do you have a simple reproduction? Since the error reports node_modules/.cache have you tried a clean install?

Sorry no minimal repro, this is a big project

I did retry with a clean install: rm -rf node_modules/ && rm -rf .nuxt/ && yarn && yarn build && yarn start no luck, same error.

Here's my info:

------------------------------
- Operating System: Darwin
- Node Version:     v24.8.0
- Nuxt Version:     4.1.0
- CLI Version:      3.28.0
- Nitro Version:    2.12.5
- Package Manager:  yarn@4.9.2
- Builder:          -
- User Config:      app, colorMode, compatibilityDate, critters, css, devtools, eslint, experimental, fonts, hooks, icon, image, modules, nitro, nuxt-jsonld, ogImage, pinia, pinoLogs, router, routeRules, runtimeConfig, scripts, site, sourcemap, srcDir, ui, vite, vitalizer
- Runtime Modules:  @pinia/nuxt@0.11.2, @vueuse/nuxt@13.7.0, nuxt-jsonld@2.2.1, @nuxtjs/device@3.2.4, @nuxt/devtools@2.6.3, nuxt-og-image@5.1.9, @nuxt/image@1.11.0, v-satori/nuxt@0.2.0, @nuxt/eslint@1.9.0, @nuxtjs/color-mode@3.5.2, unplugin-icons/nuxt@22.2.0, @nuxt/test-utils/module@3.19.2, @nuxt/scripts@0.11.13, motion-v/nuxt@1.7.0, @nuxt/ui@4.0.1, @nuxtjs/critters@0.9.0, nuxt-vitalizer@2.0.0
- Build Modules:    -
------------------------------

[benjamincanac]

@maxarias-io Would you mind trying again? I've updated the PR: https://pkg.pr.new/@nuxt/ui@bbb572d.

[maxarias-io]

No more build errors 🙌 but it seems to actually include more CSS rather than less:

[benjamincanac]

Is this in dev or build? Did you make sure to remove the .nuxt/ dir after enabling componentDetection?

[maxarias-io]

https://pkg.pr.new/@nuxt/ui@bbb572d

Always a build (yarn build && yarn start). Then I load in incognito, view source and open/save the entry.css file.

I reset everything with rm -rf node_modules/ && rm -rf .nuxt/ && yarn and ran it again, but I got the same result. ~302KB. Also if it helps any, the file hash for the entry css bundle didn't change.

[benjamincanac]

This is really weird, I'm trying on https://github.com/nuxt-ui-templates/dashboard and it's working well 🤔 Can you check the sources present in your .nuxt/ui.css after a build?

(Thank you for helping me debug this)

[maxarias-io]

Agh, dumb me, I forgot to enable componentDetection when I switched branch to test this again.

Still generating more CSS for some reason:

.nuxt/ui.css:

@source "./ui/toaster.ts";
@source "./ui/toast.ts";
@source "./ui/avatar.ts";
@source "./ui/chip.ts";
@source "./ui/button.ts";
@source "./ui/link.ts";
@source "./ui/progress.ts";
@source "./ui/modal.ts";
@source "./ui/skeleton.ts";
@source "./ui/form-field.ts";
@source "./ui/input.ts";
@source "./ui/badge.ts";
@source "./ui/tooltip.ts";
@source "./ui/kbd.ts";
@source "./ui/avatar-group.ts";
@source "./ui/checkbox.ts";
@source "./ui/switch.ts";
@source "./ui/alert.ts";
@source "./ui/separator.ts";
@source "./ui/dropdown-menu.ts";
@source "./ui/collapsible.ts";
@source "./ui/popover.ts";
@source "./ui/select.ts";
@source "./ui/textarea.ts";
@source "./ui/card.ts";
@source "./ui/chat-messages.ts";
@source "./ui/chat-message.ts";
@source "./ui/chat-prompt.ts";
@source "./ui/calendar.ts";
@source "./ui/file-upload.ts";
@source "./ui/radio-group.ts";
@source "./ui/drawer.ts";
@source "./ui/breadcrumb.ts";
@source "./ui/field-group.ts";
@source "./ui/form.ts";

Not sure why it would generate more CSS now 🙃

[maxarias-io]

Something worth exploring maybe, I see things like:

@source "./ui/progress.ts"; and @source "./ui/kbd.ts"; that I don't use in my codebase

[benjamincanac]

This is normal, Progress is used in Toast and Kbd in DropdownMenu. We need to register those dependency sources otherwise it can't be detected. I don't understand why this generates more CSS than @source "./ui"; though it doesn't make sense.

[maxarias-io]

Alright, I think this was me again. I created a hacky solution to detect used components and only source those, but it's not sourcing dependencies like yours (so it makes sense that this fix generates more css than mine, it properly includes everything needed). Maybe when I ran the initial test something was cached, I don't know.

I made sure to properly delete the module, cache, .nuxt and ran it again. Now it makes more sense:

So this experimental feature is saving around 30KB 👏

Thanks for your patience, it's early 😅

[benjamincanac]

Ok great! I was running out of ideas to fix this 😅

I'm gonna merge this as-is to include in the next minor release. I believe there are more improvements that can be made especially with dynamic imports (for example the Header component imports Modal, Slideover and Drawer to render the mobile menu based on the mode prop: https://github.com/nuxt/ui/blob/v4/src/runtime/components/Header.vue#L68-L70).

However, this is really tricky to detect so let's do this in another future PR.

[benjamincanac]

Just as a note, I'm not sure you noticed but this also works dynamically in dev mode and logs which component has been detected 😊

[maxarias-io]

Awesome work, thanks a lot!