From 7b762a1e4bb52f5baaefdf0243cf1171922e5be6 Mon Sep 17 00:00:00 2001
From: padreug <padreug@aiolabs.dev>
Date: Thu, 18 Sep 2025 22:02:10 +0200
Subject: [PATCH] Add Vue Reactivity Best Practices section to CLAUDE.md

- Introduced guidelines for handling complex object reactivity in Vue, addressing common issues such as input components not updating and computed properties not recalculating.
- Provided solutions including using Object.assign for object reactivity, dynamic keys for component re-renders, and safe navigation with fallbacks.
- Included practical examples to illustrate the application of these patterns in real scenarios, enhancing developer understanding of Vue's reactivity system.
---
 CLAUDE.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index cb789c6..e8194d8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -370,6 +370,75 @@ const onSubmit = form.handleSubmit(async (values) => {
 <Button :disabled="!isFormValid">Submit</Button>
 ```
 
+### **Vue Reactivity Best Practices**
+
+**CRITICAL: Handling Complex Object Reactivity**
+
+When working with complex objects from API responses or services, Vue's reactivity system may not always detect changes properly. This is especially common with nested objects or objects from external sources.
+
+**Common Reactivity Issues:**
+- Input components not updating when object properties change
+- Template not re-rendering after API responses
+- Computed properties not recalculating
+
+**✅ SOLUTIONS:**
+
+**1. Force Object Reactivity with Object.assign:**
+```typescript
+// ❌ DON'T: Direct assignment may not trigger reactivity
+createdObject.value = apiResponse
+
+// ✅ DO: Create new object reference to ensure reactivity
+createdObject.value = Object.assign({}, apiResponse)
+```
+
+**2. Force Component Re-render with Dynamic Keys:**
+```vue
+<!-- ❌ DON'T: Component may not update with new data -->
+<Input :value="object.property" readonly />
+
+<!-- ✅ DO: Force re-render with dynamic key -->
+<Input
+  :key="`field-${object?.id}`"
+  :model-value="object?.property || ''"
+  readonly
+/>
+```
+
+**3. Use Safe Navigation and Fallbacks:**
+```vue
+<!-- ✅ Prevent errors and ensure consistent data types -->
+<Input
+  :model-value="object?.property || ''"
+  :key="`field-${object?.uniqueId}`"
+  readonly
+/>
+```
+
+**When to Apply These Patterns:**
+- ✅ API responses stored in reactive refs
+- ✅ Complex objects from services
+- ✅ Input components showing external data
+- ✅ Any scenario where template doesn't update after data changes
+
+**Example from Wallet Module:**
+```typescript
+// Service returns complex invoice object
+const invoice = await walletService.createInvoice(data)
+
+// Force reactivity for template updates
+createdInvoice.value = Object.assign({}, invoice)
+```
+
+```vue
+<!-- Template with forced reactivity -->
+<Input
+  :key="`bolt11-${createdInvoice?.payment_hash}`"
+  :model-value="createdInvoice?.payment_request || ''"
+  readonly
+/>
+```
+
 ### **Module Development Best Practices**
 
 **Module Structure Requirements:**