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
  }
}