charging-cabinet/software/h5-uniapp/agent/skills/vue-best-practices/reference/local-components-not-in-descendants.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
Locally Registered Components Are Not Available in Descendants	HIGH	Common source of "component not found" errors in nested components	gotcha	vue3 component-registration local-registration scope nested-components

Locally Registered Components Are Not Available in Descendants

Impact: HIGH - Locally registered components are only available in the component where they are registered, NOT in its child or descendant components. This is a common source of "Unknown component" or "Failed to resolve component" errors when developers expect a component registered in a parent to be available in children.

Task Checklist

• Import and register components in every file where they are used
• Do not expect parent's local components to be available in children
• If a component is needed in many places, consider global registration only as a last resort
• Use IDE auto-import features to simplify repeated imports

Incorrect:

<!-- ParentComponent.vue -->
<script setup>
import Card from './Card.vue'
import ChildComponent from './ChildComponent.vue'
</script>

<template>
  <Card>Parent content</Card>
  <ChildComponent />
</template>

<!-- ChildComponent.vue -->
<script setup>
// WRONG: Expecting Card to be available because parent imported it
// This will cause "Failed to resolve component: Card" error
</script>

<template>
  <!-- ERROR: Card is not available here! -->
  <Card>
    Child content
  </Card>
</template>

Correct:

<!-- ParentComponent.vue -->
<script setup>
import Card from './Card.vue'
import ChildComponent from './ChildComponent.vue'
</script>

<template>
  <Card>Parent content</Card>
  <ChildComponent />
</template>

<!-- ChildComponent.vue -->
<script setup>
// CORRECT: Each component must import what it uses
import Card from './Card.vue'
</script>

<template>
  <Card>
    Child content
  </Card>
</template>

Common Scenarios

Scenario 1: Deeply Nested Components

<!-- GrandchildComponent.vue -->
<script setup>
// Even if parent and grandparent both use Card,
// grandchild must import it separately
import Card from '@/components/Card.vue'
import Button from '@/components/Button.vue'
</script>

<template>
  <Card>
    <Button>Click me</Button>
  </Card>
</template>

Scenario 2: Slot Content with Components

<!-- Parent.vue -->
<script setup>
import Modal from './Modal.vue'
import Form from './Form.vue'
</script>

<template>
  <!-- Form is registered in Parent, so it works in slot content -->
  <Modal>
    <Form /> <!-- This works because slot content is compiled in Parent's scope -->
  </Modal>
</template>

<!-- Modal.vue -->
<script setup>
// Modal doesn't need to import Form because slot content
// is compiled in the parent's scope, not Modal's scope
</script>

<template>
  <div class="modal">
    <slot /> <!-- Form component works here because it's parent's slot content -->
  </div>
</template>

Scenario 3: Dynamic Components

<!-- Container.vue -->
<script setup>
import TabA from './TabA.vue'
import TabB from './TabB.vue'
import { ref, shallowRef } from 'vue'

// When using dynamic components, all possible components must be imported
const currentTab = shallowRef(TabA)
</script>

<template>
  <component :is="currentTab" />
</template>

Why This Design?

Local registration provides:

1. Explicit dependencies - You can see exactly what each component uses
2. Tree-shaking - Unused components are removed from bundles
3. Clear scope - No magic or implicit behavior

Reference

• Vue.js Component Registration - Local Registration