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.0Use App Router (diretório app/). Provedores de carteira ficam em um wrapper de layout client.
Exemplos Básicos
1. Layout de Pastas
app/
layout.tsx # raiz
solana-provider.tsx # providers "use client"
page.tsx # marketing (server OK)
dashboard/
page.tsx # UI pesada no client
- Coloque hooks Solana sob boundaries client.
- Mantenha landing pages somente leitura como Server Components.
- API routes em
app/api/para txs montadas 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_vão para o browser - nunca secrets. - Valide env no build com zod ou t3-env.
- Documente o cluster no rodapé da UI.
3. Shell de Provider Client
// app/solana-provider.tsx
"use client";
export function SolanaProvider({ children }: { children: React.ReactNode }) {
return <WalletProviders>{children}</WalletProviders>;
}- Importe CSS de wallet UI uma vez aqui.
- Árvore de provider única evita modais duplicados.
- Veja Providers e App Router.
4. Divisão Leitura no Servidor + Escrita no Client
// Server Component: createSolanaRpc lê
// Client Component: carteira assina e envia- Nunca passe chaves privadas ao client.
- Serialize JSON simples através da borda servidor/client.
- Veja Leituras no 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 área de transferência para usuários avançados.
- Mostre desconectar ao lado do endereço.
6. Loading e Error Boundaries
// app/dashboard/error.tsx e loading.tsx- Falhas de RPC não devem causar tela branca.
- Botão de retry para erros 429 transitórios.
- Log de correlation id para suporte.
Exemplos Intermediários
7. API Route para Tx Patrocinada
// app/api/tx/route.ts - servidor monta tx parcial- Servidor paga taxas ou adiciona assinaturas que só ele possui.
- Retorne mensagem serializada para a carteira co-assinar.
- Veja API Routes 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 subscription no unmount.
- Veja Cache e Tempo Real.
9. Toast UX de Transação
// pending → confirmed → link do explorer- Desabilite submit enquanto em voo.
- 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.