claude-brain 0.15.2 → 0.17.0

package/packs/frontend/react.json

@@ -1,254 +1,254 @@
-{
-  "id": "frontend/react",
-  "name": "React Patterns & Pitfalls",
-  "version": "1.0.0",
-  "stack": ["react", "next.js", "remix", "gatsby"],
-  "description": "Hooks pitfalls, state management decisions, performance optimization, and component patterns",
-  "author": "claude-brain",
-  "entries": [
-    {
-      "type": "common-issue",
-      "category": "Hooks",
-      "title": "Avoid infinite loops with useEffect dependencies",
-      "content": "Objects, arrays, and functions created during render are new references each time. Including them in useEffect deps causes infinite re-renders. Use useMemo/useCallback to stabilize references, or restructure to use primitive deps.",
-      "confidence": 0.95,
-      "tags": ["react", "hooks", "useEffect", "performance"]
-    },
-    {
-      "type": "anti-pattern",
-      "category": "Hooks",
-      "title": "Don't use useEffect for derived state",
-      "content": "Don't use useEffect to sync state derived from other state or props. Calculate it during render instead. useEffect for derived state adds unnecessary re-renders and complexity.",
-      "confidence": 0.95,
-      "tags": ["react", "hooks", "useEffect", "state"],
-      "example": "// Bad: useEffect(() => setFullName(first + last), [first, last])\n// Good: const fullName = first + ' ' + last"
-    },
-    {
-      "type": "best-practice",
-      "category": "State Management",
-      "title": "Lift state up only as far as needed",
-      "content": "Keep state as close to where it's used as possible. Only lift state to a common parent when multiple siblings need it. Over-lifting state to the top causes unnecessary re-renders.",
-      "confidence": 0.9,
-      "tags": ["react", "state", "architecture"]
-    },
-    {
-      "type": "pattern",
-      "category": "State Management",
-      "title": "Use useReducer for complex state logic",
-      "content": "When state updates depend on previous state or involve multiple related values, useReducer provides clearer intent and easier testing than multiple useState calls.",
-      "confidence": 0.85,
-      "tags": ["react", "hooks", "useReducer", "state"]
-    },
-    {
-      "type": "common-issue",
-      "category": "Hooks",
-      "title": "Stale closures in event handlers and effects",
-      "content": "Event handlers and effects capture the state/props from the render they were created in. Use refs for values that need to be always-current in callbacks, or ensure proper dependency arrays.",
-      "confidence": 0.9,
-      "tags": ["react", "hooks", "closures", "stale-state"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Performance",
-      "title": "Use React.memo sparingly and with profiling",
-      "content": "React.memo prevents re-renders when props haven't changed, but adds comparison overhead. Only use it when profiling shows a component re-renders frequently with the same props.",
-      "confidence": 0.9,
-      "tags": ["react", "performance", "memo"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Performance",
-      "title": "Use key prop correctly for list rendering",
-      "content": "Always use stable, unique keys for list items. Never use array index as key if the list can be reordered, filtered, or items inserted. Bad keys cause incorrect DOM reuse and state bugs.",
-      "confidence": 0.95,
-      "tags": ["react", "performance", "keys", "lists"]
-    },
-    {
-      "type": "pattern",
-      "category": "Components",
-      "title": "Composition over prop drilling",
-      "content": "Use component composition (children, render props, compound components) to avoid passing props through multiple intermediate layers. This keeps components focused and reduces coupling.",
-      "confidence": 0.9,
-      "tags": ["react", "composition", "patterns"]
-    },
-    {
-      "type": "anti-pattern",
-      "category": "Components",
-      "title": "Avoid defining components inside other components",
-      "content": "Never define a component inside another component's render. This creates a new component type each render, causing full unmount/remount and losing all state. Define components at module scope.",
-      "confidence": 0.95,
-      "tags": ["react", "components", "performance"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Hooks",
-      "title": "Extract custom hooks for reusable logic",
-      "content": "Extract shared stateful logic into custom hooks (useXyz). Custom hooks compose well, are independently testable, and keep components focused on rendering.",
-      "confidence": 0.9,
-      "tags": ["react", "hooks", "custom-hooks", "reuse"]
-    },
-    {
-      "type": "common-issue",
-      "category": "Hooks",
-      "title": "Follow the Rules of Hooks",
-      "content": "Hooks must be called at the top level (not inside conditions, loops, or nested functions) and only from React function components or custom hooks. Violating this causes incorrect hook state association.",
-      "confidence": 0.95,
-      "tags": ["react", "hooks", "rules"]
-    },
-    {
-      "type": "pattern",
-      "category": "Data Fetching",
-      "title": "Use a data fetching library over raw useEffect",
-      "content": "Use React Query (TanStack Query), SWR, or your framework's data fetching solution instead of raw useEffect + fetch. These handle caching, deduplication, race conditions, and background refetching.",
-      "confidence": 0.9,
-      "tags": ["react", "data-fetching", "react-query", "swr"]
-    },
-    {
-      "type": "anti-pattern",
-      "category": "State Management",
-      "title": "Avoid mirroring props in state",
-      "content": "Don't copy props into state with useState. The state won't update when props change unless you add a useEffect to sync them. Use props directly, or derive values during render.",
-      "confidence": 0.9,
-      "tags": ["react", "state", "props", "anti-pattern"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Performance",
-      "title": "Lazy load routes and heavy components",
-      "content": "Use React.lazy() and Suspense for code splitting. Lazy load routes and heavy components (charts, editors, modals) to reduce initial bundle size and improve time-to-interactive.",
-      "confidence": 0.9,
-      "tags": ["react", "performance", "lazy-loading", "code-splitting"]
-    },
-    {
-      "type": "pattern",
-      "category": "Error Handling",
-      "title": "Use Error Boundaries for resilient UI",
-      "content": "Wrap sections of your UI with Error Boundaries to catch rendering errors and show fallback UI instead of crashing the entire app. Place boundaries at route level and around risky components.",
-      "confidence": 0.9,
-      "tags": ["react", "error-handling", "error-boundary"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Hooks",
-      "title": "Use useCallback for stable event handlers",
-      "content": "Wrap event handler functions in useCallback when passing them to memoized children or using them in effect dependency arrays. This prevents unnecessary re-renders of child components.",
-      "confidence": 0.85,
-      "tags": ["react", "hooks", "useCallback", "performance"]
-    },
-    {
-      "type": "common-issue",
-      "category": "State Management",
-      "title": "Batching state updates",
-      "content": "React 18+ automatically batches state updates in event handlers, timeouts, promises, and native events. Multiple setState calls in one function only trigger one re-render.",
-      "confidence": 0.85,
-      "tags": ["react", "state", "batching", "react-18"]
-    },
-    {
-      "type": "anti-pattern",
-      "category": "State Management",
-      "title": "Avoid excessive global state",
-      "content": "Don't put everything in global state (Redux/Context). Server data belongs in a cache layer (React Query). UI state should be local. Only truly global state (auth, theme) needs a global store.",
-      "confidence": 0.9,
-      "tags": ["react", "state", "redux", "context"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Components",
-      "title": "Keep components small and focused",
-      "content": "Each component should do one thing well. If a component file exceeds 200 lines, it likely handles too many concerns. Extract sub-components, custom hooks, or utility functions.",
-      "confidence": 0.85,
-      "tags": ["react", "components", "architecture"]
-    },
-    {
-      "type": "pattern",
-      "category": "Forms",
-      "title": "Use controlled components for forms",
-      "content": "Prefer controlled components (state-driven) for forms. Use a form library (React Hook Form, Formik) for complex forms with validation, arrays, and dynamic fields.",
-      "confidence": 0.85,
-      "tags": ["react", "forms", "controlled-components"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Accessibility",
-      "title": "Use semantic HTML and ARIA attributes",
-      "content": "Use semantic HTML elements (button, nav, main, article) over generic divs. Add ARIA labels for interactive elements. Ensure keyboard navigation works for all interactive components.",
-      "confidence": 0.9,
-      "tags": ["react", "accessibility", "a11y", "html"]
-    },
-    {
-      "type": "common-issue",
-      "category": "Hooks",
-      "title": "Clean up effects to prevent memory leaks",
-      "content": "Always return a cleanup function from useEffect when subscribing to events, setting up intervals, or creating observers. Forgetting cleanup causes memory leaks and stale callbacks.",
-      "confidence": 0.9,
-      "tags": ["react", "hooks", "useEffect", "cleanup"],
-      "example": "useEffect(() => { const id = setInterval(fn, 1000); return () => clearInterval(id); }, [])"
-    },
-    {
-      "type": "pattern",
-      "category": "Performance",
-      "title": "Virtualize long lists",
-      "content": "For lists with hundreds or thousands of items, use virtualization (react-window, react-virtuoso, TanStack Virtual) to render only visible items. This dramatically improves scroll performance.",
-      "confidence": 0.9,
-      "tags": ["react", "performance", "virtualization", "lists"]
-    },
-    {
-      "type": "best-practice",
-      "category": "State Management",
-      "title": "Use server state libraries for API data",
-      "content": "Treat server data as a cache, not as state. Libraries like TanStack Query manage caching, invalidation, background updates, and optimistic updates. This removes most useState/useEffect for data fetching.",
-      "confidence": 0.9,
-      "tags": ["react", "state", "server-state", "caching"]
-    },
-    {
-      "type": "anti-pattern",
-      "category": "Hooks",
-      "title": "Avoid useEffect as an event handler",
-      "content": "Don't use useEffect to respond to user events (clicks, form submissions). Handle events directly in event handlers. useEffect is for synchronizing with external systems, not for responding to events.",
-      "confidence": 0.9,
-      "tags": ["react", "hooks", "useEffect", "events"]
-    },
-    {
-      "type": "pattern",
-      "category": "Components",
-      "title": "Use compound components for flexible APIs",
-      "content": "For complex UI components (tabs, dropdowns, accordions), use the compound component pattern with React Context. This gives consumers flexible control over rendering while keeping logic encapsulated.",
-      "confidence": 0.85,
-      "tags": ["react", "components", "compound-components", "patterns"],
-      "example": "<Tabs>\n  <Tabs.List>\n    <Tabs.Tab>One</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel>Content</Tabs.Panel>\n</Tabs>"
-    },
-    {
-      "type": "best-practice",
-      "category": "TypeScript",
-      "title": "Type component props with interfaces",
-      "content": "Define component props as interfaces or types. Use React.FC sparingly (it adds implicit children). Prefer explicit prop typing with destructuring in the function signature.",
-      "confidence": 0.85,
-      "tags": ["react", "typescript", "props", "typing"],
-      "example": "interface ButtonProps { label: string; onClick: () => void }\nfunction Button({ label, onClick }: ButtonProps) { ... }"
-    },
-    {
-      "type": "common-issue",
-      "category": "Performance",
-      "title": "Avoid creating new objects in JSX props",
-      "content": "Inline objects and arrays in JSX (`style={{ color: 'red' }}`, `data={[1,2,3]}`) create new references each render. Move static values outside the component or use useMemo for dynamic ones.",
-      "confidence": 0.85,
-      "tags": ["react", "performance", "rendering"]
-    },
-    {
-      "type": "best-practice",
-      "category": "Testing",
-      "title": "Test behavior, not implementation",
-      "content": "Test what the user sees and interacts with, not component internals. Use React Testing Library to query by role, text, and labels. Avoid testing state values or implementation details directly.",
-      "confidence": 0.9,
-      "tags": ["react", "testing", "react-testing-library"]
-    },
-    {
-      "type": "pattern",
-      "category": "Hooks",
-      "title": "Use useId for accessibility IDs",
-      "content": "Use React.useId() to generate stable, unique IDs for accessibility attributes (htmlFor, aria-describedby). This works correctly with server-side rendering unlike random ID generation.",
-      "confidence": 0.8,
-      "tags": ["react", "hooks", "accessibility", "ssr"]
-    }
-  ]
-}
+{
+  "id": "frontend/react",
+  "name": "React Patterns & Pitfalls",
+  "version": "1.0.0",
+  "stack": ["react", "next.js", "remix", "gatsby"],
+  "description": "Hooks pitfalls, state management decisions, performance optimization, and component patterns",
+  "author": "claude-brain",
+  "entries": [
+    {
+      "type": "common-issue",
+      "category": "Hooks",
+      "title": "Avoid infinite loops with useEffect dependencies",
+      "content": "Objects, arrays, and functions created during render are new references each time. Including them in useEffect deps causes infinite re-renders. Use useMemo/useCallback to stabilize references, or restructure to use primitive deps.",
+      "confidence": 0.95,
+      "tags": ["react", "hooks", "useEffect", "performance"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Hooks",
+      "title": "Don't use useEffect for derived state",
+      "content": "Don't use useEffect to sync state derived from other state or props. Calculate it during render instead. useEffect for derived state adds unnecessary re-renders and complexity.",
+      "confidence": 0.95,
+      "tags": ["react", "hooks", "useEffect", "state"],
+      "example": "// Bad: useEffect(() => setFullName(first + last), [first, last])\n// Good: const fullName = first + ' ' + last"
+    },
+    {
+      "type": "best-practice",
+      "category": "State Management",
+      "title": "Lift state up only as far as needed",
+      "content": "Keep state as close to where it's used as possible. Only lift state to a common parent when multiple siblings need it. Over-lifting state to the top causes unnecessary re-renders.",
+      "confidence": 0.9,
+      "tags": ["react", "state", "architecture"]
+    },
+    {
+      "type": "pattern",
+      "category": "State Management",
+      "title": "Use useReducer for complex state logic",
+      "content": "When state updates depend on previous state or involve multiple related values, useReducer provides clearer intent and easier testing than multiple useState calls.",
+      "confidence": 0.85,
+      "tags": ["react", "hooks", "useReducer", "state"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Hooks",
+      "title": "Stale closures in event handlers and effects",
+      "content": "Event handlers and effects capture the state/props from the render they were created in. Use refs for values that need to be always-current in callbacks, or ensure proper dependency arrays.",
+      "confidence": 0.9,
+      "tags": ["react", "hooks", "closures", "stale-state"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Performance",
+      "title": "Use React.memo sparingly and with profiling",
+      "content": "React.memo prevents re-renders when props haven't changed, but adds comparison overhead. Only use it when profiling shows a component re-renders frequently with the same props.",
+      "confidence": 0.9,
+      "tags": ["react", "performance", "memo"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Performance",
+      "title": "Use key prop correctly for list rendering",
+      "content": "Always use stable, unique keys for list items. Never use array index as key if the list can be reordered, filtered, or items inserted. Bad keys cause incorrect DOM reuse and state bugs.",
+      "confidence": 0.95,
+      "tags": ["react", "performance", "keys", "lists"]
+    },
+    {
+      "type": "pattern",
+      "category": "Components",
+      "title": "Composition over prop drilling",
+      "content": "Use component composition (children, render props, compound components) to avoid passing props through multiple intermediate layers. This keeps components focused and reduces coupling.",
+      "confidence": 0.9,
+      "tags": ["react", "composition", "patterns"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Components",
+      "title": "Avoid defining components inside other components",
+      "content": "Never define a component inside another component's render. This creates a new component type each render, causing full unmount/remount and losing all state. Define components at module scope.",
+      "confidence": 0.95,
+      "tags": ["react", "components", "performance"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Hooks",
+      "title": "Extract custom hooks for reusable logic",
+      "content": "Extract shared stateful logic into custom hooks (useXyz). Custom hooks compose well, are independently testable, and keep components focused on rendering.",
+      "confidence": 0.9,
+      "tags": ["react", "hooks", "custom-hooks", "reuse"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Hooks",
+      "title": "Follow the Rules of Hooks",
+      "content": "Hooks must be called at the top level (not inside conditions, loops, or nested functions) and only from React function components or custom hooks. Violating this causes incorrect hook state association.",
+      "confidence": 0.95,
+      "tags": ["react", "hooks", "rules"]
+    },
+    {
+      "type": "pattern",
+      "category": "Data Fetching",
+      "title": "Use a data fetching library over raw useEffect",
+      "content": "Use React Query (TanStack Query), SWR, or your framework's data fetching solution instead of raw useEffect + fetch. These handle caching, deduplication, race conditions, and background refetching.",
+      "confidence": 0.9,
+      "tags": ["react", "data-fetching", "react-query", "swr"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "State Management",
+      "title": "Avoid mirroring props in state",
+      "content": "Don't copy props into state with useState. The state won't update when props change unless you add a useEffect to sync them. Use props directly, or derive values during render.",
+      "confidence": 0.9,
+      "tags": ["react", "state", "props", "anti-pattern"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Performance",
+      "title": "Lazy load routes and heavy components",
+      "content": "Use React.lazy() and Suspense for code splitting. Lazy load routes and heavy components (charts, editors, modals) to reduce initial bundle size and improve time-to-interactive.",
+      "confidence": 0.9,
+      "tags": ["react", "performance", "lazy-loading", "code-splitting"]
+    },
+    {
+      "type": "pattern",
+      "category": "Error Handling",
+      "title": "Use Error Boundaries for resilient UI",
+      "content": "Wrap sections of your UI with Error Boundaries to catch rendering errors and show fallback UI instead of crashing the entire app. Place boundaries at route level and around risky components.",
+      "confidence": 0.9,
+      "tags": ["react", "error-handling", "error-boundary"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Hooks",
+      "title": "Use useCallback for stable event handlers",
+      "content": "Wrap event handler functions in useCallback when passing them to memoized children or using them in effect dependency arrays. This prevents unnecessary re-renders of child components.",
+      "confidence": 0.85,
+      "tags": ["react", "hooks", "useCallback", "performance"]
+    },
+    {
+      "type": "common-issue",
+      "category": "State Management",
+      "title": "Batching state updates",
+      "content": "React 18+ automatically batches state updates in event handlers, timeouts, promises, and native events. Multiple setState calls in one function only trigger one re-render.",
+      "confidence": 0.85,
+      "tags": ["react", "state", "batching", "react-18"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "State Management",
+      "title": "Avoid excessive global state",
+      "content": "Don't put everything in global state (Redux/Context). Server data belongs in a cache layer (React Query). UI state should be local. Only truly global state (auth, theme) needs a global store.",
+      "confidence": 0.9,
+      "tags": ["react", "state", "redux", "context"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Components",
+      "title": "Keep components small and focused",
+      "content": "Each component should do one thing well. If a component file exceeds 200 lines, it likely handles too many concerns. Extract sub-components, custom hooks, or utility functions.",
+      "confidence": 0.85,
+      "tags": ["react", "components", "architecture"]
+    },
+    {
+      "type": "pattern",
+      "category": "Forms",
+      "title": "Use controlled components for forms",
+      "content": "Prefer controlled components (state-driven) for forms. Use a form library (React Hook Form, Formik) for complex forms with validation, arrays, and dynamic fields.",
+      "confidence": 0.85,
+      "tags": ["react", "forms", "controlled-components"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Accessibility",
+      "title": "Use semantic HTML and ARIA attributes",
+      "content": "Use semantic HTML elements (button, nav, main, article) over generic divs. Add ARIA labels for interactive elements. Ensure keyboard navigation works for all interactive components.",
+      "confidence": 0.9,
+      "tags": ["react", "accessibility", "a11y", "html"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Hooks",
+      "title": "Clean up effects to prevent memory leaks",
+      "content": "Always return a cleanup function from useEffect when subscribing to events, setting up intervals, or creating observers. Forgetting cleanup causes memory leaks and stale callbacks.",
+      "confidence": 0.9,
+      "tags": ["react", "hooks", "useEffect", "cleanup"],
+      "example": "useEffect(() => { const id = setInterval(fn, 1000); return () => clearInterval(id); }, [])"
+    },
+    {
+      "type": "pattern",
+      "category": "Performance",
+      "title": "Virtualize long lists",
+      "content": "For lists with hundreds or thousands of items, use virtualization (react-window, react-virtuoso, TanStack Virtual) to render only visible items. This dramatically improves scroll performance.",
+      "confidence": 0.9,
+      "tags": ["react", "performance", "virtualization", "lists"]
+    },
+    {
+      "type": "best-practice",
+      "category": "State Management",
+      "title": "Use server state libraries for API data",
+      "content": "Treat server data as a cache, not as state. Libraries like TanStack Query manage caching, invalidation, background updates, and optimistic updates. This removes most useState/useEffect for data fetching.",
+      "confidence": 0.9,
+      "tags": ["react", "state", "server-state", "caching"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Hooks",
+      "title": "Avoid useEffect as an event handler",
+      "content": "Don't use useEffect to respond to user events (clicks, form submissions). Handle events directly in event handlers. useEffect is for synchronizing with external systems, not for responding to events.",
+      "confidence": 0.9,
+      "tags": ["react", "hooks", "useEffect", "events"]
+    },
+    {
+      "type": "pattern",
+      "category": "Components",
+      "title": "Use compound components for flexible APIs",
+      "content": "For complex UI components (tabs, dropdowns, accordions), use the compound component pattern with React Context. This gives consumers flexible control over rendering while keeping logic encapsulated.",
+      "confidence": 0.85,
+      "tags": ["react", "components", "compound-components", "patterns"],
+      "example": "<Tabs>\n  <Tabs.List>\n    <Tabs.Tab>One</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel>Content</Tabs.Panel>\n</Tabs>"
+    },
+    {
+      "type": "best-practice",
+      "category": "TypeScript",
+      "title": "Type component props with interfaces",
+      "content": "Define component props as interfaces or types. Use React.FC sparingly (it adds implicit children). Prefer explicit prop typing with destructuring in the function signature.",
+      "confidence": 0.85,
+      "tags": ["react", "typescript", "props", "typing"],
+      "example": "interface ButtonProps { label: string; onClick: () => void }\nfunction Button({ label, onClick }: ButtonProps) { ... }"
+    },
+    {
+      "type": "common-issue",
+      "category": "Performance",
+      "title": "Avoid creating new objects in JSX props",
+      "content": "Inline objects and arrays in JSX (`style={{ color: 'red' }}`, `data={[1,2,3]}`) create new references each render. Move static values outside the component or use useMemo for dynamic ones.",
+      "confidence": 0.85,
+      "tags": ["react", "performance", "rendering"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Testing",
+      "title": "Test behavior, not implementation",
+      "content": "Test what the user sees and interacts with, not component internals. Use React Testing Library to query by role, text, and labels. Avoid testing state values or implementation details directly.",
+      "confidence": 0.9,
+      "tags": ["react", "testing", "react-testing-library"]
+    },
+    {
+      "type": "pattern",
+      "category": "Hooks",
+      "title": "Use useId for accessibility IDs",
+      "content": "Use React.useId() to generate stable, unique IDs for accessibility attributes (htmlFor, aria-describedby). This works correctly with server-side rendering unlike random ID generation.",
+      "confidence": 0.8,
+      "tags": ["react", "hooks", "accessibility", "ssr"]
+    }
+  ]
+}