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.

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.

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.

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.

Next.js dApp Integration Best Practices

FAQs

Related

Search Documentation

Next.js dApp Integration Best Practices

FAQs

Related