Gerenciamento de Releases de Frontend
O dApp Solana é metade do produto: releases do Next.js carregam URLs de RPC, IDs de programa, flags de recursos e versões de adaptadores de carteira. Deployments de frontend incompatíveis causam mais dor ao usuário do que muitos bugs on-chain.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
# .env.production
NEXT_PUBLIC_CLUSTER=mainnet-beta
NEXT_PUBLIC_RPC_URL=https://your-mainnet-rpc.example
NEXT_PUBLIC_PROGRAM_ID=Hx7k...
NEXT_PUBLIC_IDL_VERSION=2.4.0import { createSolanaRpc } from "@solana/kit";
const rpc = createSolanaRpc(process.env.NEXT_PUBLIC_RPC_URL!);Quando usar isso:
- Lançando alterações de UI independentes da atualização do programa
- Rotacionando o provedor de RPC sem deploy de programa
- Estratégia de CDN e cache na semana de lançamento
- Rollback de incidente de bug apenas no cliente
- Testando padrões de UX de transação A/B
Exemplo de Trabalho
// lib/solana-config.ts - validate at module load
const cluster = process.env.NEXT_PUBLIC_CLUSTER;
const programId = process.env.NEXT_PUBLIC_PROGRAM_ID;
const rpcUrl = process.env.NEXT_PUBLIC_RPC_URL;
if (!cluster || !programId || !rpcUrl) {
throw new Error("Missing Solana env vars");
}
if (process.env.VERCEL_ENV === "preview" && cluster === "mainnet-beta") {
throw new Error("Preview builds cannot target mainnet");
}
export const solanaConfig = { cluster, programId, rpcUrl };O que isso demonstra:
- Validação de ambiente fail-fast no cliente
@solana/kit7.0.0 - Bloqueio de deploys de preview do cluster mainnet
- Módulo de configuração único importado pelas rotas de app e API
Análise Detalhada
Trem de Releases
- Merge para
main-> deploy em staging (RPC devnet) - Teste: conexão de carteira, simulação dos fluxos principais
- Promoção para produção com grupo de ambiente de produção
- Tag
dapp-v1.2.3vinculada aIDL_VERSION
RPC no Frontend
| Caminho | Nível de RPC | Notas |
|---|---|---|
| Leituras do Navegador | Leitura pública ou dedicada | Cache com TTL curto |
| Envio de rota de API | Escrita premium + SWQoS | Chaves apenas no lado do servidor |
| Saldo SSR | RPC de leitura do servidor | Monitorar limites de taxa |
Armadilhas
- NEXT_PUBLIC_ expõe segredos - Nunca coloque chaves de API em envs públicas. Correção: Env apenas para o servidor para o caminho de envio.
- Cache ISR desatualizado - ID do programa antigo servido. Correção: Revalidar no webhook de deploy.
- Divergência do adaptador de carteira - Quebra a conexão da carteira após a atualização da dependência. Correção: Fixar versões do adaptador no lockfile.
- Atualização do programa sem cliente - Usuários atingem layout de instrução incorreto. Correção: Gate de versão IDL na UI.
- A/B sem persistência de coorte - Caminho de transação inconsistente. Correção: Coorte de hash de carteira (ver página de flags de recursos).
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Release de aplicativo móvel | MWA do Solana Mobile | Produto apenas para web |
| Roteamento com middleware de edge | RPC multi-região | RPC simples e único |
| Blue/green Vercel | Transição zero-downtime | Sobrecarga de equipe pequena |
FAQs
Com que frequência enviar frontend?
Independente do programa; muitas equipes enviam diariamente com flags.
Segurança do URL de preview?
Bloquear hardmente o ambiente mainnet em preview; usar apenas IDs de programa devnet.
Onde armazenar URL de RPC?
Env por ambiente; rotacionar via segredos do provedor de hospedagem sem reconstruir se usar configuração em tempo de execução.
Coordenar com deploy de programa?
Mesma janela de alteração para releases que quebram IDL; frontend pode liderar com flags.
Velocidade de rollback?
Reverter deploy na UI de hospedagem; purgar cache CDN; anunciar se for voltado para o usuário.
Exibição de versão na UI?
Mostrar IDL_VERSION no rodapé para correlação de suporte.
SSR e carteira?
SSR apenas para leituras; assinatura permanece no lado do cliente.
Testar antes da produção?
Playwright contra staging com fixture de carteira devnet.
Múltiplos IDs de programa?
Mapa de configuração por programa; validar todos na build.
Comunicações de incidente?
Links da página de status para a versão implantada e a versão anterior conhecida como boa.
Relacionados
- Flags de Recursos e Rollout Progressivo - habilitação gradual
- Promoção de Devnet para Mainnet - promoção de ambiente
- Provedores e App Router - integração Next.js
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.