@xaviele/ag-kit 1.0.0

package/template/.agent/skills/zalo-mini-app/references/react-best-practices.md

@@ -0,0 +1,790 @@
+# React Best Practices
+
+Comprehensive performance optimization guide for React applications in Zalo Mini Apps. Based on Vercel Engineering guidelines.
+
+---
+
+## 1. Eliminating Waterfalls (CRITICAL)
+
+Waterfalls are the #1 performance killer. Each sequential await adds full network latency.
+
+### 1.1 Defer Await Until Needed
+
+Move `await` into branches where actually used.
+
+```typescript
+// Incorrect: blocks both branches
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  if (skipProcessing) return { skipped: true }
+  return processUserData(userData)
+}
+
+// Correct: only blocks when needed
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) return { skipped: true }
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+### 1.2 Promise.all() for Independent Operations
+
+```typescript
+// Incorrect: 3 round trips
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+
+// Correct: 1 round trip
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+### 1.3 Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all`:
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+### 1.4 Strategic Suspense Boundaries
+
+```tsx
+// Correct: wrapper shows immediately, data streams in
+function Page() {
+  return (
+    <div>
+      <Header />
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay />
+      </Suspense>
+      <Footer />
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData()
+  return <div>{data.content}</div>
+}
+```
+
+**When NOT to use:**
+- Critical data needed for layout decisions
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+
+---
+
+## 2. Bundle Size Optimization (CRITICAL)
+
+Keep bundle <10MB for Zalo Mini App approval.
+
+### 2.1 Avoid Barrel File Imports
+
+Barrel files can load 1000+ modules, taking 200-800ms extra.
+
+```tsx
+// Incorrect: imports entire library (1,583 modules)
+import { Check, X, Menu } from 'lucide-react'
+
+// Correct: imports only what you need (~3 modules)
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+```
+
+**Commonly affected libraries:** `lucide-react`, `@mui/material`, `react-icons`, `lodash`, `date-fns`
+
+### 2.2 Dynamic Imports for Heavy Components
+
+```tsx
+import { lazy, Suspense } from 'react'
+
+const HeavyEditor = lazy(() => import('./HeavyEditor'))
+
+function CodePanel({ code }) {
+  return (
+    <Suspense fallback={<Skeleton />}>
+      <HeavyEditor value={code} />
+    </Suspense>
+  )
+}
+```
+
+### 2.3 Conditional Module Loading
+
+```tsx
+function AnimationPlayer({ enabled }) {
+  const [frames, setFrames] = useState(null)
+
+  useEffect(() => {
+    if (enabled && !frames) {
+      import('./animation-frames.js')
+        .then(mod => setFrames(mod.frames))
+        .catch(() => {})
+    }
+  }, [enabled, frames])
+
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+
+### 2.4 Preload on User Intent
+
+```tsx
+function EditorButton({ onClick }) {
+  const preload = () => void import('./HeavyEditor')
+
+  return (
+    <button
+      onMouseEnter={preload}
+      onFocus={preload}
+      onClick={onClick}
+    >
+      Open Editor
+    </button>
+  )
+}
+```
+
+### 2.5 Defer Non-Critical Libraries
+
+```tsx
+// Analytics, logging load after hydration
+import { lazy, Suspense } from 'react'
+
+const Analytics = lazy(() => import('@/lib/analytics'))
+
+function RootLayout({ children }) {
+  return (
+    <>
+      {children}
+      <Suspense fallback={null}>
+        <Analytics />
+      </Suspense>
+    </>
+  )
+}
+```
+
+---
+
+## 3. Client-Side Data Fetching (MEDIUM-HIGH)
+
+### 3.1 Use SWR for Automatic Deduplication
+
+```tsx
+import useSWR from 'swr'
+
+// Multiple instances share one request
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+  return <div>{users?.map(renderUser)}</div>
+}
+```
+
+### 3.2 Passive Event Listeners for Scroll Performance
+
+```typescript
+useEffect(() => {
+  const handleScroll = (e) => console.log(e.deltaY)
+
+  // Correct: passive allows immediate scrolling
+  document.addEventListener('wheel', handleScroll, { passive: true })
+
+  return () => document.removeEventListener('wheel', handleScroll)
+}, [])
+```
+
+### 3.3 Deduplicate Global Event Listeners
+
+Use `useSWRSubscription` to share listeners across component instances:
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+const keyCallbacks = new Map()
+
+function useKeyboardShortcut(key, callback) {
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) keyCallbacks.set(key, new Set())
+    keyCallbacks.get(key).add(callback)
+    return () => {
+      keyCallbacks.get(key)?.delete(callback)
+      if (keyCallbacks.get(key)?.size === 0) keyCallbacks.delete(key)
+    }
+  }, [key, callback])
+
+  useSWRSubscription('global-keydown', () => {
+    const handler = (e) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key).forEach(cb => cb())
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  })
+}
+```
+
+### 3.4 Version localStorage Data
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config) {
+  try {
+    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+  } catch {}
+}
+
+function loadConfig() {
+  try {
+    const data = localStorage.getItem(`userConfig:${VERSION}`)
+    return data ? JSON.parse(data) : null
+  } catch {
+    return null
+  }
+}
+```
+
+---
+
+## 4. Re-render Optimization (MEDIUM)
+
+### 4.1 Defer State Reads to Usage Point
+
+```tsx
+// Incorrect: subscribes to all searchParams changes
+function ShareButton({ chatId }) {
+  const searchParams = useSearchParams()
+  const handleShare = () => shareChat(chatId, { ref: searchParams.get('ref') })
+  return <button onClick={handleShare}>Share</button>
+}
+
+// Correct: reads on demand, no subscription
+function ShareButton({ chatId }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search)
+    shareChat(chatId, { ref: params.get('ref') })
+  }
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+### 4.2 Use Functional setState Updates
+
+```tsx
+// Incorrect: requires state as dependency, recreated on every change
+const addItems = useCallback((newItems) => {
+  setItems([...items, ...newItems])
+}, [items])
+
+// Correct: stable callback, no stale closures
+const addItems = useCallback((newItems) => {
+  setItems(curr => [...curr, ...newItems])
+}, [])
+```
+
+**Benefits:**
+- Stable callback references
+- No stale closures
+- Fewer dependencies
+- Prevents common React bugs
+
+### 4.3 Use Lazy State Initialization
+
+```tsx
+// Incorrect: buildSearchIndex runs on EVERY render
+const [searchIndex] = useState(buildSearchIndex(items))
+
+// Correct: runs only on initial render
+const [searchIndex] = useState(() => buildSearchIndex(items))
+```
+
+### 4.4 Narrow Effect Dependencies
+
+```tsx
+// Incorrect: re-runs on any user field change
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+
+// Correct: re-runs only when id changes
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+### 4.5 Subscribe to Derived State
+
+```tsx
+// Incorrect: re-renders on every pixel change
+function Sidebar() {
+  const width = useWindowWidth()
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+
+// Correct: re-renders only when boolean changes
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+### 4.6 Use Transitions for Non-Urgent Updates
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+### 4.7 Extract to Memoized Components
+
+```tsx
+// Incorrect: computes avatar even when loading
+function Profile({ user, loading }) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+
+// Correct: skips computation when loading
+const UserAvatar = memo(function UserAvatar({ user }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }) {
+  if (loading) return <Skeleton />
+  return <div><UserAvatar user={user} /></div>
+}
+```
+
+---
+
+## 5. Rendering Performance (MEDIUM)
+
+### 5.1 CSS content-visibility for Long Lists
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
+
+### 5.2 Animate SVG Wrapper
+
+Many browsers don't have hardware acceleration for CSS animations on SVG elements.
+
+```tsx
+// Incorrect: no hardware acceleration
+<svg className="animate-spin">
+  <circle cx="12" cy="12" r="10" />
+</svg>
+
+// Correct: hardware accelerated
+<div className="animate-spin">
+  <svg>
+    <circle cx="12" cy="12" r="10" />
+  </svg>
+</div>
+```
+
+### 5.3 Hoist Static JSX Elements
+
+```tsx
+// Correct: reuses same element across renders
+const loadingSkeleton = (
+  <div className="animate-pulse h-20 bg-gray-200" />
+)
+
+function Container({ loading }) {
+  return <div>{loading && loadingSkeleton}</div>
+}
+```
+
+### 5.4 Use Explicit Conditional Rendering
+
+```tsx
+// Incorrect: renders "0" when count is 0
+{count && <span className="badge">{count}</span>}
+
+// Correct: renders nothing when count is 0
+{count > 0 ? <span className="badge">{count}</span> : null}
+```
+
+### 5.5 Prevent Hydration Mismatch Without Flickering
+
+```tsx
+function ThemeWrapper({ children }) {
+  return (
+    <>
+      <div id="theme-wrapper">
+        {children}
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `
+            (function() {
+              try {
+                var theme = localStorage.getItem('theme') || 'light';
+                var el = document.getElementById('theme-wrapper');
+                if (el) el.className = theme;
+              } catch (e) {}
+            })();
+          `,
+        }}
+      />
+    </>
+  )
+}
+```
+
+### 5.6 Use Activity Component for Show/Hide
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Preserves state/DOM for expensive components that frequently toggle visibility.
+
+---
+
+## 6. JavaScript Performance (LOW-MEDIUM)
+
+### 6.1 Build Index Maps for Repeated Lookups
+
+```typescript
+// Incorrect: O(n) per lookup - 1M ops for 1000×1000
+orders.map(order => ({
+  ...order,
+  user: users.find(u => u.id === order.userId)
+}))
+
+// Correct: O(1) per lookup - 2K ops
+const userById = new Map(users.map(u => [u.id, u]))
+orders.map(order => ({
+  ...order,
+  user: userById.get(order.userId)
+}))
+```
+
+### 6.2 Use Set/Map for O(1) Lookups
+
+```typescript
+// Incorrect: O(n) per check
+items.filter(item => allowedIds.includes(item.id))
+
+// Correct: O(1) per check
+const allowedSet = new Set(allowedIds)
+items.filter(item => allowedSet.has(item.id))
+```
+
+### 6.3 Combine Multiple Array Iterations
+
+```typescript
+// Incorrect: 3 iterations
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+
+// Correct: 1 iteration
+const admins = [], testers = [], inactive = []
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```
+
+### 6.4 Cache Storage API Calls
+
+```typescript
+const storageCache = new Map()
+
+function getLocalStorage(key) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key, value) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)
+}
+
+// Invalidate on external changes
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+```
+
+### 6.5 Cache Repeated Function Calls
+
+```typescript
+const slugifyCache = new Map()
+
+function cachedSlugify(text) {
+  if (slugifyCache.has(text)) return slugifyCache.get(text)
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+```
+
+### 6.6 Use toSorted() for Immutability
+
+```typescript
+// Incorrect: mutates original array
+const sorted = users.sort((a, b) => a.name.localeCompare(b.name))
+
+// Correct: creates new array, original unchanged
+const sorted = users.toSorted((a, b) => a.name.localeCompare(b.name))
+
+// Fallback for older browsers
+const sorted = [...users].sort((a, b) => a.name.localeCompare(b.name))
+```
+
+**Other immutable methods:** `.toReversed()`, `.toSpliced()`, `.with()`
+
+### 6.7 Early Return from Functions
+
+```typescript
+// Incorrect: processes all items after error found
+function validateUsers(users) {
+  let hasError = false
+  for (const user of users) {
+    if (!user.email) hasError = true
+  }
+  return hasError ? { valid: false } : { valid: true }
+}
+
+// Correct: returns on first error
+function validateUsers(users) {
+  for (const user of users) {
+    if (!user.email) return { valid: false, error: 'Email required' }
+  }
+  return { valid: true }
+}
+```
+
+### 6.8 Early Length Check for Array Comparisons
+
+```typescript
+// Incorrect: always sorts even when lengths differ
+function hasChanges(current, original) {
+  return current.sort().join() !== original.sort().join()
+}
+
+// Correct: O(1) length check first
+function hasChanges(current, original) {
+  if (current.length !== original.length) return true
+  const currentSorted = current.toSorted()
+  const originalSorted = original.toSorted()
+  for (let i = 0; i < currentSorted.length; i++) {
+    if (currentSorted[i] !== originalSorted[i]) return true
+  }
+  return false
+}
+```
+
+### 6.9 Use Loop for Min/Max Instead of Sort
+
+```typescript
+// Incorrect: O(n log n)
+function getLatestProject(projects) {
+  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+  return sorted[0]
+}
+
+// Correct: O(n)
+function getLatestProject(projects) {
+  if (projects.length === 0) return null
+  let latest = projects[0]
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt > latest.updatedAt) {
+      latest = projects[i]
+    }
+  }
+  return latest
+}
+```
+
+### 6.10 Cache Property Access in Loops
+
+```typescript
+// Incorrect: 3 lookups × N iterations
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+
+// Correct: 1 lookup total
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```
+
+### 6.11 Hoist RegExp Creation
+
+```tsx
+// Incorrect: new RegExp every render
+function Highlighter({ text, query }) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+
+// Correct: memoize
+function Highlighter({ text, query }) {
+  const regex = useMemo(
+    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+    [query]
+  )
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+### 6.12 Batch DOM CSS Changes
+
+```typescript
+// Incorrect: multiple reflows
+element.style.width = '100px'
+element.style.height = '200px'
+element.style.backgroundColor = 'blue'
+
+// Correct: single reflow via class
+element.classList.add('highlighted-box')
+
+// Or via cssText
+element.style.cssText = `
+  width: 100px;
+  height: 200px;
+  background-color: blue;
+`
+```
+
+---
+
+## 7. Advanced Patterns (LOW)
+
+### 7.1 Store Event Handlers in Refs
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event, handler) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+### 7.2 useLatest for Stable Callback Refs
+
+```typescript
+function useLatest(value) {
+  const ref = useRef(value)
+  useEffect(() => {
+    ref.current = value
+  }, [value])
+  return ref
+}
+
+// Usage: stable effect, fresh callback
+function SearchInput({ onSearch }) {
+  const [query, setQuery] = useState('')
+  const onSearchRef = useLatest(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchRef.current(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
+
+---
+
+## Anti-patterns Checklist
+
+### Critical Performance
+- [ ] Sequential awaits for independent operations
+- [ ] Barrel file imports (`import { X } from 'library'`)
+- [ ] Large arrays `.map()` without virtualization
+- [ ] `transition: all` instead of specific properties
+
+### React State
+- [ ] Mutating arrays with `.sort()` (use `.toSorted()`)
+- [ ] Missing functional setState for state-dependent updates
+- [ ] Non-lazy expensive state initialization
+- [ ] Object dependencies in useEffect (use primitives)
+
+### Rendering
+- [ ] Animating SVG elements directly (wrap in div)
+- [ ] Using `&&` with numbers (`count && <Badge />`)
+- [ ] Creating RegExp in render without memoization
+- [ ] Layout reads in render (`getBoundingClientRect`)
+
+### Events
+- [ ] Missing `{ passive: true }` for scroll/touch listeners
+- [ ] Multiple listeners for same global event
+- [ ] Non-versioned localStorage keys
+
+---
+
+## References
+
+- React: https://react.dev
+- SWR: https://swr.vercel.app
+- better-all: https://github.com/shuding/better-all
+- LRU Cache: https://github.com/isaacs/node-lru-cache
+- Vercel Blog: https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast