1---
2title: Avoid Component Naming Conflicts Between Global and Local
3impact: HIGH
4impactDescription: Naming conflicts cause unexpected component rendering and hard-to-debug issues
5type: gotcha
6tags: [vue3, component-registration, naming-conflicts, global-local, debugging]
7---
8 
9# Avoid Component Naming Conflicts Between Global and Local
10 
11**Impact: HIGH** - When a global component and a local component have the same name (or resolve to the same name due to casing differences), unexpected behavior occurs. The precedence rules can be confusing, and the wrong component may render silently without any error. This is particularly problematic when using third-party component libraries.
12 
13## Task Checklist
14 
15- [ ] Use unique, prefixed names for global components (e.g., `BaseButton`, `AppHeader`)
16- [ ] Check for naming conflicts when adding global components
17- [ ] Explicitly alias local components if there's potential conflict
18- [ ] When overriding third-party components, document and test thoroughly
19 
20**Incorrect:**
21```javascript
22// main.js
23import { createApp } from 'vue'
24import Button from './components/Button.vue'
25 
26const app = createApp(App)
27app.component('Button', Button) // Global Button
28```
29 
30```vue
31<!-- SomeComponent.vue -->
32<script setup>
33// This local Button might conflict with global Button
34import Button from './local/Button.vue'
35</script>
36 
37<template>
38  <!-- Which Button renders? Behavior may be unexpected -->
39  <Button>Click me</Button>
40</template>
41```
42 
43```vue
44<!-- Another confusing scenario -->
45<script setup>
46// Registering with camelCase
47import MyButton from './MyButton.vue'
48</script>
49 
50<template>
51  <!-- Using kebab-case - might match a global 'my-button' instead -->
52  <my-button>Click</my-button>
53</template>
54```
55 
56**Correct:**
57```javascript
58// main.js - use prefixes for global components
59import { createApp } from 'vue'
60import BaseButton from './components/BaseButton.vue'
61import BaseIcon from './components/BaseIcon.vue'
62 
63const app = createApp(App)
64app.component('BaseButton', BaseButton)
65app.component('BaseIcon', BaseIcon)
66```
67 
68```vue
69<!-- SomeComponent.vue -->
70<script setup>
71// Local components have distinct names
72import SubmitButton from './local/SubmitButton.vue'
73</script>
74 
75<template>
76  <!-- No ambiguity - each name is unique -->
77  <BaseButton>Generic button</BaseButton>
78  <SubmitButton>Submit form</SubmitButton>
79</template>
80```
81 
82## Explicit Aliasing for Clarity
83 
84When you intentionally want to override or have similar names, use explicit aliasing:
85 
86```vue
87<script setup>
88// Explicit alias to avoid confusion
89import { default as LocalButton } from './Button.vue'
90</script>
91 
92<template>
93  <LocalButton>Local version</LocalButton>
94</template>
95```
96 
97```vue
98<!-- Options API with explicit component name -->
99<script>
100import ThirdPartyModal from 'some-library'
101import CustomModal from './CustomModal.vue'
102 
103export default {
104  components: {
105    // Explicit names prevent ambiguity
106    LibraryModal: ThirdPartyModal,
107    CustomModal
108  }
109}
110</script>
111```
112 
113## Resolution Order
114 
115Understanding Vue's component resolution order helps debug issues:
116 
1171. **Local registration** takes precedence over global
1182. **Exact case match** takes precedence over case-insensitive match
1193. Self-referencing component name (file name) has lowest priority
120 
121```vue
122<!-- If all exist: GlobalButton, local Button, and file is Button.vue -->
123<script setup>
124import Button from './Button.vue' // Local registration
125</script>
126 
127<template>
128  <!-- Resolves to locally imported Button, not global -->
129  <Button />
130</template>
131```
132 
133## Third-Party Library Conflicts
134 
135```vue
136<script setup>
137// Be explicit when using components from multiple libraries
138import { Button as AntButton } from 'ant-design-vue'
139import { Button as ElButton } from 'element-plus'
140</script>
141 
142<template>
143  <AntButton>Ant Design</AntButton>
144  <ElButton>Element Plus</ElButton>
145</template>
146```
147 
148## Naming Convention Strategy
149 
150| Component Type | Naming Pattern | Example |
151|----------------|---------------|---------|
152| Base/Global | `Base*` or `App*` prefix | `BaseButton`, `AppHeader` |
153| Domain-specific | Domain prefix | `UserCard`, `ProductList` |
154| Page components | `*Page` or `*View` suffix | `HomePage`, `UserView` |
155| Layout components | `*Layout` suffix | `DefaultLayout`, `AdminLayout` |
156 
157## Reference
158- [Vue.js Component Registration](https://vuejs.org/guide/components/registration.html)
159- [GitHub Issue: Global component naming conflicts](https://github.com/vuejs/vue/issues/4434)
160