UseOptimistic e useActionState do React 19: substituindo 80% do padrão do seu estado

Combinando os dois ganchos: exemplo Full-Stack Todo

Configuração do projeto

O exemplo a seguir usa React 19 no cliente e um endpoint mínimo da API Express/Node.js em POST /api/todos. O servidor simula um atraso de rede de 1 segundo e retorna aleatoriamente um erro 500 em aproximadamente 30% das vezes (em ambientes que não sejam de produção), o que facilita a observação do comportamento de reversão.

Garantir express.json() o middleware é registrado antes da rota para analisar o corpo da solicitação JSON.

Endpoint do servidor (server.js):

const express = require('express');
const app = express();

const ALLOWED_ORIGIN = process.env.ALLOWED_ORIGIN || 'http://localhost:5173';

app.use(express.json()); 

app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', ALLOWED_ORIGIN);
  res.header('Access-Control-Allow-Headers', 'Content-Type');
  res.header('Access-Control-Allow-Methods', 'POST, OPTIONS');

  if (req.method === 'OPTIONS') return res.sendStatus(204);

  next();
});

app.post('/api/todos', async (req, res, next) => {
  try {
    const { text } = req.body;

    if (typeof text !== 'string' || text.trim().length === 0 || text.length > 500) {
      return res.status(400).json({ error: 'Invalid text' });
    }

    await new Promise((resolve) => setTimeout(resolve, 1000));

    if (process.env.NODE_ENV !== 'production' && Math.random()  0.3) {
      return res.status(500).json({ error: 'Random server failure' });
    }

    const todo = { id: Date.now(), text: text.trim() };
    res.json(todo);
  } catch (err) {
    next(err);
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

Observação: Se o seu servidor de desenvolvimento React for executado em uma porta diferente (por exemplo, 5173 para Vite), defina o ALLOWED_ORIGIN variável de ambiente para corresponder à origem do seu servidor de desenvolvimento. O middleware CORS acima restringe o acesso a uma única origem permitida em vez de usar um curinga, o que é importante para a segurança nos terminais de mutação.

Instale a dependência do servidor separadamente:

npm install express

Construindo o Componente

O componente abaixo usa useOptimistic para feedback instantâneo da interface do usuário e useActionState para gerenciar o ciclo de vida do envio, incluindo estado pendente e exibição de erros. A função de ação retorna a lista de todos atualizada como parte do estado da ação, evitando o risco de simultaneidade de chamar setTodos de dentro de um useActionState Ação.

Chamar addOptimisticTodo antes de qualquer await expressão na ação. O sistema de transição do React captura apenas atualizações otimistas emitidas de forma síncrona antes do primeiro ponto de suspensão.

import { useOptimistic, useActionState } from 'react';

export default function TodoList() {
  
  async function todoAction(prevState, formData) {
    const text = formData.get('text');
    const tempTodo = { id: crypto.randomUUID(), text, pending: true };

    
    addOptimisticTodo(tempTodo);

    let res;
    try {
      res = await fetch('/api/todos', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ text }),
      });
    } catch {
      return { error: 'Network error. Please try again.', todos: prevState.todos };
    }

    if (!res.ok) {
      const errBody = await res.text();
      console.error('Todo API error:', res.status, errBody);
      
      return { error: 'Failed to add todo. Please try again.', todos: prevState.todos };
    }

    const savedTodo = await res.json();
    
    return { error: null, todos: (...prevState.todos, savedTodo) };
  }

  
  const (state, formAction, isPending) = useActionState(todoAction, {
    error: null,
    todos: (),
  });

  
  const (optimisticTodos, addOptimisticTodo) = useOptimistic(
    state.todos,
    (current, newTodo) => (...current, newTodo)
  );

  return (
    div>
      {state.error && !isPending && (
        p className="error" role="alert">{state.error}p>
      )}
      ul>
        {optimisticTodos.map((t) => (
          li key={t.id} style={{ opacity: t.pending ? 0.5 : 1 }}>{t.text}li>
        ))}
      ul>
      form action={formAction}>
        input name="text" required />
        button type="submit" disabled={isPending}>
          {isPending ? 'Adding...' : 'Add Todo'}
        button>
      form>
    div>
  );
}

O que acontece em caso de falha: passo a passo

A sequência é: o usuário envia o formulário. useActionState envolve a ação em uma transição React automaticamente. A tarefa otimista aparece instantaneamente na lista com opacidade reduzida (pending: true). Um segundo depois, o servidor retorna um erro 500. A função de ação retorna { error: 'Failed to add todo. Please try again.', todos: prevState.todos } com a lista de todos anterior inalterada. Quando a transição for concluída, o React reconcilia optimisticState de volta ao inalterado todose o item otimista desaparece da lista. A mensagem de erro é renderizada. Código de reversão manual zero.

Lista de verificação de implementação e guia de migração

Quando alcançar cada gancho

Lista de verificação de migração

Auditoria

1. Confirme React 19.0.0 ou posterior em package.json (npm install react@19 react-dom@19).
2. Identifique os componentes com o manual isLoading / error / data trios estaduais.
3. Identifique padrões de atualização otimistas em que os instantâneos de código estão antes da mutação e são revertidos em caso de falha.

Substituir

4. Substitua os manipuladores de envio por useActionState funções de ação usando o async (prevState, formData) => nextState assinatura. Importar useActionState de react.
5. Substituir onSubmit com (React DOM only).
6. Remove e.preventDefault() chamadas.
7. Substitua os padrões de instantâneo e reversão por useOptimisticpassando o estado canônico como primeiro argumento e sempre fornecendo um updateFn.
8. Envolva chamadas otimistas dentro da função de ação ou startTransition. Se estiver usando useActionStatea ação já está envolvida em uma transição. Use apenas explícito startTransition ao ligar addOptimistic fora de um useActionState ação ou manipulador de formulário.
9. Remover reversão manual catch blocos.