Melhores Práticas para Bibliotecas React

Um resumo condensado das 25 melhores práticas mais importantes, extraídas de cada página desta seção.

1. Retorne toDataStreamResponse: Um manipulador de rota do SDK de IA deve retornar result.toDataStreamResponse() (não result.text ou NextResponse.json); caso contrário, você envia um blob JSON de resposta completa e a UI de streaming useChat nunca é atualizada token a token.
2. Defina maxSteps para Chamadas de Ferramentas: Ferramentas definidas sem maxSteps têm o padrão de um único passo, então o modelo pode chamar uma ferramenta, mas nunca ver seu resultado e a conversa estagna - aumente para a profundidade máxima de raciocínio que você realmente deseja.
3. Use generateObject Com Zod: Para saída estruturada, generateObject({ schema }) com um esquema Zod impõe a forma na camada do SDK; solicitar JSON e fazer o parsing manual é frágil e desperdiça tokens em instruções de formato.
4. Codifique o Payload do Lambda como Uint8Array: InvokeCommand rejeita objetos simples em tempo de execução - envolva com new TextEncoder().encode(JSON.stringify(payload)) e decodifique a resposta simetricamente, respeitando os limites de payload de 6 MB síncrono / 256 KB assíncrono.
5. Verifique FunctionError, Não Use Catch: Erros de tempo de execução do Lambda chegam como um campo FunctionError na resposta, não como uma exceção lançada, então inspecione o envelope da resposta - invocações assíncronas (Event) descartam erros silenciosamente, a menos que você configure uma DLQ.
6. Observe os Limites de Caracteres do Polly: O mecanismo neural tem um limite de 3.000 caracteres por solicitação e o mecanismo padrão de 6.000, então divida textos longos em limites de frases e verifique o suporte neural com DescribeVoicesCommand antes de trocar de voz.
7. Envolva SSML em speak e Escape: A entrada SSML requer TextType: "ssml" e deve ser XML válido dentro de <speak>...</speak> com &, <, > escapados; também evite saída pcm para navegadores, pois é áudio bruto - use mp3 ou ogg_vorbis.
8. Faça Upload para S3 via Presigned PUT: Gere uma URL pré-assinada no servidor e deixe o navegador fazer PUT diretamente para o S3 para que uploads grandes ignorem o limite de corpo de requisição do Next.js (padrão de 1 MB) e nunca toquem na largura de banda do seu servidor.
9. Configure CORS do Bucket para PUT: Uploads do navegador para S3 exigem regras CORS explícitas do bucket listando sua origem, o método PUT e o cabeçalho Content-Type - e sempre defina ContentType no comando pré-assinado para que o objeto não seja salvo como application/octet-stream.
10. Mantenha os SDKs da AWS Apenas no Servidor: Nunca importe @aws-sdk/client-s3, client-lambda ou client-polly de um arquivo "use client" - credenciais acabam no bundle do navegador e o SDK v3 da AWS incha o JS do cliente; use Server Actions ou Route Handlers.
11. Use parseISO, Não new Date: new Date("2026-04-06") interpreta strings ISO apenas de data como meia-noite UTC e muda visivelmente em zonas não UTC, então prefira parseISO (mais date-fns-tz para trabalho ciente de fuso horário) para evitar bugs silenciosos de um dia de diferença.
12. Observe os Tokens de Formato MM vs mm: date-fns segue o TR#35 do Unicode, onde MM é mês, mm são minutos e DD é inválido (use dd) - erros de maiúsculas/minúsculas compilam bem e produzem strings silenciosamente erradas.
13. Formate Datas no Cliente: Datas formatadas renderizadas no servidor causam inconsistências de hidratação sempre que o fuso horário do servidor difere do cliente, então formate em um Client Component após a montagem ou passe o timestamp bruto e formate no navegador.
14. Envolva Itens de Arrastar em DragOverlay: DragOverlay renderiza a prévia de arrastar fora do fluxo do DOM e corrige o problema de "item saltando" quando o slot original colapsa; combine com opacidade reduzida no original para um visual estável.
15. Exija Movimento do Ponteiro para Iniciar o Arrastar: Adicione activationConstraint: { distance: 8 } (ou um atraso) ao PointerSensor para que um único clique não inicie um arrastar; sem isso, cada clique em um item ordenável dispara arrastamentos acidentais.
16. IDs Globalmente Únicos do dnd-kit: dnd-kit identifica itens apenas pelo ID em todos os contêineres, então IDs duplicados entre colunas quebram drops em múltiplos contêineres - use UUIDs ou chaves prefixadas pelo contêiner em vez de índices por lista.
17. Importe de lodash-es: Use importações nomeadas de lodash-es para que o bundler faça tree-shaking de utilitários não utilizados; import _ from "lodash" carrega todo o build CJS de ~70 KB mesmo para um único helper.
18. Memoize a Criação de debounce: Criar debounce(fn, 300) inline na renderização retorna uma nova instância a cada renderização e nunca acumula chamadas; envolva a criação em useMemo/useCallback e chame .cancel() na limpeza do useEffect para que invocações pendentes não disparem após o desmontar.
19. Passe um Alvo Fresco para merge: merge(target, source) do Lodash muta seu primeiro argumento, então sempre passe um {} fresco (ou cloneDeep primeiro) como alvo; prefira também structuredClone nativo em vez de cloneDeep, a menos que você precise de suporte a funções ou instâncias de classe.
20. Gere um AUTH_SECRET de 32+ Caracteres: Auth.js falha em produção sem AUTH_SECRET, e segredos fracos comprometem todas as sessões - gere um com npx auth secret e use valores distintos por ambiente para que uma chave de desenvolvimento vazada nunca comprometa a produção.
21. Credentials Provider é Apenas JWT: O provider Credentials não pode usar sessões de banco de dados mesmo com um adapter instalado, e estender tipos de sessão requer tanto o par de callbacks jwt/session quanto uma ampliação de módulo em types/next-auth.d.ts ou o TypeScript se desvia do tempo de execução.
22. Use um Cliente Prisma Singleton: Em desenvolvimento, anexe o cliente Prisma a globalThis para que a recarga a quente de módulos não abra um novo pool de conexões a cada salvamento - sem isso, o banco de dados rapidamente recusa conexões e o servidor de desenvolvimento parece travar.
23. Converta BigInt Antes da Serialização: Campos BigInt do Prisma não podem cruzar a fronteira Servidor→Cliente via JSON, então mapeie-os para Number ou String antes de passá-los para Client Components, e selecione apenas as relações que você precisa (com include/select) para evitar consultas N+1.
24. QueryClient Vive em useState: Construa o QueryClient do TanStack Query dentro de useState(() => new QueryClient()) dentro de um provider de cliente; um cliente em nível de módulo em um Server Component vaza o estado do cache entre requisições de usuário e vaza dados entre usuários.
25. Entenda staleTime vs gcTime: staleTime controla quando os dados são considerados frescos e se as refetches ocorrem; gcTime controla quanto tempo consultas inativas permanecem no cache - staleTime: Infinity ainda permite a coleta de lixo, e mutações nunca invalidam automaticamente consultas relacionadas sem invalidateQueries explícito.