Prácticas recomendadas para la integración de dApps en Next.js
25 prácticas para aplicaciones de App Router en Solana con @solana/kit 7.0.0.
-
Proveedor de cliente único en la raíz: Un único
SolanaProvideren ellayout- sin duplicados anidados (Proveedores y App Router). -
División servidor/cliente: Lecturas en Server Components; firma en "islas" de cliente (Conceptos básicos de integración de dApps).
-
URL RPC del servidor sin NEXT_PUBLIC: Oculta las claves API del proveedor en las rutas del servidor.
-
Valida el entorno en la compilación: Falla CI cuando falta la URL RPC.
-
Muestra el clúster en la interfaz de usuario: Insignia de Devnet vs. Mainnet siempre visible.
-
Usa kit 7.0.0 en todas partes: Evita nuevas importaciones de web3.js v1.
-
Simula antes del modal de la billetera: Reduce las aprobaciones fallidas.
-
Máquina de estados de transacción:
idle→signing→sending→confirmed(Experiencia de usuario de transacciones). -
Enlaces al explorador en caso de éxito: El parámetro
clusterde consulta es obligatorio. -
Deshabilita el envío mientras está pendiente: Evita envíos dobles.
-
Hash de bloque fresco por intento: Reconstruye en errores de caducidad.
-
URL WSS para confirmaciones: Empareja con
sendAndConfirmTransactionFactory. -
SWR + suscripciones: Semilla HTTP, invalida WebSocket (Caché y tiempo real).
-
Nunca pases BigInt en props de RSC: Serializa a cadena.
-
Claves de patrocinador solo en el servidor:
Route Handlerscon límites de tasa (Rutas API para transacciones). -
Autenticación en puntos de conexión patrocinados: Evita el abuso de retransmisión abierta.
-
Clientes Codama tipados: Comparte decodificadores entre servidor y cliente.
-
Sanea las URL de metadatos de NFT: Bloquea XSS en los
hrefde las imágenes. -
Límites de error en las rutas del panel: Las interrupciones de RPC no deben provocar pantallas en blanco.
-
Esqueletos de carga: Distingue entre cero, cargando y error.
-
Conexión de billetera diferida: No muestres el modal al cargar la página de destino.
-
Restablece el estado al desconectar: Limpia las cachés específicas del usuario.
-
Tarifas de prioridad en Mainnet: Instrucciones de presupuesto de cómputo durante la congestión.
-
Prueba navegadores móviles: Los enlaces profundos de las billeteras difieren de las extensiones de escritorio.
-
Documenta las billeteras requeridas: Página de ayuda para QA y usuarios.
Preguntas frecuentes
¿Pages Router?
Prefiere App Router para aplicaciones nuevas; los mismos patrones de kit se aplican con páginas de cliente.
¿Server Actions para firmar?
No - la firma permanece en el lado del cliente para la custodia del usuario.
¿Runtime de Edge?
Ten cuidado con Node fs para las claves de patrocinador; prefiere Route Handlers con runtime de Node.
Relacionados
- Conceptos básicos de integración de dApps - estructura
- Prácticas recomendadas para la integración de billeteras - billeteras
- Prácticas recomendadas de @solana/kit - capa de kit
Versiones de la pila: Esta página se escribió 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.