agent-skills/skills/vue-best-practices/reference/prefer-local-component-registration.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
Prefer Local Component Registration Over Global	MEDIUM	Global registration prevents tree-shaking and creates implicit dependencies	best-practice	vue3 component-registration tree-shaking performance maintainability

Prefer Local Component Registration Over Global

Impact: MEDIUM - Global registration prevents build tools from removing unused components (tree-shaking), increasing bundle size. It also creates implicit dependencies similar to global variables, making it difficult to trace where components are used and locate their implementations in large applications.

Use local registration for better maintainability, smaller bundles, and explicit dependency relationships.

Task Checklist

• Use local registration (import in each component) by default
• Reserve global registration only for truly ubiquitous components (icons, buttons, layouts)
• When using <script setup>, simply import components - no explicit registration needed
• Review existing global components and migrate to local registration where possible

Incorrect:

// main.js - registering many components globally
import { createApp } from 'vue'
import App from './App.vue'
import Card from './components/Card.vue'
import Modal from './components/Modal.vue'
import Table from './components/Table.vue'
import Pagination from './components/Pagination.vue'
import UserAvatar from './components/UserAvatar.vue'
import SearchBar from './components/SearchBar.vue'

const app = createApp(App)

// WRONG: All these components are now in the bundle even if unused
app.component('Card', Card)
app.component('Modal', Modal)
app.component('Table', Table)
app.component('Pagination', Pagination)
app.component('UserAvatar', UserAvatar)
app.component('SearchBar', SearchBar)

app.mount('#app')

<!-- SomePage.vue - uses only Card, but all components are bundled -->
<template>
  <Card>
    <p>Content</p>
  </Card>
</template>

<script setup>
// No imports - relying on global registration
// This makes dependencies invisible and hurts tree-shaking
</script>

Correct:

// main.js - only register truly universal components globally
import { createApp } from 'vue'
import App from './App.vue'
import BaseIcon from './components/BaseIcon.vue'
import BaseButton from './components/BaseButton.vue'

const app = createApp(App)

// Only truly ubiquitous base components
app.component('BaseIcon', BaseIcon)
app.component('BaseButton', BaseButton)

app.mount('#app')

<!-- SomePage.vue - explicit local imports -->
<script setup>
// CORRECT: Explicit imports enable tree-shaking
// Only Card is included in the bundle for this component
import Card from '@/components/Card.vue'
import UserAvatar from '@/components/UserAvatar.vue'
</script>

<template>
  <Card>
    <UserAvatar :user="currentUser" />
    <p>Content</p>
  </Card>
</template>

<!-- Options API local registration -->
<script>
import Card from '@/components/Card.vue'
import UserAvatar from '@/components/UserAvatar.vue'

export default {
  components: {
    Card,
    UserAvatar
  }
}
</script>

When Global Registration IS Appropriate

// Truly universal base components used across the entire app
import BaseIcon from './components/BaseIcon.vue'
import BaseButton from './components/BaseButton.vue'
import BaseInput from './components/BaseInput.vue'

// Third-party component libraries with controlled scope
import { Button, Input } from 'some-ui-library'

app.component('BaseIcon', BaseIcon)
app.component('BaseButton', BaseButton)
app.component('BaseInput', BaseInput)

Benefits of Local Registration

Aspect	Global	Local
Tree-shaking	Not possible	Full support
Dependency tracking	Implicit/hidden	Explicit imports
Component location	Hard to find	Follow import path
Bundle size	All registered components	Only used components
Refactoring	Risk of breaking unknown usages	Clear dependency graph

Reference

• Vue.js Component Registration