chore: init monorepo with existing website and plans

2026-06-15 02:31:15 +08:00
commit 72bc89ab03
488 changed files with 115304 additions and 0 deletions
@@ -0,0 +1,151 @@
+---
+title: Locally Registered Components Are Not Available in Descendants
+impact: HIGH
+impactDescription: Common source of "component not found" errors in nested components
+type: gotcha
+tags: [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:**
+```vue
+<!-- ParentComponent.vue -->
+<script setup>
+import Card from './Card.vue'
+import ChildComponent from './ChildComponent.vue'
+</script>
+
+<template>
+  <Card>Parent content</Card>
+  <ChildComponent />
+</template>
+```
+
+```vue
+<!-- 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:**
+```vue
+<!-- ParentComponent.vue -->
+<script setup>
+import Card from './Card.vue'
+import ChildComponent from './ChildComponent.vue'
+</script>
+
+<template>
+  <Card>Parent content</Card>
+  <ChildComponent />
+</template>
+```
+
+```vue
+<!-- 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
+```vue
+<!-- 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
+```vue
+<!-- 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>
+```
+
+```vue
+<!-- 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
+```vue
+<!-- 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](https://vuejs.org/guide/components/registration.html#local-registration)