react-conventions

React Conventions

This skill consolidates idioms that hold across React SPA projects. Apply alongside js-foundation:typescript-patterns (general TS strictness).

Project layout

Two common structures:

Feature-based (preferred for medium+ apps)

src/
├── main.tsx                       # entry — ReactDOM.createRoot
├── App.tsx                         # root component
├── routes.tsx                      # route definitions (or routes/ folder)
├── features/
│   ├── users/
│   │   ├── UserList.tsx
│   │   ├── UserDetail.tsx
│   │   ├── UserForm.tsx
│   │   ├── api/
│   │   │   └── users.ts            # fetcher / TanStack Query hooks
│   │   ├── hooks/
│   │   │   └── useUsers.ts
│   │   └── types.ts
│   └── orders/
│       └── ...
├── components/
│   ├── ui/                         # primitives (Button, Input, Modal)
│   └── shared/                     # cross-feature shared components
├── lib/                            # framework-agnostic utilities
│   ├── http.ts
│   └── format.ts
├── hooks/                          # cross-feature hooks (useDebounce, useMediaQuery)
├── styles/                         # global CSS, design tokens
└── types/                          # global types

Type-based (acceptable for small apps)

src/
├── components/
├── hooks/
├── pages/                          # route components
├── lib/
└── styles/

Mirror what exists. Don't refactor structure as part of feature work.

File naming

What	Convention
Component file	PascalCase.tsx (UserCard.tsx)
Hook file	useCamelCase.ts (useDebounce.ts)
Utility module	kebab-case.ts or camelCase.ts (match project)
Test file	*.test.tsx colocated, OR mirror in tests/
Story file	*.stories.tsx colocated (Storybook)
Type file	types.ts per feature, OR *.types.ts

Hooks rules

// ✅ Top-level only
function MyComponent() {
  const [count, setCount] = useState(0);
  const ref = useRef(null);
  useEffect(() => { /* ... */ }, []);
  return <div />;
}

// ❌ Conditional hook
function Bad() {
  if (someCondition) {
    const [x, setX] = useState(0); // breaks Rules of Hooks
  }
}

// ❌ Hook in loop
function AlsoBad() {
  for (let i = 0; i < 5; i++) {
    useState(0); // breaks
  }
}

Custom hooks always start with use*:

// src/hooks/useDebounce.ts
import { useEffect, useState } from 'react';

export function useDebounce<T>(value: T, delay = 300): T {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(id);
  }, [value, delay]);
  return debounced;
}

The use* prefix is what enables the linter and React itself to recognize it as a hook.

Dependency arrays

Trust the eslint-plugin-react-hooks exhaustive-deps rule. If it flags, fix the dep array — don't disable the rule.

If a function is recreated each render but its identity matters (used in effect dep array, or as prop to memoized child):

// Stabilize the function reference
const handleClick = useCallback((id: string) => {
  doSomething(id);
}, []); // deps: anything closed over from outer scope

Same for objects:

const config = useMemo(() => ({ retries: 3, timeout: 5000 }), []);

But: don't pre-emptively wrap everything in useCallback/useMemo. Only when the deps array failure or memoization break is real.

Component patterns

Plain functional component

type Props = {
  title: string;
  onClose: () => void;
  children: React.ReactNode;
};

export function Modal({ title, onClose, children }: Props) {
  return (
    <div role="dialog" aria-labelledby="modal-title">
      <h2 id="modal-title">{title}</h2>
      {children}
      <button onClick={onClose}>Close</button>
    </div>
  );
}

Compound components (shared context)

// Tabs.tsx
import { createContext, useContext, useState } from 'react';

type TabsContext = { active: string; setActive: (s: string) => void };
const Ctx = createContext<TabsContext | null>(null);

export function Tabs({ defaultTab, children }: { defaultTab: string; children: React.ReactNode }) {
  const [active, setActive] = useState(defaultTab);
  return <Ctx.Provider value={{ active, setActive }}>{children}</Ctx.Provider>;
}

export function Tab({ name, children }: { name: string; children: React.ReactNode }) {
  const ctx = useContext(Ctx);
  if (!ctx) throw new Error('Tab must be inside Tabs');
  return (
    <button onClick={() => ctx.setActive(name)} aria-selected={ctx.active === name}>
      {children}
    </button>
  );
}

export function TabPanel({ name, children }: { name: string; children: React.ReactNode }) {
  const ctx = useContext(Ctx);
  if (!ctx) throw new Error('TabPanel must be inside Tabs');
  return ctx.active === name ? <div role="tabpanel">{children}</div> : null;
}

Usage:

<Tabs defaultTab="overview">
  <Tab name="overview">Overview</Tab>
  <Tab name="settings">Settings</Tab>
  <TabPanel name="overview"><OverviewContent /></TabPanel>
  <TabPanel name="settings"><SettingsContent /></TabPanel>
</Tabs>

Render props (when children + context don't fit)

type Props<T> = {
  data: T[];
  render: (item: T, index: number) => React.ReactNode;
};

export function List<T>({ data, render }: Props<T>) {
  return <ul>{data.map((item, i) => <li key={i}>{render(item, i)}</li>)}</ul>;
}

forwardRef (React ≤18) / ref-as-prop (React 19+)

// React 19+ — ref is a regular prop
type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & { ref?: React.Ref<HTMLButtonElement> };
export function Button({ ref, ...rest }: ButtonProps) {
  return <button ref={ref} {...rest} />;
}

// React ≤18 — forwardRef
import { forwardRef } from 'react';
export const Button = forwardRef<HTMLButtonElement, React.ButtonHTMLAttributes<HTMLButtonElement>>(
  function Button(props, ref) {
    return <button ref={ref} {...props} />;
  }
);

Match the React major version's idiom.

Effects: when (and when not)

useEffect is for synchronizing with external systems. NOT for:

// ❌ Don't use effect to derive state
function Bad({ users }: { users: User[] }) {
  const [count, setCount] = useState(0);
  useEffect(() => setCount(users.length), [users]);
  return <div>{count}</div>;
}

// ✅ Compute during render
function Good({ users }: { users: User[] }) {
  return <div>{users.length}</div>;
}

// ❌ Don't use effect for event-driven logic
function Bad() {
  const [clicked, setClicked] = useState(false);
  useEffect(() => {
    if (clicked) reportAnalytics();
  }, [clicked]);
  return <button onClick={() => setClicked(true)}>Click</button>;
}

// ✅ Handle the event directly
function Good() {
  return <button onClick={() => reportAnalytics()}>Click</button>;
}

Effect IS correct for:

• Subscribing to external sources (WebSocket, EventEmitter, BroadcastChannel).
• DOM measurement / focus / scroll restoration.
• Browser API observers (IntersectionObserver, ResizeObserver, MutationObserver) — with cleanup.
• Manual data fetching when not using TanStack Query / SWR (most projects use those).

Always return a cleanup function for subscriptions:

useEffect(() => {
  const handler = () => doSomething();
  window.addEventListener('resize', handler);
  return () => window.removeEventListener('resize', handler);
}, []);

Performance escape hatches (use sparingly)

React.memo

export const ExpensiveChild = React.memo(function ExpensiveChild({ data }: Props) {
  // ...
});

Wraps a component in shallow-prop comparison. Don't apply by reflex — measure first. Many components don't need it; some have unstable props that defeat memoization anyway.

useMemo / useCallback

const sorted = useMemo(() => expensiveSort(items), [items]);
const onClick = useCallback((id: string) => { /* ... */ }, [dep]);

Only when:

• The computation is genuinely expensive (profile first).
• Reference stability matters for downstream memo or effect deps.

List virtualization

For lists > 100 items, use react-window or @tanstack/react-virtual. Renders only visible rows.

Code splitting

import { lazy, Suspense } from 'react';

const HeavyChart = lazy(() => import('./HeavyChart'));

export function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      <Suspense fallback={<div>Loading chart...</div>}>
        <HeavyChart />
      </Suspense>
    </div>
  );
}

Routes are the natural split boundary.

Accessibility (table stakes)

• Use semantic HTML: <button> for clickable, <a> for navigation. Don't rebuild buttons from <div onClick>.
• Form inputs paired with <label> (visible or via aria-label).
• Modal / dialog: role="dialog", focus trap, ESC to close, focus return on close.
• Image: alt attribute (empty if decorative).
• Lists: real <ul>/<ol>/<li> for screen reader semantics.

Anti-patterns

• ❌ useEffect(() => { setState(...) }, [otherState]) to derive state — compute in render.
• ❌ Index as key for reorderable lists.
• ❌ dangerouslySetInnerHTML without sanitization.
• ❌ <div onClick={...}> for clickable — use <button>.
• ❌ Stuffing logic into useEffect instead of event handlers.
• ❌ useCallback / useMemo everywhere "for performance" without profiling.
• ❌ Storing derived data in state that could be computed.
• ❌ Disabling react-hooks/exhaustive-deps ESLint rule per-line — fix the deps.
• ❌ Mounting/unmounting an effect just to invoke it once (use useEffect(() => fn(), []) deliberately).
• ❌ Reading process.env.X for secrets in components — env vars are public in client bundles.