Fundamentos de Integración de dApps
9 ejemplos para estructurar una dApp de Solana con Next.js App Router: 6 básicos y 3 intermedios.
Prerrequisitos
npx create-solana-dapp@latest my-dapp
# o: npx create-next-app@latest && npm install @solana/kit@7.0.0Usa App Router (app/ directory). Los proveedores de wallet viven en un wrapper de layout del cliente.
Ejemplos Básicos
1. Estructura de Carpetas
app/
layout.tsx # raíz
solana-provider.tsx # proveedores "use client"
page.tsx # marketing (servidor OK)
dashboard/
page.tsx # UI con mucha lógica del cliente
- Coloca los hooks de Solana bajo los límites del cliente.
- Mantén las páginas de aterrizaje de solo lectura como Server Components.
- Rutas API en
app/api/para transacciones construidas en el servidor.
2. Variables de Entorno
NEXT_PUBLIC_RPC_URL=https://api.devnet.solana.com
NEXT_PUBLIC_CLUSTER=devnet
# Solo servidor:
# SPONSOR_KEYPAIR_PATH=...- Los valores
NEXT_PUBLIC_se envían al navegador; nunca secretos. - Valida el entorno en la compilación con zod o t3-env.
- Documenta el cluster en el pie de página de la UI.
3. Shell del Proveedor del Cliente
// app/solana-provider.tsx
"use client";
export function SolanaProvider({ children }: { children: React.ReactNode }) {
return <WalletProviders>{children}</WalletProviders>;
}- Importa el CSS de la UI de la wallet una vez aquí.
- Un único árbol de proveedores evita modales duplicados.
- Ver Proveedores y App Router.
4. División Lectura del Servidor + Escritura del Cliente
// Server Component: createSolanaRpc lee
// Client Component: wallet firma y envía- Nunca pases claves privadas al cliente.
- Serializa JSON plano a través del límite servidor/cliente.
- Ver Lecturas del Lado del Servidor.
5. Mostrar Dirección de la Wallet
"use client";
import { useWallet } from "@solana/wallet-adapter-react";- Trunca la dirección para el layout.
- Copiar al portapapeles para usuarios avanzados.
- Muestra desconexión junto a la dirección.
6. Límites de Carga y Error
// app/dashboard/error.tsx y loading.tsx- Los fallos de RPC no deben causar una pantalla blanca.
- Botón de reintento para errores transitorios 429.
- ID de correlación de registro para soporte.
Ejemplos Intermedios
7. Ruta API para Transacción Patrocinada
// app/api/tx/route.ts - el servidor construye la tx parcial- El servidor paga las tarifas o añade firmas que solo él posee.
- Devuelve el mensaje serializado para que la wallet co-firme.
- Ver Rutas API para Transacciones.
8. SWR / Saldo en Tiempo Real
"use client";
// useSWR + accountSubscribe para saldo en vivo- Combina el seed HTTP con actualizaciones WebSocket.
- Aborta la suscripción al desmontar.
- Ver Caché y Tiempo Real.
9. UX de Toast de Transacción
// pendiente → confirmado → enlace al explorador- Deshabilita el envío mientras está en curso.
- Decodifica errores para humanos.
- Ver UX de Transacción.
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.