Gerenciamento de Releases de Frontend

Q: Exibição de versão na UI?

Mostrar IDL_VERSION no rodapé para correlação de suporte.

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.0

import { 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/kit 7.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.3 vinculada a IDL_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.

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.0

import { 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/kit 7.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.3 vinculada a IDL_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.

Gerenciamento de Releases de Frontend

Buscar na documentação

Gerenciamento de Releases de Frontend