Boas Práticas de Integração de dApp Next.js
25 práticas para apps Solana com App Router e @solana/kit 7.0.0.
-
Provider client único na raiz: Um SolanaProvider no layout - sem duplicatas aninhadas (Providers e App Router).
-
Divisão servidor/client: Leituras em Server Components; assinatura em ilhas client (Noções Básicas de Integração de dApp).
-
URL de RPC no servidor sem NEXT_PUBLIC: Oculte API keys de provider em rotas de servidor.
-
Valide env no build: Falhe CI quando URL de RPC estiver ausente.
-
Mostre cluster na UI: Badge devnet vs mainnet sempre visível.
-
Use kit 7.0.0 em todo lugar: Evite novos imports de web3.js v1.
-
Simule antes do modal da carteira: Reduza aprovações com falha.
-
Máquina de estados de transação: idle → signing → sending → confirmed (UX de Transação).
-
Links do explorer no sucesso: Parâmetro de cluster obrigatório.
-
Desabilite submit enquanto pendente: Prevenha envios duplos.
-
Blockhash fresco por tentativa: Reconstrua em erros de expiração.
-
URL WSS para confirmações: Combine com sendAndConfirmTransactionFactory.
-
SWR + subscriptions: Seed HTTP, invalidação WebSocket (Cache e Tempo Real).
-
Nunca passe BigInt em props RSC: Serialize para string.
-
Chaves de patrocínio só no servidor: Route Handlers com rate limits (API Routes para Transações).
-
Auth em endpoints patrocinados: Prevenha abuso de relay aberto.
-
Clientes Codama tipados: Compartilhe decoders entre servidor e client.
-
Sanitize URLs de metadata NFT: Bloqueie XSS em hrefs de imagem.
-
Error boundaries em rotas de dashboard: Quedas de RPC não devem causar tela branca.
-
Skeletons de loading: Distinga zero vs loading vs erro.
-
Conexão lazy de carteira: Não abra modal no carregamento da landing.
-
Reset de estado ao desconectar: Limpe caches com escopo de usuário.
-
Priority fees na mainnet: Instruções de compute budget durante congestionamento.
-
Teste browsers mobile: Deep links de carteira diferem de extensões desktop.
-
Documente carteiras exigidas: Página de ajuda para QA e usuários.
FAQs
Pages Router?
Prefira App Router para apps novos; mesmos padrões kit aplicam com pages client.
Server Actions para assinatura?
Não - assinatura permanece no client para custódia do usuário.
Edge runtime?
Cuidado com Node fs para chaves de patrocínio - prefira route handlers Node runtime.
Relacionado
- Noções Básicas de Integração de dApp - estrutura
- Boas Práticas de Integração de Carteira - carteiras
- Boas Práticas do @solana/kit - camada kit
Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.