Frontend React Best Practices

1---2name: frontend-react-best-practices3description: React performance optimization guidelines. Use when writing, reviewing, or refactoring React components to ensure optimal rendering and bundle patterns. Triggers on tasks involving React components, hooks, memoization, or bundle optimization.4---5 6# React Best Practices7 8Performance optimization and composition patterns for React components. Contains 33 rules across 6 categories focused on reducing re-renders, optimizing bundles, component composition, and avoiding common React pitfalls.9 10## When to Apply11 12Reference these guidelines when:13 14- Writing new React components15- Reviewing code for performance issues16- Refactoring existing React code17- Optimizing bundle size18- Working with hooks and state19 20## Rules Summary21 22### Bundle Size Optimization (CRITICAL)23 24#### bundle-barrel-imports - @rules/bundle-barrel-imports.md25 26Import directly from source, avoid barrel files.27 28```tsx29// Bad: loads entire library (200-800ms)30import { Check, X } from "lucide-react";31 32// Good: loads only what you need33import Check from "lucide-react/dist/esm/icons/check";34import X from "lucide-react/dist/esm/icons/x";35```36 37#### bundle-conditional - @rules/bundle-conditional.md38 39Load modules only when feature is activated.40 41```tsx42useEffect(() => {43  if (enabled && typeof window !== "undefined") {44    import("./heavy-module").then((mod) => setModule(mod));45  }46}, [enabled]);47```48 49#### bundle-preload - @rules/bundle-preload.md50 51Preload on hover/focus for perceived speed.52 53```tsx54<button55  onMouseEnter={() => import("./editor")}56  onFocus={() => import("./editor")}57  onClick={openEditor}58>59  Open Editor60</button>61```62 63### Re-render Optimization (MEDIUM)64 65#### rerender-functional-setstate - @rules/rerender-functional-setstate.md66 67Use functional setState for stable callbacks.68 69```tsx70// Bad: stale closure risk, recreates on items change71const addItem = useCallback(72  (item) => {73    setItems([...items, item]);74  },75  [items],76);77 78// Good: always uses latest state, stable reference79const addItem = useCallback((item) => {80  setItems((curr) => [...curr, item]);81}, []);82```83 84#### rerender-derived-state-no-effect - @rules/rerender-derived-state-no-effect.md85 86Derive state during render, not in effects.87 88```tsx89// Bad: extra state and effect, extra render90const [fullName, setFullName] = useState("");91useEffect(() => {92  setFullName(firstName + " " + lastName);93}, [firstName, lastName]);94 95// Good: derived directly during render96const fullName = firstName + " " + lastName;97```98 99#### rerender-lazy-state-init - @rules/rerender-lazy-state-init.md100 101Pass function to useState for expensive initial values.102 103```tsx104// Bad: runs expensiveComputation() on every render105const [data] = useState(expensiveComputation());106 107// Good: runs only on initial render108const [data] = useState(() => expensiveComputation());109```110 111#### rerender-dependencies - @rules/rerender-dependencies.md112 113Use primitive dependencies in effects.114 115```tsx116// Bad: runs on any user field change117useEffect(() => {118  console.log(user.id);119}, [user]);120 121// Good: runs only when id changes122useEffect(() => {123  console.log(user.id);124}, [user.id]);125```126 127#### rerender-derived-state - @rules/rerender-derived-state.md128 129Subscribe to derived booleans, not raw values.130 131```tsx132// Bad: re-renders on every pixel change133const width = useWindowWidth();134const isMobile = width < 768;135 136// Good: re-renders only when boolean changes137const isMobile = useMediaQuery("(max-width: 767px)");138```139 140#### rerender-memo - @rules/rerender-memo.md141 142Extract expensive work into memoized components.143 144```tsx145// Good: skips computation when loading146const UserAvatar = memo(function UserAvatar({ user }) {147  let id = useMemo(() => computeAvatarId(user), [user]);148  return <Avatar id={id} />;149});150 151function Profile({ user, loading }) {152  if (loading) return <Skeleton />;153  return <UserAvatar user={user} />;154}155```156 157#### rerender-memo-with-default-value - @rules/rerender-memo-with-default-value.md158 159Hoist default non-primitive props to constants.160 161```tsx162// Bad: breaks memoization (new function each render)163const Button = memo(({ onClick = () => {} }) => ...)164 165// Good: stable default value166const NOOP = () => {}167const Button = memo(({ onClick = NOOP }) => ...)168```169 170#### rerender-simple-expression-in-memo - @rules/rerender-simple-expression-in-memo.md171 172Don't wrap simple primitive expressions in useMemo.173 174```tsx175// Bad: useMemo overhead > expression cost176const isLoading = useMemo(() => a.loading || b.loading, [a.loading, b.loading]);177 178// Good: just compute it179const isLoading = a.loading || b.loading;180```181 182#### rerender-move-effect-to-event - @rules/rerender-move-effect-to-event.md183 184Put interaction logic in event handlers, not effects.185 186```tsx187// Bad: effect re-runs on theme change188useEffect(() => {189  if (submitted) post("/api/register");190}, [submitted, theme]);191 192// Good: in handler193const handleSubmit = () => post("/api/register");194```195 196#### rerender-transitions - @rules/rerender-transitions.md197 198Use startTransition for non-urgent updates.199 200```tsx201// Good: non-blocking scroll tracking202const handler = () => {203  startTransition(() => setScrollY(window.scrollY));204};205```206 207#### rerender-use-ref-transient-values - @rules/rerender-use-ref-transient-values.md208 209Use refs for transient frequent values.210 211```tsx212// Good: no re-render, direct DOM update213const lastXRef = useRef(0);214const dotRef = useRef<HTMLDivElement>(null);215 216useEffect(() => {217  let onMove = (e) => {218    lastXRef.current = e.clientX;219    dotRef.current?.style.transform = `translateX(${e.clientX}px)`;220  };221  window.addEventListener("mousemove", onMove);222  return () => window.removeEventListener("mousemove", onMove);223}, []);224```225 226### Rendering Performance (MEDIUM)227 228#### rendering-conditional-render - @rules/rendering-conditional-render.md229 230Use ternary, not && for conditionals with numbers.231 232```tsx233// Bad: renders "0" when count is 0234{235  count && <Badge>{count}</Badge>;236}237 238// Good: renders nothing when count is 0239{240  count > 0 ? <Badge>{count}</Badge> : null;241}242```243 244#### rendering-hoist-jsx - @rules/rendering-hoist-jsx.md245 246Extract static JSX outside components.247 248```tsx249// Good: reuses same element, especially for large SVGs250const skeleton = <div className="animate-pulse h-20 bg-gray-200" />;251 252function Container({ loading }) {253  return loading ? skeleton : <Content />;254}255```256 257#### rendering-content-visibility - @rules/rendering-content-visibility.md258 259Use content-visibility for long lists.260 261```css262.list-item {263  content-visibility: auto;264  contain-intrinsic-size: 0 80px;265}266```267 268#### rendering-animate-svg-wrapper - @rules/rendering-animate-svg-wrapper.md269 270Animate wrapper div, not SVG element (for GPU acceleration).271 272```tsx273// Good: hardware accelerated274<div className="animate-spin">275  <svg>...</svg>276</div>277```278 279#### rendering-svg-precision - @rules/rendering-svg-precision.md280 281Reduce SVG coordinate precision with SVGO.282 283```bash284npx svgo --precision=1 --multipass icon.svg285```286 287#### rendering-hydration-no-flicker - @rules/rendering-hydration-no-flicker.md288 289Use inline script for client-only data to prevent flicker.290 291```tsx292<div id="theme-wrapper">{children}</div>293<script dangerouslySetInnerHTML={{ __html: `294  var theme = localStorage.getItem('theme') || 'light';295  document.getElementById('theme-wrapper').className = theme;296` }} />297```298 299#### rendering-hydration-suppress-warning - @rules/rendering-hydration-suppress-warning.md300 301Suppress expected hydration mismatches.302 303```tsx304<span suppressHydrationWarning>{new Date().toLocaleString()}</span>305```306 307#### rendering-client-only - @rules/rendering-client-only.md308 309Render browser-only components with ClientOnly and a fallback.310 311```tsx312<ClientOnly fallback={<Skeleton />}>313  {() => <Map />}314</ClientOnly>315```316 317#### rendering-use-hydrated - @rules/rendering-use-hydrated.md318 319Use `useHydrated` for SSR/CSR divergence.320 321```tsx322let hydrated = useHydrated();323return hydrated ? <Widget /> : <Skeleton />;324```325 326#### rendering-usetransition-loading - @rules/rendering-usetransition-loading.md327 328Prefer useTransition over manual loading states.329 330```tsx331const [isPending, startTransition] = useTransition();332 333let handleSearch = (value) => {334  startTransition(async () => {335    let data = await fetchResults(value);336    setResults(data);337  });338};339```340 341#### fault-tolerant-error-boundaries - @rules/fault-tolerant-error-boundaries.md342 343Place error boundaries at feature boundaries.344 345```tsx346<ErrorBoundary fallback={<SidebarError />}>347  <Sidebar />348</ErrorBoundary>349```350 351### Client Patterns (MEDIUM)352 353#### client-passive-event-listeners - @rules/client-passive-event-listeners.md354 355Use passive listeners for scroll/touch.356 357```tsx358document.addEventListener("wheel", handler, { passive: true });359document.addEventListener("touchstart", handler, { passive: true });360```361 362#### client-localstorage-schema - @rules/client-localstorage-schema.md363 364Version and minimize localStorage data.365 366```typescript367const VERSION = "v2";368 369function saveConfig(config: Config) {370  try {371    localStorage.setItem(`config:${VERSION}`, JSON.stringify(config));372  } catch {} // Handle incognito/quota exceeded373}374```375 376### Hooks (HIGH)377 378#### hooks-limit-useeffect - @rules/hooks-limit-useeffect.md379 380Use useEffect only when absolutely necessary. Prefer derived state or event handlers.381 382```tsx383// Bad: useEffect to derive state384let [filtered, setFiltered] = useState(items);385useEffect(() => {386  setFiltered(items.filter((i) => i.active));387}, [items]);388 389// Good: derive during render390let filtered = items.filter((i) => i.active);391 392// Good: useMemo if expensive393let filtered = useMemo(() => items.filter((i) => i.active), [items]);394```395 396#### hooks-useeffect-named-functions - @rules/hooks-useeffect-named-functions.md397 398Use named function declarations in useEffect for better debugging and self-documentation.399 400```tsx401// Bad: anonymous arrow function402useEffect(() => {403  document.title = title;404}, [title]);405 406// Good: named function407useEffect(408  function syncDocumentTitle() {409    document.title = title;410  },411  [title],412);413 414// Good: also name cleanup functions415useEffect(function subscribeToOnlineStatus() {416  window.addEventListener("online", handleOnline);417  return function unsubscribeFromOnlineStatus() {418    window.removeEventListener("online", handleOnline);419  };420}, []);421```422 423### Composition Patterns (HIGH)424 425#### composition-avoid-boolean-props - @rules/composition-avoid-boolean-props.md426 427Don't add boolean props to customize behavior. Use composition instead.428 429```tsx430// Bad: boolean prop explosion431<Composer isThread isEditing={false} showAttachments />432 433// Good: explicit variants434<ThreadComposer channelId="abc" />435<EditComposer messageId="xyz" />436```437 438#### composition-compound-components - @rules/composition-compound-components.md439 440Structure complex components as compound components with shared context.441 442```tsx443// Good: compound components444<Composer.Provider state={state} actions={actions}>445  <Composer.Frame>446    <Composer.Input />447    <Composer.Footer>448      <Composer.Submit />449    </Composer.Footer>450  </Composer.Frame>451</Composer.Provider>452```453 454#### composition-state-provider - @rules/composition-state-provider.md455 456Lift state into provider components for cross-component access.457 458```tsx459// Good: state in provider, accessible anywhere inside460<ForwardMessageProvider>461  <Dialog>462    <Composer.Input />463    <MessagePreview /> {/* Can read state */}464    <ForwardButton /> {/* Can call submit */}465  </Dialog>466</ForwardMessageProvider>467```468 469#### composition-explicit-variants - @rules/composition-explicit-variants.md470 471Create explicit variant components instead of prop combinations.472 473```tsx474// Good: self-documenting variants475function ThreadComposer({ channelId }) {476  return (477    <ThreadProvider channelId={channelId}>478      <Composer.Frame>479        <Composer.Input />480        <AlsoSendToChannelField />481        <Composer.Submit />482      </Composer.Frame>483    </ThreadProvider>484  );485}486```487 488#### composition-children-over-render-props - @rules/composition-children-over-render-props.md489 490Prefer children for composition. Use render props only when passing data back.491 492```tsx493// Good: children for structure494<Card>495  <Card.Header>Title</Card.Header>496  <Card.Body>Content</Card.Body>497</Card>498 499// OK: render props when passing data500<List renderItem={({ item }) => <Item {...item} />} />501```502 503#### composition-avoid-overabstraction - @rules/composition-avoid-overabstraction.md504 505Avoid rigid configuration props; prefer composable children APIs.506 507```tsx508<Select value="abc" onChange={...}>509  <Option value="abc">ABC</Option>510  <Option value="xyz">XYZ</Option>511</Select>512```513 514#### composition-typescript-namespaces - @rules/composition-typescript-namespaces.md515 516Use TypeScript namespaces to combine component and its types for single-import access.517 518```tsx519// components/button.tsx520export namespace Button {521  export type Variant = "solid" | "ghost" | "outline";522  export interface Props {523    variant?: Variant;524    children: React.ReactNode;525  }526}527 528export function Button({ variant = "solid", children }: Button.Props) {529  // ...530}531 532// Usage: single import533import { Button } from "~/components/button";534 535<Button variant="ghost">Click</Button>536function wrap(props: Button.Props) { ... }537```538 539**Important:** Namespaces should only contain types, never runtime code.