@brookmind/ai-toolkit 1.0.5 → 1.1.2

package/skills/react-best-practices/AGENTS.md

@@ -0,0 +1,915 @@
+# React Best Practices - Compiled Rules
+
+> Performance optimization guidelines for React 19 applications. Contains 35+ rules across 7 categories, prioritized by impact.
+
+**Last Updated:** January 2026
+**React Version:** 19
+**Target:** Client-side SPA (Vite, etc.)
+
+---
+
+## Table of Contents
+
+1. [Eliminating Waterfalls](#1-eliminating-waterfalls-critical) (CRITICAL)
+2. [Bundle Size Optimization](#2-bundle-size-optimization-critical) (CRITICAL)
+3. [Client-Side Data Fetching](#3-client-side-data-fetching-medium-high) (MEDIUM-HIGH)
+4. [Re-render Optimization](#4-re-render-optimization-medium) (MEDIUM)
+5. [Rendering Performance](#5-rendering-performance-medium) (MEDIUM)
+6. [JavaScript Performance](#6-javascript-performance-low-medium) (LOW-MEDIUM)
+7. [Advanced Patterns](#7-advanced-patterns-low) (LOW)
+
+---
+
+## 1. Eliminating Waterfalls (CRITICAL)
+
+Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+### Promise.all() for Independent Operations
+
+**Impact:** CRITICAL (2-10× improvement)
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser();
+const posts = await fetchPosts();
+const comments = await fetchComments();
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments(),
+]);
+```
+
+### Dependency-Based Parallelization
+
+**Impact:** CRITICAL (2-10× improvement)
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([fetchUser(), fetchConfig()]);
+const profile = await fetchProfile(user.id);
+```
+
+**Correct (config and profile run in parallel):**
+
+```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);
+  },
+});
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+
+### Defer Await Until Needed
+
+**Impact:** HIGH
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+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):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    return { skipped: true };
+  }
+
+  const userData = await fetchUserData(userId);
+  return processUserData(userData);
+}
+```
+
+### Strategic Suspense Boundaries
+
+**Impact:** HIGH (faster initial paint)
+
+Use Suspense boundaries to show wrapper UI immediately while data loads asynchronously.
+
+**Incorrect (entire component waits for data):**
+
+```tsx
+function Page() {
+  const { data, isLoading } = useQuery(['data'], fetchData);
+
+  if (isLoading) return <Skeleton />;
+
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  );
+}
+```
+
+**Correct (wrapper shows immediately):**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  );
+}
+
+function DataDisplay() {
+  const { data } = useSuspenseQuery(['data'], fetchData);
+  return <div>{data.content}</div>;
+}
+```
+
+**With React 19 use() hook:**
+
+```tsx
+function Page() {
+  const dataPromise = useMemo(() => fetchData(), []);
+
+  return (
+    <Suspense fallback={<Skeleton />}>
+      <DataDisplay dataPromise={dataPromise} />
+    </Suspense>
+  );
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise);
+  return <div>{data.content}</div>;
+}
+```
+
+---
+
+## 2. Bundle Size Optimization (CRITICAL)
+
+Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+### Avoid Barrel File Imports
+
+**Impact:** CRITICAL (200-800ms import cost)
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules.
+
+**Incorrect (imports entire library):**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react';
+// Loads 1,583 modules, takes ~2.8s extra in dev
+
+import { Button, TextField } from '@mui/material';
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct (imports only what you need):**
+
+```tsx
+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';
+
+import Button from '@mui/material/Button';
+import TextField from '@mui/material/TextField';
+```
+
+Commonly affected libraries: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `lodash`, `date-fns`.
+
+### Conditional Module Loading
+
+**Impact:** HIGH
+
+Load large data or modules only when a feature is activated.
+
+**React 19 with use() and Suspense (Recommended):**
+
+```tsx
+import { use, Suspense, useMemo } from 'react';
+
+function AnimationPlayer({ enabled }: { enabled: boolean }) {
+  const framesPromise = useMemo(
+    () =>
+      enabled ? import('./animation-frames.js').then((m) => m.frames) : null,
+    [enabled]
+  );
+
+  if (!framesPromise) return null;
+
+  const frames = use(framesPromise);
+  return <Canvas frames={frames} />;
+}
+
+function AnimationSection({ enabled }: { enabled: boolean }) {
+  return (
+    <Suspense fallback={<Skeleton />}>
+      <AnimationPlayer enabled={enabled} />
+    </Suspense>
+  );
+}
+```
+
+**With React.lazy:**
+
+```tsx
+const HeavyEditor = lazy(() => import('./HeavyEditor'));
+
+function EditorSection({ showEditor }: { showEditor: boolean }) {
+  if (!showEditor) return null;
+
+  return (
+    <Suspense fallback={<EditorSkeleton />}>
+      <HeavyEditor />
+    </Suspense>
+  );
+}
+```
+
+### Preload Based on User Intent
+
+**Impact:** MEDIUM
+
+Preload heavy bundles on hover/focus to reduce perceived latency.
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    void import('./monaco-editor');
+  };
+
+  return (
+    <button onMouseEnter={preload} onFocus={preload} onClick={onClick}>
+      Open Editor
+    </button>
+  );
+}
+```
+
+---
+
+## 3. Client-Side Data Fetching (MEDIUM-HIGH)
+
+Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+### Use React Query for Automatic Deduplication
+
+**Impact:** MEDIUM-HIGH
+
+TanStack Query (React Query 5) enables request deduplication, caching, and stale-while-revalidate patterns.
+
+**Incorrect (each instance fetches):**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState<User[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/users')
+      .then((r) => r.json())
+      .then(setUsers)
+      .finally(() => setIsLoading(false));
+  }, []);
+
+  // ...
+}
+```
+
+**Correct (multiple instances share one request):**
+
+```tsx
+import { useQuery } from '@tanstack/react-query';
+
+function UserList() {
+  const { data: users, isLoading } = useQuery({
+    queryKey: ['users'],
+    queryFn: () => fetch('/api/users').then((r) => r.json()),
+  });
+
+  if (isLoading) return <Skeleton />;
+  return (
+    <ul>
+      {users.map((u) => (
+        <li key={u.id}>{u.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+**With Suspense (React 19):**
+
+```tsx
+import { useSuspenseQuery } from '@tanstack/react-query';
+
+function UserList() {
+  const { data: users } = useSuspenseQuery({
+    queryKey: ['users'],
+    queryFn: fetchUsers,
+  });
+
+  return (
+    <ul>
+      {users.map((u) => (
+        <li key={u.id}>{u.name}</li>
+      ))}
+    </ul>
+  );
+}
+
+// Parent
+<Suspense fallback={<Skeleton />}>
+  <UserList />
+</Suspense>;
+```
+
+### Deduplicate Global Event Listeners
+
+**Impact:** MEDIUM (single listener for N components)
+
+Use `useSyncExternalStore` to share global event listeners across component instances.
+
+**Incorrect (N instances = N listeners):**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) callback();
+    };
+    window.addEventListener('keydown', handler);
+    return () => window.removeEventListener('keydown', handler);
+  }, [key, callback]);
+}
+```
+
+**Correct (N instances = 1 listener):**
+
+```tsx
+import { useSyncExternalStore } from 'react';
+
+function useOnlineStatus() {
+  return useSyncExternalStore(
+    (callback) => {
+      window.addEventListener('online', callback);
+      window.addEventListener('offline', callback);
+      return () => {
+        window.removeEventListener('online', callback);
+        window.removeEventListener('offline', callback);
+      };
+    },
+    () => navigator.onLine,
+    () => true
+  );
+}
+```
+
+Reference: [React useSyncExternalStore](https://react.dev/reference/react/useSyncExternalStore)
+
+---
+
+## 4. Re-render Optimization (MEDIUM)
+
+Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+### Extract to Memoized Components
+
+**Impact:** MEDIUM
+
+**With React 19 Compiler (Recommended):**
+
+The compiler automatically memoizes components. Just write clean code:
+
+```tsx
+function UserAvatar({ user }: { user: User }) {
+  const id = computeAvatarId(user);
+  return <Avatar id={id} />;
+}
+```
+
+**Without React Compiler (Manual):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user]);
+  return <Avatar id={id} />;
+});
+```
+
+### Use Functional setState Updates
+
+**Impact:** MEDIUM
+
+Use functional update form to prevent stale closures and create stable callbacks.
+
+**Incorrect:**
+
+```tsx
+const addItems = useCallback(
+  (newItems: Item[]) => {
+    setItems([...items, ...newItems]);
+  },
+  [items]
+); // Recreated on every items change
+```
+
+**Correct:**
+
+```tsx
+const addItems = useCallback((newItems: Item[]) => {
+  setItems((curr) => [...curr, ...newItems]);
+}, []); // Stable, never recreated
+```
+
+### Use Lazy State Initialization
+
+**Impact:** MEDIUM
+
+Pass a function to `useState` for expensive initial values.
+
+**Incorrect (runs on every render):**
+
+```tsx
+const [searchIndex] = useState(buildSearchIndex(items));
+```
+
+**Correct (runs only once):**
+
+```tsx
+const [searchIndex] = useState(() => buildSearchIndex(items));
+```
+
+### Use Transitions for Non-Urgent Updates
+
+**Impact:** MEDIUM
+
+Mark frequent, non-urgent state updates as transitions.
+
+```tsx
+import { startTransition } from 'react';
+
+const handler = () => {
+  startTransition(() => setScrollY(window.scrollY));
+};
+window.addEventListener('scroll', handler, { passive: true });
+```
+
+### Subscribe to Derived State
+
+**Impact:** MEDIUM
+
+Subscribe to derived boolean state instead of continuous values.
+
+**Incorrect (re-renders on every pixel):**
+
+```tsx
+const width = useWindowWidth();
+const isMobile = width < 768;
+```
+
+**Correct (re-renders only on boolean change):**
+
+```tsx
+const isMobile = useMediaQuery('(max-width: 767px)');
+```
+
+### Defer State Reads to Usage Point
+
+**Impact:** MEDIUM
+
+Don't subscribe to dynamic state if you only read it inside callbacks.
+
+**Incorrect:**
+
+```tsx
+const searchParams = useSearchParams();
+const handleShare = () => {
+  const ref = searchParams.get('ref');
+  shareChat(chatId, { ref });
+};
+```
+
+**Correct:**
+
+```tsx
+const handleShare = () => {
+  const params = new URLSearchParams(window.location.search);
+  const ref = params.get('ref');
+  shareChat(chatId, { ref });
+};
+```
+
+### Narrow Effect Dependencies
+
+**Impact:** LOW
+
+Specify primitive dependencies instead of objects.
+
+**Incorrect:**
+
+```tsx
+useEffect(() => {
+  console.log(user.id);
+}, [user]);
+```
+
+**Correct:**
+
+```tsx
+useEffect(() => {
+  console.log(user.id);
+}, [user.id]);
+```
+
+---
+
+## 5. Rendering Performance (MEDIUM)
+
+Optimizing the rendering process reduces the work the browser needs to do.
+
+### CSS content-visibility for Long Lists
+
+**Impact:** HIGH (10× faster initial render)
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+### Preserve State for Hidden Components
+
+**Impact:** MEDIUM
+
+Use CSS visibility instead of conditional rendering to preserve state.
+
+**Incorrect (unmounts, loses state):**
+
+```tsx
+return isOpen ? <ExpensiveMenu /> : null;
+```
+
+**Correct (stays mounted):**
+
+```tsx
+<div style={{ display: isOpen ? 'block' : 'none' }}>
+  <ExpensiveMenu />
+</div>
+```
+
+### Hoist Static JSX Elements
+
+**Impact:** LOW
+
+**With React 19 Compiler:** Automatic - just write normal components.
+
+**Without Compiler:**
+
+```tsx
+// Hoisted to module scope
+const loadingSkeleton = <div className="animate-pulse h-20 bg-gray-200" />;
+
+function Container({ loading }: { loading: boolean }) {
+  return <div>{loading && loadingSkeleton}</div>;
+}
+```
+
+### Animate SVG Wrapper Instead of SVG
+
+**Impact:** LOW (enables hardware acceleration)
+
+```tsx
+// Incorrect
+<svg className="animate-spin">...</svg>
+
+// Correct
+<div className="animate-spin">
+  <svg>...</svg>
+</div>
+```
+
+### Use Explicit Conditional Rendering
+
+**Impact:** LOW (prevents rendering 0 or NaN)
+
+```tsx
+// Incorrect (renders "0")
+{
+  count && <span>{count}</span>;
+}
+
+// Correct
+{
+  count > 0 ? <span>{count}</span> : null;
+}
+```
+
+### Optimize SVG Precision
+
+**Impact:** LOW
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```
+
+---
+
+## 6. JavaScript Performance (LOW-MEDIUM)
+
+Micro-optimizations for hot paths can add up to meaningful improvements.
+
+### Use toSorted() for Immutability
+
+**Impact:** MEDIUM-HIGH
+
+```typescript
+// Incorrect (mutates array)
+const sorted = users.sort((a, b) => a.name.localeCompare(b.name));
+
+// Correct (creates new array)
+const sorted = users.toSorted((a, b) => a.name.localeCompare(b.name));
+```
+
+### Cache Repeated Function Calls
+
+**Impact:** MEDIUM
+
+```typescript
+const slugifyCache = new Map<string, string>();
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) return slugifyCache.get(text)!;
+  const result = slugify(text);
+  slugifyCache.set(text, result);
+  return result;
+}
+```
+
+### Batch DOM CSS Changes
+
+**Impact:** MEDIUM
+
+```tsx
+// Incorrect (multiple reflows)
+element.style.width = '100px';
+element.style.height = '200px';
+
+// Correct (single reflow)
+element.classList.add('highlighted-box');
+```
+
+### Early Length Check for Array Comparisons
+
+**Impact:** MEDIUM-HIGH
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  if (current.length !== original.length) return true;
+  // ... expensive comparison
+}
+```
+
+### Use Set/Map for O(1) Lookups
+
+**Impact:** LOW-MEDIUM
+
+```typescript
+// Incorrect O(n)
+items.filter((item) => allowedIds.includes(item.id));
+
+// Correct O(1)
+const allowedSet = new Set(allowedIds);
+items.filter((item) => allowedSet.has(item.id));
+```
+
+### Build Index Maps for Repeated Lookups
+
+**Impact:** LOW-MEDIUM
+
+```typescript
+const userById = new Map(users.map((u) => [u.id, u]));
+orders.map((order) => ({ ...order, user: userById.get(order.userId) }));
+```
+
+### Use Loop for Min/Max Instead of Sort
+
+**Impact:** LOW (O(n) instead of O(n log n))
+
+```typescript
+let latest = projects[0];
+for (let i = 1; i < projects.length; i++) {
+  if (projects[i].updatedAt > latest.updatedAt) latest = projects[i];
+}
+```
+
+### Cache Storage API Calls
+
+**Impact:** LOW-MEDIUM
+
+```typescript
+const storageCache = new Map<string, string | null>();
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key));
+  }
+  return storageCache.get(key);
+}
+```
+
+### Early Return from Functions
+
+**Impact:** LOW-MEDIUM
+
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) return { valid: false, error: 'Email required' };
+  }
+  return { valid: true };
+}
+```
+
+### Combine Multiple Array Iterations
+
+**Impact:** LOW-MEDIUM
+
+```typescript
+// Incorrect (3 iterations)
+const admins = users.filter((u) => u.isAdmin);
+const testers = users.filter((u) => u.isTester);
+
+// Correct (1 iteration)
+const admins: User[] = [],
+  testers: User[] = [];
+for (const user of users) {
+  if (user.isAdmin) admins.push(user);
+  if (user.isTester) testers.push(user);
+}
+```
+
+### Hoist RegExp Creation
+
+**Impact:** LOW-MEDIUM
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+function Highlighter({ text, query }: Props) {
+  const regex = useMemo(() => new RegExp(`(${query})`, 'gi'), [query]);
+  // ...
+}
+```
+
+### Cache Property Access in Loops
+
+**Impact:** LOW-MEDIUM
+
+```typescript
+const value = obj.config.settings.value;
+const len = arr.length;
+for (let i = 0; i < len; i++) {
+  process(value);
+}
+```
+
+---
+
+## 7. Advanced Patterns (LOW)
+
+Advanced patterns for specific cases that require careful implementation.
+
+### Stable Event Callbacks with useEffectEvent
+
+**Impact:** MEDIUM
+
+Use `useEffectEvent` (React 19) to access latest values in effect callbacks without adding them to dependency arrays.
+
+**Incorrect:**
+
+```tsx
+useEffect(() => {
+  const timeout = setTimeout(() => onSearch(query), 300);
+  return () => clearTimeout(timeout);
+}, [query, onSearch]); // onSearch causes unnecessary re-runs
+```
+
+**Correct (React 19):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+const onSearchEvent = useEffectEvent((q: string) => onSearch(q));
+
+useEffect(() => {
+  const timeout = setTimeout(() => onSearchEvent(query), 300);
+  return () => clearTimeout(timeout);
+}, [query]); // No need to include onSearchEvent
+```
+
+**Legacy fallback (pre-React 19):**
+
+```tsx
+function useLatest<T>(value: T) {
+  const ref = useRef(value);
+  useEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref;
+}
+
+const onSearchRef = useLatest(onSearch);
+useEffect(() => {
+  const timeout = setTimeout(() => onSearchRef.current(query), 300);
+  return () => clearTimeout(timeout);
+}, [query]);
+```
+
+### Stable Event Handler References
+
+**Impact:** MEDIUM
+
+Use `useEffectEvent` for stable event handler references in effects.
+
+**React 19:**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function useWindowEvent(event: string, handler: () => void) {
+  const onEvent = useEffectEvent(handler);
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent);
+    return () => window.removeEventListener(event, onEvent);
+  }, [event]);
+}
+```
+
+**Legacy fallback:**
+
+```tsx
+function useWindowEvent(event: string, handler: () => void) {
+  const handlerRef = useRef(handler);
+  useEffect(() => {
+    handlerRef.current = handler;
+  }, [handler]);
+
+  useEffect(() => {
+    const listener = () => handlerRef.current();
+    window.addEventListener(event, listener);
+    return () => window.removeEventListener(event, listener);
+  }, [event]);
+}
+```
+
+---
+
+## References
+
+- [React Compiler](https://react.dev/learn/react-compiler)
+- [TanStack Query](https://tanstack.com/query)
+- [useSyncExternalStore](https://react.dev/reference/react/useSyncExternalStore)
+- [useEffectEvent RFC](https://react.dev/learn/separating-events-from-effects)