dApp Integration Basics

9 examples for structuring a Solana Next.js App Router dApp - 6 basic and 3 intermediate.

Prerequisites

npx create-solana-dapp@latest my-dapp
# or: npx create-next-app@latest && npm install @solana/kit@7.0.0

Use App Router (app/ directory). Wallet providers live in a client layout wrapper.

Basic Examples

1. Folder Layout

app/
  layout.tsx          # root
  solana-provider.tsx # "use client" providers
  page.tsx            # marketing (server OK)
  dashboard/
    page.tsx          # client-heavy UI

• Colocate Solana hooks under client boundaries.
• Keep read-only landing pages as Server Components.
• API routes in app/api/ for server-built txs.

2. Environment Variables

NEXT_PUBLIC_RPC_URL=https://api.devnet.solana.com
NEXT_PUBLIC_CLUSTER=devnet
# Server-only:
# SPONSOR_KEYPAIR_PATH=...

• NEXT_PUBLIC_ values ship to browser - never secrets.
• Validate env at build with zod or t3-env.
• Document cluster in UI footer.

3. Client Provider Shell

// app/solana-provider.tsx
"use client";
export function SolanaProvider({ children }: { children: React.ReactNode }) {
  return <WalletProviders>{children}</WalletProviders>;
}

• Import wallet UI CSS once here.
• Single provider tree prevents duplicate modals.
• See Providers & App Router.

4. Server Read + Client Write Split

// Server Component: createSolanaRpc reads
// Client Component: wallet signs and sends

• Never pass private keys to the client.
• Serialize plain JSON across the server/client boundary.
• See Server-Side Reads.

5. Display Wallet Address

"use client";
import { useWallet } from "@solana/wallet-adapter-react";

• Truncate address for layout.
• Copy-to-clipboard for power users.
• Show disconnect adjacent to address.

6. Loading and Error Boundaries

// app/dashboard/error.tsx and loading.tsx

• RPC failures should not white-screen.
• Retry button for transient 429 errors.
• Log correlation id for support.

Intermediate Examples

7. API Route for Sponsored Tx

// app/api/tx/route.ts - server builds partial tx

• Server pays fees or adds signatures only it holds.
• Return serialized message for wallet to co-sign.
• See API Routes for Transactions.

8. SWR / Realtime Balance

"use client";
// useSWR + accountSubscribe for live balance

• Combine HTTP seed with WebSocket updates.
• Abort subscription on unmount.
• See Caching & Realtime.

9. Transaction Toast UX

// pending → confirmed → explorer link

• Disable submit while in-flight.
• Decode errors for humans.
• See Transaction UX.

Stack versions: This page was written for 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, and LiteSVM 0.6.x.