1---
2title: Frontend with framework-kit
3description: Build React and Next.js Solana apps with a single client instance, Wallet Standard-first connection, and minimal client-side footprint.
4---
5 
6# Frontend with framework-kit (Next.js / React)
7 
8## Goals
9- One Solana client instance for the app (RPC + WS + wallet connectors)
10- Wallet Standard-first discovery/connect
11- Minimal "use client" footprint in Next.js (hooks only in leaf components)
12- Transaction sending that is observable, cancelable, and UX-friendly
13 
14## Recommended dependencies
15- @solana/client
16- @solana/react-hooks
17- @solana/kit
18- @solana-program/system, @solana-program/token, etc. (only what you need)
19 
20## Bootstrap recommendation
21Prefer `create-solana-dapp` and pick a kit/framework-kit compatible template for new projects.
22 
23## Provider setup (Next.js App Router)
24Create a single client and provide it via SolanaProvider.
25 
26Example `app/providers.tsx`:
27 
28```tsx
29'use client';
30 
31import React from 'react';
32import { SolanaProvider } from '@solana/react-hooks';
33import { autoDiscover, createClient } from '@solana/client';
34 
35const endpoint =
36  process.env.NEXT_PUBLIC_SOLANA_RPC_URL ?? 'https://api.devnet.solana.com';
37 
38// Some environments prefer an explicit WS endpoint; default to wss derived from https.
39const websocketEndpoint =
40  process.env.NEXT_PUBLIC_SOLANA_WS_URL ??
41  endpoint.replace('https://', 'wss://').replace('http://', 'ws://');
42 
43export const solanaClient = createClient({
44  endpoint,
45  websocketEndpoint,
46  walletConnectors: autoDiscover(),
47});
48 
49export function Providers({ children }: { children: React.ReactNode }) {
50  return <SolanaProvider client={solanaClient}>{children}</SolanaProvider>;
51}
52```
53 
54Then wrap `app/layout.tsx` with `<Providers>`.
55 
56## Hook usage patterns (high-level)
57 
58Prefer framework-kit hooks before writing your own store/subscription logic:
59 
60* `useWalletConnection()` for connect/disconnect and wallet discovery
61* `useBalance(...)` for lamports balance
62* `useSolTransfer(...)` for SOL transfers
63* `useSplToken(...)` / token helpers for token balances/transfers
64* `useTransactionPool(...)` for managing send + status + retry flows
65 
66When you need custom instructions, build them using `@solana-program/*` and send them via the framework-kit transaction helpers.
67 
68## Data fetching and subscriptions
69 
70* Prefer watchers/subscriptions rather than manual polling.
71* Clean up subscriptions with abort handles returned by watchers.
72* For Next.js: keep server components server-side; only leaf components that call hooks should be client components.
73 
74## Transaction UX checklist
75 
76* Disable inputs while a transaction is pending
77* Provide a signature immediately after send
78* Track confirmation states (processed/confirmed/finalized) based on UX need
79* Show actionable errors:
80 
81  * user rejected signing
82  * insufficient SOL for fees / rent
83  * blockhash expired / dropped
84  * account already in use / already initialized
85  * program error (custom error code)
86 
87## When to use ConnectorKit (optional)
88 
89If you need a headless connector with composable UI elements and explicit state control, use ConnectorKit.
90Typical reasons:
91 
92* You want a headless wallet connection core (useful across frameworks)
93* You want more control over wallet/account state than a single provider gives
94* You need production diagnostics/health checks for wallet sessions
95