React Best Practices: Architecture, Performance, and Quality in 2025

React is deliberately unopinionated — it's a library, not a framework. That flexibility is real, and so is the cost: every team ends up building their own implicit framework through accumulated conventions. The difference between a React codebase that's a pleasure to work in and one that's a maze of workarounds comes down to a handful of decisions made (or not made) early on.

1. Component Design: Small, Focused, and Composable

The most valuable mental model in React is thinking in composition rather than inheritance or hierarchy. A component should do one thing and do it well. The signal that a component needs to be split: you need to scroll to understand what it renders.

// ✗ Monolithic component — renders, fetches, and manages all state in one place// ✗ Componente monolítico — renderiza, busca e gerencia todo o estado em um lugar
function UserDashboard() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(false);
  const [selected, setSelected] = useState(null);
  // 150 lines of JSX...// 150 linhas de JSX...
}

// ✓ Composed from focused pieces — each testable independently// ✓ Composto de partes focadas — cada uma testável independentemente
function UserDashboard() {
  return (
    <DashboardLayout>
      <UserListContainer />      {/* fetches + manages list state *//* busca + gerencia estado da lista */}
      <UserDetailPanel />        {/* reads selected user from store *//* lê usuário selecionado do store */}
    </DashboardLayout>
  );
}

The children prop and render props are underused composition tools. Passing UI as props rather than hardcoding it inside a component decouples layout from behavior and makes reuse trivial without adding abstraction layers.

// Compound pattern — state stays in the parent, rendering is delegated// Padrão compound — estado fica no pai, renderização é delegada
<DataTable data={orders}>
  <DataTable.Header />
  <DataTable.Body renderRow={order => <OrderRow key={order.id} order={order} />} />
  <DataTable.Pagination />
</DataTable>

2. Hooks: The Five Mistakes Everyone Makes

useEffect for everything

useEffect is the most misused hook. The React team's own guidance: most things you put in useEffect don't belong there. Data fetching belongs in a data-fetching library (React Query, SWR, RTK Query). Derived state belongs in a calculation during render, not a useEffect that syncs two state variables. Event responses belong in event handlers, not effects.

// ✗ useEffect to compute derived state// ✗ useEffect para calcular estado derivado
const [items, setItems] = useState([]);
const [total, setTotal] = useState(0);
useEffect(() => { setTotal(items.reduce((s, i) => s + i.price, 0)); }, [items]);

// ✓ Derive during render — no effect, no extra re-render// ✓ Derive durante a renderização — sem effect, sem re-renderização extra
const [items, setItems] = useState([]);
const total = items.reduce((s, i) => s + i.price, 0); // recalculated on render// recalculado na renderização

// ✗ useEffect to fetch on mount — no caching, no deduplication, no loading state management// ✗ useEffect para buscar no mount — sem cache, sem deduplicação, sem gerenciamento de loading
useEffect(() => { fetch('/api/users').then(r => r.json()).then(setUsers); }, []);

// ✓ React Query handles all of this — caching, background refetch, error boundaries// ✓ React Query lida com tudo isso — cache, refetch em background, error boundaries
const { data: users, isLoading } = useQuery({ queryKey: ['users'], queryFn: fetchUsers });

Stale closures in effects and callbacks

// ✗ Stale closure — count is captured at 0, never updates// ✗ Closure obsoleta — count é capturado em 0, nunca atualiza
useEffect(() => {
  const id = setInterval(() => console.log(count), 1000);
  return () => clearInterval(id);
}, []); // missing count dependency// dependência count ausente

// ✓ Add the dependency, or use a ref for values you want to read without re-subscribing// ✓ Adicione a dependência ou use uma ref para valores que quer ler sem re-assinar
const countRef = useRef(count);
useEffect(() => { countRef.current = count; });
useEffect(() => {
  const id = setInterval(() => console.log(countRef.current), 1000);
  return () => clearInterval(id);
}, []);

Missing cleanup in effects

// ✗ Sets state after component unmounts — React 18 warning, potential memory leak// ✗ Define estado após o componente ser desmontado — aviso no React 18, potencial memory leak
useEffect(() => {
  fetchUser(id).then(user => setUser(user));
}, [id]);

// ✓ AbortController cancels the fetch when component unmounts or id changes// ✓ AbortController cancela o fetch quando o componente é desmontado ou id muda
useEffect(() => {
  const controller = new AbortController();
  fetchUser(id, { signal: controller.signal }).then(user => setUser(user));
  return () => controller.abort();
}, [id]);

Overusing useState instead of useReducer

When you have three or more state variables that change together, or transitions that involve complex conditions, useReducer is cleaner than multiple useState calls. It centralizes logic, makes state transitions explicit, and is trivial to test (pure function — no hooks required).

Not extracting custom hooks

Any stateful logic that appears in more than one component belongs in a custom hook. Custom hooks are the primary reuse mechanism in React — they extract the why (the logic) from the what (the rendering). A component that is 60% hook calls and 40% JSX should have its hook calls extracted.

// Custom hook encapsulates the logic — component focuses on rendering// Custom hook encapsula a lógica — componente foca na renderização
function useUserSearch(initialQuery = '') {
  const [query, setQuery] = useState(initialQuery);
  const debouncedQuery = useDebounce(query, 300);
  const { data, isLoading } = useQuery({
    queryKey: ['users', 'search', debouncedQuery],
    queryFn: () => searchUsers(debouncedQuery),
    enabled: debouncedQuery.length > 1
  });
  return { query, setQuery, results: data ?? [], isLoading };
}

function UserSearchPage() {
  const { query, setQuery, results, isLoading } = useUserSearch();
  return (
    <>
      <SearchInput value={query} onChange={setQuery} />
      <UserList users={results} loading={isLoading} />
    </>
  );
}

3. State Management: The Decision Tree

1. Can the state live in a single component?

Use useState or useReducer. Don't pull it into global state prematurely — it creates invisible coupling and makes the component harder to reuse.Use useState ou useReducer. Não coloque prematuramente em estado global — isso cria acoplamento invisível e torna o componente mais difícil de reutilizar.

2. Is it server state (remote data)?

Use React Query or SWR. Server state has different concerns: caching, background sync, stale time, error retry. These libraries handle all of it. Putting API data in Redux or Zustand is almost always the wrong call.

3. Is it shared across a subtree of components?

Use Context for low-frequency updates (theme, locale, auth user). Context re-renders all consumers on every change — avoid it for high-frequency state like form input values or scroll position.Use Context para atualizações de baixa frequência (tema, locale, usuário autenticado). Context re-renderiza todos os consumidores em cada mudança — evite para estado de alta frequência como valores de inputs de formulário ou posição de scroll.

4. Is it truly global client state?

Use Zustand (simple, low boilerplate) or Redux Toolkit (powerful, auditable). Real global client state is rare: shopping cart, user preferences, notification queue. Most things teams put in Redux belong in React Query or local state.

Most state belongs in levels 1–2. Reaching for level 4 (Redux/Zustand) for server data is a very common mistake.

4. Performance: When memo Actually Helps (and When It Hurts)

React.memo, useMemo, and useCallback are optimization tools, not default patterns. They add cost (memory for the cached value, CPU for the comparison). They're only beneficial when the comparison is cheaper than the work being avoided — which is not always true.

// ✗ Memoizing a cheap computation — the memo overhead exceeds the benefit// ✗ Memoizando um cálculo barato — o overhead do memo supera o benefício
const label = useMemo(() => `${firstName} ${lastName}`, [firstName, lastName]);

// ✓ Just compute it — string concatenation is not worth memoizing// ✓ Apenas calcule — concatenação de string não vale memoizar
const label = `${firstName} ${lastName}`;

// ✓ useMemo for genuinely expensive computations// ✓ useMemo para cálculos genuinamente custosos
const sortedAndFiltered = useMemo(() =>
  items.filter(predicate).sort(comparator),
  [items, predicate, comparator]
);

// ✓ useCallback when a function is passed to a memoized child// ✓ useCallback quando uma função é passada para um filho memoizado
const handleSelect = useCallback((id: string) => {
  setSelected(id);
}, []); // only useful if UserRow is wrapped in React.memo// só útil se UserRow estiver envolvido em React.memo

The memo contract: React.memo on a child component only prevents re-renders if all its props are stable across parent renders. If the parent creates a new function or object inline, the prop is a new reference every render and memo does nothing. useCallback and useMemo are only useful when their result is passed to a React.memo-wrapped component or is itself used as a dependency.

5. Code Splitting and Lazy Loading

// Lazy load route-level components — initial bundle contains only the shell// Lazy load em componentes de nível de rota — bundle inicial contém apenas o shell
const UserPage = lazy(() => import('./features/users/UserPage'));
const OrdersPage = lazy(() => import('./features/orders/OrdersPage'));

function App() {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <Routes>
        <Route path="/users" element={<UserPage />} />
        <Route path="/orders" element={<OrdersPage />} />
      </Routes>
    </Suspense>
  );
}

// Lazy load heavy non-route components too — charts, rich text editors, modals// Lazy load em componentes pesados não rota também — gráficos, editores, modais
const Chart = lazy(() => import('./components/Chart'));
{showChart && <Suspense fallback={<ChartSkeleton />}><Chart /></Suspense>}

Route-level splitting should be non-negotiable. A React SPA that doesn't code-split loads the JavaScript for every feature on every page load — users pay the cost of features they never visit. Bundle analysis with vite-bundle-analyzer or webpack-bundle-analyzer makes the cost visible.

6. Project Structure That Scales

src/
├── features/               # one folder per domain feature# uma pasta por feature de domínio
│   ├── users/
│   │   ├── components/     # presentational, feature-scoped# apresentacional, escopo de feature
│   │   ├── hooks/          # custom hooks for this feature# custom hooks para esta feature
│   │   ├── api/            # React Query hooks (useUsers, useCreateUser)# hooks React Query (useUsers, useCreateUser)
│   │   ├── store/          # Zustand slice or Redux slice if needed# slice Zustand ou Redux se necessário
│   │   ├── types.ts        # domain types scoped to this feature# tipos de domínio com escopo desta feature
│   │   └── index.ts        # public API — only export what other features need# API pública — exporte apenas o que outras features precisam
│   └── orders/
├── shared/                 # truly shared UI — Button, Modal, Input, Table# UI verdadeiramente compartilhada — Button, Modal, Input, Table
│   └── components/
├── lib/                    # framework setup — queryClient, store, router# setup de framework — queryClient, store, router
└── app/                    # routes, App component, providers# rotas, componente App, providers

The index.ts barrel file at each feature boundary acts as an explicit public API. Other features import from features/users, not from features/users/components/UserCard/UserCard.tsx. This encapsulation makes refactoring within a feature safe and makes cross-feature dependencies explicit and reviewable.

7. Forms: Controlled vs. Uncontrolled

Controlled inputs (value={state}) are the React default and give you fine-grained control. But they re-render on every keystroke. For large forms (20+ fields), this is measurable. Uncontrolled inputs with useRef or a form library like React Hook Form (which uses uncontrolled inputs internally) are significantly faster for complex forms.

// React Hook Form — uncontrolled under the hood, minimal re-renders// React Hook Form — não controlado por baixo, re-renderizações mínimas
const { register, handleSubmit, formState: { errors } } = useForm<UserForm>({
  resolver: zodResolver(userSchema)  // Zod schema for validation// schema Zod para validação
});

return (
  <form onSubmit={handleSubmit(onSubmit)}>
    <input {...register('email')} />
    {errors.email && <span>{errors.email.message}</span>}
  </form>
);

8. Error Boundaries: Failing Gracefully

A runtime error in any component without an Error Boundary crashes the entire React tree. Error Boundaries are class components (or use the react-error-boundary library) that catch render errors and display fallback UI instead of a blank page.

// Wrap every major section — not just the root// Envolva cada seção principal — não apenas a raiz
import { ErrorBoundary } from 'react-error-boundary';

function App() {
  return (
    <ErrorBoundary fallback={<AppCrash />}>
      <Header />
      <ErrorBoundary fallback={<SectionError section="dashboard" />}>
        <Dashboard />
      </ErrorBoundary>
      <ErrorBoundary fallback={<SectionError section="sidebar" />}>
        <Sidebar />
      </ErrorBoundary>
    </ErrorBoundary>
  );
}

9. Testing with React Testing Library

React Testing Library's guiding principle: test behavior, not implementation. Query by what the user sees (text, role, label), not by class names or component internals. Tests that break when you refactor without changing behavior are not tests — they're maintenance liabilities.

// ✗ Tests implementation details — breaks on any refactor// ✗ Testa detalhes de implementação — quebra em qualquer refatoração
expect(wrapper.find('.user-card__title').text()).toBe('Alice');

// ✓ Tests what the user sees — survives any refactor that keeps the behavior// ✓ Testa o que o usuário vê — sobrevive a qualquer refatoração que mantém o comportamento
render(<UserCard user={alice} />);
expect(screen.getByRole('heading', { name: 'Alice' })).toBeInTheDocument();

// ✓ Testing an interaction// ✓ Testando uma interação
await userEvent.click(screen.getByRole('button', { name: /delete/i }));
expect(screen.queryByText('Alice')).not.toBeInTheDocument();

Query priority in RTL: getByRole > getByLabelText > getByPlaceholderText > getByText. Roles map to what screen readers announce — tests that use them double as accessibility checks.

10. React 18 Concurrent Features

React 18's concurrent mode doesn't change how you write components — it changes how React decides when to render them. Two hooks expose this power directly to application code: useTransition and useDeferredValue. Both solve the same problem: keeping the UI responsive during expensive updates.

// useTransition — mark a state update as non-urgent
// UI stays responsive; the update is deferred until React has idle time// useTransition — marca uma atualização de estado como não urgente
// UI permanece responsiva; a atualização é adiada até o React ter tempo livre
const [isPending, startTransition] = useTransition();

function handleSearch(value: string) {
  setInputValue(value);                          // urgent: update input immediately// urgente: atualiza o input imediatamente
  startTransition(() => setSearchQuery(value));  // non-urgent: filter 10,000 items// não urgente: filtra 10.000 itens
}

return (
  <>
    <input value={inputValue} onChange={e => handleSearch(e.target.value)} />
    {isPending && <Spinner />}
    <ItemList query={searchQuery} />  {/* renders with deferred value *//* renderiza com valor adiado */}
  </>
);

// useDeferredValue — defer the expensive part without owning the state update// useDeferredValue — adia a parte custosa sem possuir a atualização de estado
function SearchResults({ query }: { query: string }) {
  const deferredQuery = useDeferredValue(query);
  const isStale = query !== deferredQuery;

  return (
    <div style={{ opacity: isStale ? 0.6 : 1 }}>  {/* visual stale indicator *//* indicador visual de stale */}
      <ExpensiveList query={deferredQuery} />
    </div>
  );
}

useTransition vs useDeferredValue: Use useTransition when you own the state update (you control when setState fires). Use useDeferredValue when you receive a value as a prop or from an external source you don't control. Both defer the expensive downstream render; they differ in where the deferral is applied.

11. TypeScript Patterns That Make Components Safer

React and TypeScript have strong synergy, but most teams only use TypeScript for basic prop typing. A few patterns go much further in making invalid states unrepresentable at compile time.

// Discriminated unions for component variants — impossible to pass wrong combination// Unions discriminadas para variantes de componente — impossível passar combinação errada
type ButtonProps =
  | { variant: 'primary'; onClick: () => void; href?: never }
  | { variant: 'link'; href: string; onClick?: never };

// ✗ Type error — link variant requires href, not onClick// ✗ Erro de tipo — variante link requer href, não onClick
<Button variant="link" onClick={handleClick} />

// Polymorphic component — preserves the correct HTML element's prop types// Componente polimórfico — preserva os tipos de props do elemento HTML correto
type AsProps<T extends ElementType> = { as?: T } & ComponentPropsWithoutRef<T>;

function Text<T extends ElementType = 'p'>({ as, ...props }: AsProps<T>) {
  const Tag = as ?? 'p';
  return <Tag {...props} />;
}
<Text as="h1" id="title">Heading</Text>  // id is valid; href would be a type error// id é válido; href seria erro de tipo

// Generic data components — no any, full type inference through// Componentes de dados genéricos — sem any, inferência de tipo completa
function DataTable<T>({ data, columns }: {
  data: T[];
  columns: { key: keyof T; label: string }[];
}) { ... }

<DataTable
  data={users}                             // T inferred as User// T inferido como User
  columns={[{ key: 'email', label: 'Email' }]}  // key must be keyof User// key deve ser keyof User
/>

12. Server Components and the Next.js App Router

React Server Components (RSC) — the foundation of Next.js 13+ App Router — fundamentally change the rendering model. Server Components run only on the server: they can access databases and secrets directly, never ship JavaScript to the client, and are ideal for data fetching. Client Components (marked 'use client') run in the browser and handle interactivity.

// Server Component — runs on server, zero JS sent to client, direct DB access// Server Component — roda no servidor, zero JS enviado ao cliente, acesso direto ao DB
// app/users/page.tsx (no 'use client' directive = Server Component by default)// app/users/page.tsx (sem diretiva 'use client' = Server Component por padrão)
export default async function UsersPage() {
  const users = await db.users.findMany();    // direct DB call, no API needed// chamada direta ao DB, sem API necessária
  return <UserList users={users} />;
}

// Client Component — needed for: useState, useEffect, event handlers, browser APIs// Client Component — necessário para: useState, useEffect, event handlers, browser APIs
'use client';
export function UserList({ users }: { users: User[] }) {
  const [selected, setSelected] = useState<string | null>(null);
  return (
    <ul>
      {users.map(user => (
        <li key={user.id} onClick={() => setSelected(user.id)}>{user.name}</li>
      ))}
    </ul>
  );
}

The decision rule: Default to Server Components. Add 'use client' only when you need: useState, useEffect, event listeners, browser-only APIs (window, localStorage), or third-party libraries that aren't RSC-compatible. Push 'use client' as far down the component tree as possible — a leaf interactive button doesn't require its entire parent tree to be a Client Component.

13. Common Mistakes That Compound Over Time

Prop drilling beyond two levels. Passing props through three or more component layers creates invisible coupling. Extract to Context or move the consuming component closer to the state.
Huge component files with multiple exported components. One component per file (with its types and helpers in the same file) is the standard that makes navigation predictable. A 400-line file with five components is a refactoring trigger.
Inconsistent async error handling. Components that don't show errors look like they're working. Always handle the error state in data-fetching components — an empty error state is worse than a visible one because it silently tells the user nothing went wrong when something did.
Re-creating context values inline. <ThemeContext.Provider value={{ theme, toggleTheme }}> creates a new object on every render, causing all consumers to re-render. Memoize the context value.

Key Takeaways

Composition over abstraction. Split components by concern, not by line count. A component that renders three visual sections should be three components, not one with if-blocks.
Stop putting useEffect where it doesn't belong. Derived state is a calculation. Event responses are handlers. Data fetching is React Query. If you're reaching for useEffect, ask whether one of these fits first.
Server state and client state are different problems. React Query for remote data, Context or Zustand for genuine client state. Most apps have far less client state than they think.
memo is a last resort, not a default. Profile first, then memoize where the profiler shows a genuine cost. Premature memoization adds complexity without measurable benefit.
Feature-based structure with explicit public APIs (index.ts) keeps cross-feature dependencies visible and refactoring safe. Layer-based structure (components/, hooks/, services/ at the root) doesn't scale past 10 features.
Test behavior, not implementation. RTL queries by role and text survive refactoring. Snapshot tests and class-name queries do not.

1. Component Design: Small, Focused, and Composable1. Design de Componentes: Pequenos, Focados e Combináveis

2. Hooks: The Five Mistakes Everyone Makes2. Hooks: Os Cinco Erros que Todo Mundo Comete

useEffect for everythinguseEffect para tudo

Stale closures in effects and callbacksClosures obsoletas em effects e callbacks

Missing cleanup in effectsCleanup ausente em effects

Overusing useState instead of useReducerUsar useState em excesso em vez de useReducer

Not extracting custom hooksNão extrair custom hooks

3. State Management: The Decision Tree3. Gerenciamento de Estado: A Árvore de Decisão

4. Performance: When memo Actually Helps (and When It Hurts)4. Performance: Quando memo Realmente Ajuda (e Quando Prejudica)

5. Code Splitting and Lazy Loading5. Code Splitting e Lazy Loading

6. Project Structure That Scales6. Estrutura de Projeto que Escala

7. Forms: Controlled vs. Uncontrolled7. Formulários: Controlado vs. Não Controlado

8. Error Boundaries: Failing Gracefully8. Error Boundaries: Falhando Graciosamente

9. Testing with React Testing Library9. Testes com React Testing Library

10. React 18 Concurrent Features10. Recursos Concorrentes do React 18

11. TypeScript Patterns That Make Components Safer11. Padrões TypeScript que Tornam Componentes Mais Seguros

12. Server Components and the Next.js App Router12. Server Components e o App Router do Next.js

13. Common Mistakes That Compound Over Time13. Erros Comuns que se Agravam com o Tempo

Key TakeawaysPontos Principais

1. Component Design: Small, Focused, and Composable

2. Hooks: The Five Mistakes Everyone Makes

useEffect for everything

Stale closures in effects and callbacks

Missing cleanup in effects

Overusing useState instead of useReducer

Not extracting custom hooks

3. State Management: The Decision Tree

4. Performance: When memo Actually Helps (and When It Hurts)

5. Code Splitting and Lazy Loading

6. Project Structure That Scales

7. Forms: Controlled vs. Uncontrolled

8. Error Boundaries: Failing Gracefully

9. Testing with React Testing Library

10. React 18 Concurrent Features

11. TypeScript Patterns That Make Components Safer

12. Server Components and the Next.js App Router

13. Common Mistakes That Compound Over Time

Key Takeaways