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

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