Gestión de Lanzamientos Frontend
La dApp de Solana es la mitad del producto: los lanzamientos de Next.js transportan URLs de RPC, IDs de programa, flags de características y versiones de adaptadores de billetera. Despliegues de frontend desincronizados causan más dolor al usuario que muchos errores en la cadena.
Receta
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
# .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!);Cuándo usar esto:
- Al enviar cambios de UI independientes de la actualización del programa
- Al rotar el proveedor de RPC sin desplegar el programa
- Estrategia de CDN y caché para la semana de lanzamiento
- Reversión de un incidente de error solo en el cliente
- Pruebas A/B de patrones de UX de transacciones
Ejemplo Funcional
// lib/solana-config.ts - validar al cargar el módulo
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("Variables de entorno de Solana faltantes");
}
if (process.env.VERCEL_ENV === "preview" && cluster === "mainnet-beta") {
throw new Error("Las compilaciones de vista previa no pueden apuntar a mainnet");
}
export const solanaConfig = { cluster, programId, rpcUrl };Lo que esto demuestra:
- Validación de entorno de fallo rápido en el cliente
@solana/kit7.0.0 - Bloqueo de despliegues de vista previa desde el clúster principal
- Módulo de configuración único importado por las rutas de la aplicación y la API
Análisis Profundo
Tren de Lanzamiento
- Fusionar a
main-> despliegue en staging (RPC de devnet) - Prueba: conexión de billetera, simulación de flujos principales
- Promocionar a producción con grupo de entorno de producción
- Etiquetar
dapp-v1.2.3vinculado aIDL_VERSION
RPC en Frontend
| Ruta | Nivel de RPC | Notas |
|---|---|---|
| Lecturas del navegador | Lectura pública o dedicada | Caché con TTL corto |
| Envío de ruta de API | Escritura premium + SWQoS | Claves solo del lado del servidor |
| Saldo SSR | RPC de lectura del servidor | Vigilar límites de tasa |
Trampas Comunes
- NEXT_PUBLIC_ expone secretos - Nunca pongas claves de API en el entorno público. Solución: Entorno solo del servidor para la ruta de envío.
- Caché ISR obsoleta - Se sirve un ID de programa antiguo. Solución: Revalidar en el webhook de despliegue.
- Desfase del adaptador de billetera - Rompe la conexión de billetera después de un aumento de dependencia. Solución: Fijar versiones de adaptador en el archivo de bloqueo.
- Actualización de programa sin cliente - Los usuarios acceden a la distribución incorrecta. Solución: Puerta de versión IDL en la UI.
- A/B sin persistencia de cohorte - Ruta de transacción inconsistente. Solución: Cohete hash de billetera (ver página de flags de características).
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Lanzamiento de aplicación móvil | MWA de Solana Mobile | Producto solo web |
| Enrutamiento con middleware de borde | RPC multiregión | RPC simple y único |
| Vercel Blue/green | Corte sin tiempo de inactividad | Carga de trabajo de equipo pequeña |
Preguntas Frecuentes
¿Con qué frecuencia se lanza el frontend?
Independiente del programa; muchos equipos lanzan diariamente con flags.
¿Seguridad de la URL de vista previa?
Bloquear duramente el entorno mainnet en vista previa; usar solo IDs de programa de devnet.
¿Dónde almacenar la URL del RPC?
Entorno por entorno; rotar a través de los secretos del proveedor de alojamiento sin reconstruir si se usa configuración en tiempo de ejecución.
¿Coordinar con el despliegue del programa?
Misma ventana de cambio para lanzamientos que rompen IDL; el frontend puede liderar con flags.
¿Velocidad de reversión?
Revertir el despliegue en la UI de alojamiento; purgar la caché de CDN; anunciar si es visible para el usuario.
¿Mostrar versión en la UI?
Mostrar IDL_VERSION en el pie de página para correlación de soporte.
¿SSR y billetera?
SSR solo para lecturas; la firma permanece en el lado del cliente.
¿Probar antes de producción?
Playwright contra staging con fixture de billetera de devnet.
¿Múltiples IDs de programa?
Mapa de configuración por programa; validar todos en la compilación.
¿Comunicaciones de incidentes?
La página de estado enlaza a la versión desplegada y a la versión anterior conocida como buena.
Relacionado
- Flags de Características y Despliegue Progresivo - habilitación gradual
- Promoción de Devnet a Mainnet - promoción de entornos
- Proveedores y App Router - integración de Next.js
Versiones de Stack: Esta página fue 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, y LiteSVM 0.6.x.