Noções Básicas de Integração de dApp

9 exemplos para estruturar um dApp Solana Next.js com App Router - 6 básicos e 3 intermediários.

Pré-requisitos

npx create-solana-dapp@latest my-dapp
# ou: npx create-next-app@latest && npm install @solana/kit@7.0.0

Use o App Router (diretório app/). Provedores de carteira residem em um wrapper de layout do cliente.

Exemplos Básicos

1. Layout de Pastas

app/
  layout.tsx          # raiz
  solana-provider.tsx # providers "use client"
  page.tsx            # marketing (servidor OK)
  dashboard/
    page.tsx          # UI com uso intensivo do cliente

• Coloque hooks Solana sob limites do cliente.
• Mantenha páginas de destino somente leitura como Server Components.
• Rotas de API em app/api/ para transações criadas no servidor.

2. Variáveis de Ambiente

NEXT_PUBLIC_RPC_URL=https://api.devnet.solana.com
NEXT_PUBLIC_CLUSTER=devnet
# Somente servidor:
# SPONSOR_KEYPAIR_PATH=...

• Valores NEXT_PUBLIC_ são enviados ao navegador - nunca segredos.
• Valide o ambiente no build com zod ou t3-env.
• Documente o cluster no rodapé da UI.

3. Shell de Provedor do Cliente

// app/solana-provider.tsx
"use client";
export function SolanaProvider({ children }: { children: React.ReactNode }) {
  return <WalletProviders>{children}</WalletProviders>;
}

• Importe o CSS da UI da carteira uma vez aqui.
• Uma única árvore de provedores evita modais duplicados.
• Veja Provedores e App Router.

4. Divisão Leitura do Servidor + Escrita do Cliente

// Server Component: createSolanaRpc lê
// Client Component: carteira assina e envia

• Nunca passe chaves privadas para o cliente.
• Serialize JSON simples através da fronteira servidor/cliente.
• Veja Leituras do Lado do Servidor.

5. Exibir Endereço da Carteira

"use client";
import { useWallet } from "@solana/wallet-adapter-react";

• Trunque o endereço para o layout.
• Copiar para a área de transferência para usuários avançados.
• Mostre desconectar adjacente ao endereço.

6. Limites de Carregamento e Erro

// app/dashboard/error.tsx e loading.tsx

• Falhas de RPC não devem causar tela branca.
• Botão de tentar novamente para erros 429 transitórios.
• ID de correlação de log para suporte.

Exemplos Intermediários

7. Rota de API para Tx Patrocinada

// app/api/tx/route.ts - servidor constrói tx parcial

• O servidor paga taxas ou adiciona assinaturas que apenas ele detém.
• Retorne mensagem serializada para a carteira co-assinar.
• Veja Rotas de API para Transações.

8. SWR / Saldo em Tempo Real

"use client";
// useSWR + accountSubscribe para saldo ao vivo

• Combine seed HTTP com atualizações WebSocket.
• Cancele a subscrição ao desmontar.
• Veja Cache e Tempo Real.

9. UX de Toast de Transação

// pendente → confirmado → link do explorer

• Desabilite o envio enquanto estiver em andamento.
• Decodifique erros para humanos.
• Veja UX de Transação.

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.