React

Critical Patterns (Always Check)

Waterfall Prevention

// ❌ Sequential - 3 round trips
const user = await fetchUser()
const posts = await fetchPosts()

// ✅ Parallel - 1 round trip
const [user, posts] = await Promise.all([fetchUser(), fetchPosts()])

Bundle Size

// ❌ Loads 1,583 modules
import { Check } from 'lucide-react'

// ✅ Next.js config
// next.config.js: optimizePackageImports: ['lucide-react']

Dark Mode (Helmai MANDATORY)

// ❌ Light only
className="bg-white text-gray-700"

// ✅ With dark variants
className="bg-white dark:bg-gray-900 text-gray-700 dark:text-gray-200"

TanStack Query Pattern

// Use query key factories
import { patientKeys } from '@/hooks/queryKeys'

const { data } = useQuery({
  queryKey: patientKeys.detail(patientId),
  queryFn: () => fetchPatient(patientId),
})

Toast Notifications

import { toast } from 'sonner'

// ❌ Never use alert()
// ✅ Always use Sonner
toast.error('Something went wrong')
toast.success('Saved successfully')

Decision Tree

Performance Issue?
├── Slow initial load → Check [bundle-size.md](references/bundle-size.md)
├── Slow data fetch → Check [waterfalls.md](references/waterfalls.md)
├── UI stuttering → Check [re-renders.md](references/re-renders.md)
├── Long lists slow → Check [rendering.md](references/rendering.md)
└── API route slow → Check [server-side.md](references/server-side.md)

Checklist Before PR

• No sequential awaits (use Promise.all)
• Dynamic imports for heavy components
• Dark mode variants on all UI elements
• TanStack Query with key factories
• Sonner for notifications (not alert)
• Error boundaries around async components

Feedback Loop

When reviewing or fixing performance issues:

1. Identify → Run pnpm build or check React DevTools
2. Fix → Apply patterns from reference files
3. Validate → Re-run build, verify no new warnings
4. Repeat → If issues remain, continue loop

External Resources

• React Documentation
• Next.js Documentation
• TanStack Query
• Vercel Performance Guide