Claude Code + React: Guia Completo para Devs Frontend

Se voce trabalha com React, ja sabe: criar componentes, escrever testes, refatorar codigo legado e otimizar performance consomem horas do seu dia. O Claude Code transforma essas tarefas. Ele le seu projeto inteiro, entende seus padroes e gera codigo que se encaixa perfeitamente na sua codebase.

Nao estamos falando de snippets genericos copiados de documentacao. O Claude Code analisa a estrutura do seu projeto -- se usa TypeScript, styled-components, Zustand, React Query -- e gera codigo que segue exatamente o mesmo padrao. Ele entende contexto.

Neste guia, voce vai ver exemplos reais de como usar Claude Code para cada etapa do desenvolvimento React: criar componentes, extrair hooks, escrever testes, migrar class components e otimizar renders. Tudo com comandos que voce pode executar hoje.

1. Por que usar Claude Code com React

React e um framework que exige muito codigo boilerplate. Um componente simples com TypeScript, props tipadas, testes e estilos pode facilmente ter 4 arquivos e 200+ linhas. Multiplique por dezenas de componentes e voce tem centenas de horas de trabalho repetitivo.

O Claude Code resolve isso porque ele opera diretamente no seu codebase. Diferente de chatbots que geram codigo isolado, o Claude Code:

• Le toda a estrutura do projeto -- entende onde ficam componentes, hooks, utils, tipos
• Identifica padroes existentes -- se seus componentes usam forwardRef, ele gera com forwardRef
• Cria arquivos no lugar certo -- nao joga codigo no terminal, cria os arquivos diretamente
• Executa comandos -- roda testes, verifica tipos com tsc, executa lint
• Itera sobre feedback -- se o teste falhou, ele le o erro e corrige

2. Configurando o ambiente

Para usar Claude Code com React, voce precisa do Claude Code instalado e um projeto React. O setup e simples:

Ao iniciar, o Claude Code identifica automaticamente que e um projeto React e ajusta seu comportamento. Ele reconhece:

• Se o projeto usa JavaScript ou TypeScript
• Qual versao do React (para saber se pode usar hooks, server components, etc.)
• Bibliotecas de estado (Redux, Zustand, Jotai, Context API)
• Bibliotecas de estilo (CSS Modules, styled-components, Tailwind, Emotion)
• Configuracao de testes (Jest, Vitest, Testing Library)
• Configuracao de lint (ESLint, Prettier)

CLAUDE.md para projetos React

Para resultados ainda melhores, crie um arquivo CLAUDE.md na raiz do projeto com as convencoes da equipe:

# CLAUDE.md

## Padroes de componentes
- Usar functional components com TypeScript
- Props tipadas com interface (nao type)
- Exportar componente como default
- Um componente por arquivo
- Colocar em src/components/[NomeComponente]/

## Estrutura de cada componente
- index.tsx (componente principal)
- types.ts (interfaces de props)
- styles.module.css (estilos)
- [NomeComponente].test.tsx (testes)

## Testes
- Usar React Testing Library
- Testar comportamento, nao implementacao
- Minimo: render sem crash + interacoes principais

## Estado
- Estado local: useState/useReducer
- Estado global: Zustand
- Estado do servidor: React Query

Com esse arquivo, o Claude Code segue suas convencoes em 100% dos casos. Sem ele, ele infere os padroes analisando o codigo existente -- o que funciona bem, mas o CLAUDE.md elimina ambiguidades.

3. Criando componentes com Claude Code

Criar componentes e onde o Claude Code mais brilha. Voce descreve o que precisa, e ele gera o componente completo com tipos, estilos e testes.

Exemplo: componente de card de produto

O Claude Code analisa o projeto e gera:

// src/components/ProductCard/types.ts
export interface ProductCardProps {
  name: string;
  price: number;
  image: string;
  description: string;
  onAddToCart: (productName: string) => void;
}

// src/components/ProductCard/index.tsx
import { memo } from 'react';
import type { ProductCardProps } from './types';
import styles from './styles.module.css';

function ProductCard({ name, price, image, description, onAddToCart }: ProductCardProps) {
  return (
    <article className={styles.card}>
      <img
        src={image}
        alt={name}
        className={styles.image}
        loading="lazy"
      />
      <div className={styles.content}>
        <h3 className={styles.name}>{name}</h3>
        <p className={styles.description}>{description}</p>
        <div className={styles.footer}>
          <span className={styles.price}>
            {new Intl.NumberFormat('pt-BR', {
              style: 'currency',
              currency: 'BRL'
            }).format(price)}
          </span>
          <button
            className={styles.button}
            onClick={() => onAddToCart(name)}
            type="button"
          >
            Adicionar ao carrinho
          </button>
        </div>
      </div>
    </article>
  );
}

export default memo(ProductCard);

Note que ele usou memo automaticamente (porque e um componente que recebe props e pode se beneficiar de memoizacao), loading="lazy" na imagem, formatacao de moeda brasileira com Intl.NumberFormat e semantica HTML correta com <article>.

Componentes complexos

O Claude Code tambem gera componentes mais complexos. Formularios com validacao, tabelas com ordenacao e paginacao, modais com portal, wizards multi-step -- tudo seguindo os padroes do seu projeto:

Ele gera o componente com generics (DataTable<T>), hooks internos para estado de ordenacao e paginacao, e tipagem completa. Se o projeto usa React Query, ele pode integrar com paginacao server-side automaticamente.

4. Hooks customizados na pratica

Hooks customizados sao onde React realmente brilha para reutilizacao de logica. O Claude Code identifica oportunidades de extracao de hooks e cria hooks robustos.

Exemplo: useDebounce

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

export function useDebounce<T>(value: T, delay: number = 300): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value);

  useEffect(() => {
    const timer = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    return () => clearTimeout(timer);
  }, [value, delay]);

  return debouncedValue;
}

Exemplo: useLocalStorage

// src/hooks/useLocalStorage.ts
import { useState, useCallback } from 'react';

export function useLocalStorage<T>(
  key: string,
  initialValue: T
): [T, (value: T | ((prev: T) => T)) => void, () => void] {
  const [storedValue, setStoredValue] = useState<T>(() => {
    try {
      const item = window.localStorage.getItem(key);
      return item ? (JSON.parse(item) as T) : initialValue;
    } catch {
      return initialValue;
    }
  });

  const setValue = useCallback(
    (value: T | ((prev: T) => T)) => {
      setStoredValue((prev) => {
        const valueToStore = value instanceof Function ? value(prev) : value;
        window.localStorage.setItem(key, JSON.stringify(valueToStore));
        return valueToStore;
      });
    },
    [key]
  );

  const removeValue = useCallback(() => {
    window.localStorage.removeItem(key);
    setStoredValue(initialValue);
  }, [key, initialValue]);

  return [storedValue, setValue, removeValue];
}

Extraindo hooks de componentes existentes

Um dos usos mais poderosos e pedir ao Claude Code para analisar componentes existentes e extrair logica reutilizavel:

O Claude Code faz uma analise completa: identifica padroes como fetch + loading + error repetidos em multiplos componentes, logica de formulario duplicada, manipulacao de estado similar. Ele cria os hooks e atualiza todos os componentes que usavam a logica duplicada.

5. Testes com Jest e Testing Library

Escrever testes e a tarefa que mais devs pulam -- e a que mais se beneficia do Claude Code. Ele gera testes que seguem as melhores praticas do React Testing Library: testam comportamento do usuario, nao detalhes de implementacao.

Gerando testes para um componente existente

// src/components/ProductCard/ProductCard.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import ProductCard from './';

const defaultProps = {
  name: 'Camiseta React',
  price: 79.9,
  image: '/images/camiseta.webp',
  description: 'Camiseta oficial do React',
  onAddToCart: jest.fn(),
};

describe('ProductCard', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('renderiza nome, descricao e preco formatado', () => {
    render(<ProductCard {...defaultProps} />);

    expect(screen.getByRole('heading', { name: 'Camiseta React' })).toBeInTheDocument();
    expect(screen.getByText('Camiseta oficial do React')).toBeInTheDocument();
    expect(screen.getByText('R$\u00a079,90')).toBeInTheDocument();
  });

  it('renderiza imagem com alt text e lazy loading', () => {
    render(<ProductCard {...defaultProps} />);

    const img = screen.getByRole('img', { name: 'Camiseta React' });
    expect(img).toHaveAttribute('src', '/images/camiseta.webp');
    expect(img).toHaveAttribute('loading', 'lazy');
  });

  it('chama onAddToCart com o nome do produto ao clicar', async () => {
    const user = userEvent.setup();
    render(<ProductCard {...defaultProps} />);

    await user.click(screen.getByRole('button', { name: /adicionar ao carrinho/i }));

    expect(defaultProps.onAddToCart).toHaveBeenCalledTimes(1);
    expect(defaultProps.onAddToCart).toHaveBeenCalledWith('Camiseta React');
  });

  it('formata precos com centavos corretamente', () => {
    render(<ProductCard {...defaultProps} price={1299.99} />);
    expect(screen.getByText('R$\u00a01.299,99')).toBeInTheDocument();
  });
});

Note como os testes usam getByRole e getByText em vez de getByTestId -- seguindo a filosofia do Testing Library de testar como o usuario ve a interface. O Claude Code sabe disso porque entende as melhores praticas da biblioteca.

Testes para hooks customizados

// src/hooks/useDebounce.test.ts
import { renderHook, act } from '@testing-library/react';
import { useDebounce } from './useDebounce';

describe('useDebounce', () => {
  beforeEach(() => {
    jest.useFakeTimers();
  });

  afterEach(() => {
    jest.useRealTimers();
  });

  it('retorna o valor inicial imediatamente', () => {
    const { result } = renderHook(() => useDebounce('hello', 500));
    expect(result.current).toBe('hello');
  });

  it('atualiza o valor apos o delay', () => {
    const { result, rerender } = renderHook(
      ({ value, delay }) => useDebounce(value, delay),
      { initialProps: { value: 'hello', delay: 500 } }
    );

    rerender({ value: 'world', delay: 500 });
    expect(result.current).toBe('hello');

    act(() => { jest.advanceTimersByTime(500); });
    expect(result.current).toBe('world');
  });

  it('cancela o timer anterior quando o valor muda', () => {
    const { result, rerender } = renderHook(
      ({ value }) => useDebounce(value, 500),
      { initialProps: { value: 'a' } }
    );

    rerender({ value: 'ab' });
    act(() => { jest.advanceTimersByTime(300); });

    rerender({ value: 'abc' });
    act(() => { jest.advanceTimersByTime(300); });

    expect(result.current).toBe('a');

    act(() => { jest.advanceTimersByTime(200); });
    expect(result.current).toBe('abc');
  });
});

Cobertura em massa

Para projetos com baixa cobertura de testes, voce pode pedir ao Claude Code para gerar testes para todos os componentes de uma vez:

6. Refatorando class para functional

Se voce tem componentes legados usando class components, o Claude Code faz a migracao de forma segura -- preservando a logica de negocio e convertendo lifecycle methods para hooks.

Exemplo: class component original

// Antes: class component
class UserProfile extends React.Component {
  constructor(props) {
    super(props);
    this.state = { user: null, loading: true, error: null };
  }

  componentDidMount() {
    this.fetchUser();
  }

  componentDidUpdate(prevProps) {
    if (prevProps.userId !== this.props.userId) {
      this.fetchUser();
    }
  }

  componentWillUnmount() {
    this.abortController?.abort();
  }

  async fetchUser() {
    this.abortController = new AbortController();
    this.setState({ loading: true, error: null });
    try {
      const res = await fetch(`/api/users/${this.props.userId}`, {
        signal: this.abortController.signal
      });
      const user = await res.json();
      this.setState({ user, loading: false });
    } catch (err) {
      if (err.name !== 'AbortError') {
        this.setState({ error: err.message, loading: false });
      }
    }
  }

  render() {
    const { user, loading, error } = this.state;
    if (loading) return <Spinner />;
    if (error) return <ErrorMessage message={error} />;
    return <div>{user.name}</div>;
  }
}

Resultado: functional component

// Depois: functional component com hooks
import { useState, useEffect } from 'react';

interface UserProfileProps {
  userId: string;
}

interface User {
  name: string;
  email: string;
}

function UserProfile({ userId }: UserProfileProps) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const abortController = new AbortController();

    async function fetchUser() {
      setLoading(true);
      setError(null);
      try {
        const res = await fetch(`/api/users/${userId}`, {
          signal: abortController.signal,
        });
        const data: User = await res.json();
        setUser(data);
        setLoading(false);
      } catch (err) {
        if (err instanceof Error && err.name !== 'AbortError') {
          setError(err.message);
          setLoading(false);
        }
      }
    }

    fetchUser();

    return () => abortController.abort();
  }, [userId]);

  if (loading) return <Spinner />;
  if (error) return <ErrorMessage message={error} />;

  return <div>{user?.name}</div>;
}

export default UserProfile;

O Claude Code converteu componentDidMount e componentDidUpdate em um unico useEffect com userId na dependency array, manteve o AbortController com cleanup no return do useEffect, e adicionou tipagem TypeScript. O comportamento e identico, o codigo e mais limpo.

Migracao em massa

O Claude Code faz o inventario, classifica por complexidade e voce pode migrar um por um com seguranca, validando os testes a cada etapa.

7. Otimizacao de performance

Performance em React se resume a evitar renders desnecessarios e reduzir o tamanho do bundle. O Claude Code analisa seu projeto e identifica problemas de performance automaticamente.

Audit de re-renders

O Claude Code identifica padroes como:

• Objetos/arrays criados inline em props -- causam re-render porque a referencia muda a cada render
• Funcoes definidas inline em JSX -- mesmo problema, referencia nova a cada render
• Componentes sem memo que recebem props estaveis -- re-renderizam desnecessariamente quando o pai renderiza
• Computacoes pesadas sem useMemo -- recalculam a cada render mesmo quando os inputs nao mudaram

Exemplo: antes e depois

// ANTES: problemas de performance
function ProductList({ products, onSelect }) {
  // filteredProducts recalcula a cada render
  const filteredProducts = products.filter(p => p.active);

  return (
    <div>
      {filteredProducts.map(product => (
        <ProductCard
          key={product.id}
          product={product}
          {/* nova funcao criada a cada render */}
          onSelect={() => onSelect(product.id)}
          {/* novo objeto criado a cada render */}
          style={{ marginBottom: 16 }}
        />
      ))}
    </div>
  );
}

// DEPOIS: otimizado pelo Claude Code
const cardStyle = { marginBottom: 16 };

function ProductList({ products, onSelect }) {
  const filteredProducts = useMemo(
    () => products.filter(p => p.active),
    [products]
  );

  const handleSelect = useCallback(
    (id: string) => onSelect(id),
    [onSelect]
  );

  return (
    <div>
      {filteredProducts.map(product => (
        <ProductCard
          key={product.id}
          product={product}
          onSelect={handleSelect}
          style={cardStyle}
        />
      ))}
    </div>
  );
}

Code splitting e lazy loading

O Claude Code tambem pode analisar o bundle e sugerir code splitting:

8. Acessibilidade automatizada

Acessibilidade e frequentemente negligenciada em projetos React. O Claude Code ajuda auditando e corrigindo problemas de acessibilidade nos seus componentes.

O Claude Code verifica e corrige:

• Imagens sem alt text -- adiciona alt descritivo ou alt="" para imagens decorativas
• Botoes sem texto acessivel -- adiciona aria-label em botoes com apenas icone
• Formularios sem labels -- associa labels com inputs via htmlFor
• Focus trap em modais -- implementa focus management correto
• Contraste insuficiente -- alerta sobre combinacoes de cores com contraste abaixo de 4.5:1
• Navegacao por teclado -- garante que elementos interativos sao acessiveis via Tab/Enter/Escape

Ele pode tambem adicionar testes de acessibilidade automatizados usando jest-axe:

import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

it('nao tem violacoes de acessibilidade', async () => {
  const { container } = render(<ProductCard {...defaultProps} />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

9. Workflows completos de desenvolvimento

O real poder do Claude Code aparece quando voce combina multiplas tarefas em workflows completos. Aqui estao os workflows mais comuns para devs React:

Workflow 1: feature completa

O Claude Code cria todos os arquivos, implementa a logica, escreve os testes, roda para confirmar que passam e reporta o resultado. Uma feature que levaria horas, entregue em minutos.

Workflow 2: code review automatizado

Workflow 3: upgrade de dependencias

O Claude Code le o guia de migracao, identifica todos os pontos do codigo afetados, aplica as mudancas e valida com testes. Migracoes que costumam levar dias viram horas.