Next.js dApp Integration Best Practices
25 practices for App Router Solana apps with @solana/kit 7.0.0.
-
Single client provider at root: One SolanaProvider in layout - no nested duplicates (Providers & App Router).
-
Server/client split: Reads in Server Components; signing in client islands (dApp Integration Basics).
-
Server RPC URL without NEXT_PUBLIC: Hide provider API keys on server routes.
-
Validate env at build: Fail CI when RPC URL missing.
-
Show cluster in UI: Devnet vs mainnet badge always visible.
-
Use kit 7.0.0 everywhere: Avoid new web3.js v1 imports.
-
Simulate before wallet modal: Reduce failed approvals.
-
Transaction state machine: idle → signing → sending → confirmed (Transaction UX).
-
Explorer links on success: Cluster query param required.
-
Disable submit while pending: Prevent double sends.
-
Fresh blockhash per attempt: Rebuild on expiry errors.
-
WSS URL for confirmations: Pair with sendAndConfirmTransactionFactory.
-
SWR + subscriptions: HTTP seed, WebSocket invalidate (Caching & Realtime).
-
Never pass BigInt in RSC props: Serialize to string.
-
Sponsor keys only on server: Route Handlers with rate limits (API Routes for Transactions).
-
Auth on sponsored endpoints: Prevent open relay abuse.
-
Typed Codama clients: Share decoders between server and client.
-
Sanitize NFT metadata URLs: Block XSS in image hrefs.
-
Error boundaries on dashboard routes: RPC outages should not white-screen.
-
Loading skeletons: Distinguish zero vs loading vs error.
-
Lazy wallet connect: Do not modal on landing page load.
-
Reset state on disconnect: Clear user-scoped caches.
-
Priority fees on mainnet: Compute budget instructions during congestion.
-
Test mobile browsers: Wallet deep links differ from desktop extensions.
-
Document required wallets: Help page for QA and users.
FAQs
Pages Router?
Prefer App Router for new apps; same kit patterns apply with client pages.
Server Actions for signing?
No - signing stays client-side for user custody.
Edge runtime?
Careful with Node fs for sponsor keys - prefer Node runtime route handlers.
Related
- dApp Integration Basics - structure
- Wallet Integration Best Practices - wallets
- @solana/kit Best Practices - kit layer
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.