1---
2title: Plugins & Client Composition
3description: Solana Kit plugin architecture, all-in-one RPC/LiteSVM plugins, signer plugins, custom client composition, and plugin ordering rules.
4---
5 
6# Solana Kit Plugins & Client Composition
7 
8Kit clients are built by chaining `.use(plugin)` calls onto `createClient()`. Each plugin extends the client with new properties or methods. Plugins that depend on others (e.g., RPC needs a payer) must come after their dependencies — TypeScript enforces this.
9 
10## All-in-One Clients
11 
12### Production Client (mainnet/devnet/custom)
13 
14```bash
15npm install @solana/kit @solana/kit-plugin-rpc @solana/kit-plugin-signer
16```
17 
18```ts
19import { createClient } from '@solana/kit';
20import { solanaRpc } from '@solana/kit-plugin-rpc';
21import { signer } from '@solana/kit-plugin-signer';
22 
23const client = createClient()
24  .use(signer(mySigner)) // sets payer + identity to the same keypair
25  .use(solanaRpc({ rpcUrl: 'https://api.mainnet-beta.solana.com' }));
26 
27await client.sendTransaction([myInstruction]);
28```
29 
30`solanaRpc` installs an RPC connection, RPC subscriptions, minimum-balance computation, transaction planner, and transaction executor in one call. It requires a `payer` to be set first — `signer()` covers that and the identity role at the same time. Reach for the role-specific `payer()` + `identity()` only when fees and authority must come from different keypairs.
31 
32**`solanaRpc` options:**
33 
34| Option | Type | Description |
35|--------|------|-------------|
36| `rpcUrl` | `string` | RPC endpoint (required) |
37| `rpcSubscriptionsUrl` | `string` | WS endpoint (defaults to `rpcUrl` with `http`→`ws`) |
38| `rpcConfig` | `object` | Forwarded to `createSolanaRpc` |
39| `rpcSubscriptionsConfig` | `object` | Forwarded to `createSolanaRpcSubscriptions` |
40| `transactionConfig` | `object` | Tx planner options (priority fees, etc.) |
41| `maxConcurrency` | `number` | Concurrent tx limit (default: 10) |
42| `skipPreflight` | `boolean` | Always skip preflight (default: false) |
43 
44### Cluster-Specialized Variants
45 
46```ts
47import { createClient } from '@solana/kit';
48import { solanaMainnetRpc, solanaDevnetRpc, solanaLocalRpc } from '@solana/kit-plugin-rpc';
49import { signer, signerFromFile } from '@solana/kit-plugin-signer';
50 
51// Mainnet — type-narrowed; airdrop is NOT exposed
52const main = createClient().use(signer(s)).use(solanaMainnetRpc({ rpcUrl: '...' }));
53 
54// Devnet — defaults to https://api.devnet.solana.com, includes airdrop
55const dev = createClient().use(signer(s)).use(solanaDevnetRpc());
56 
57// Local — defaults to http://127.0.0.1:8899, includes airdrop
58const local = await createClient()
59  .use(signerFromFile('~/.config/solana/id.json'))
60  .use(solanaLocalRpc());
61```
62 
63### LiteSVM Test Client
64 
65```bash
66npm install @solana/kit @solana/kit-plugin-litesvm @solana/kit-plugin-signer
67```
68 
69```ts
70import { createClient, lamports } from '@solana/kit';
71import { litesvm } from '@solana/kit-plugin-litesvm';
72import { airdropSigner, generatedSigner } from '@solana/kit-plugin-signer';
73 
74const client = await createClient()
75  .use(generatedSigner())
76  .use(litesvm())
77  .use(airdropSigner(lamports(1_000_000_000n)));
78 
79client.svm.setAccount(myTestAccount);
80client.svm.addProgramFromFile(myProgramAddress, 'program.so');
81 
82await client.sendTransaction([myInstruction]);
83```
84 
85`litesvm()` is Node.js only. Browser/React Native builds throw.
86 
87---
88 
89## Client API Surface
90 
91See [overview.md](overview.md#client-api) for the full surface (`client.rpc`, `client.payer`, `client.sendTransaction`, etc.). Plugin-specific additions:
92 
93- `solanaDevnetRpc` / `solanaLocalRpc` / `litesvm` add `client.airdrop(address, lamports)`.
94- `litesvm` additionally adds `client.svm` for direct LiteSVM access.
95- The low-level composition (Custom Client Composition below) also exposes `client.transactionPlanner` and `client.transactionPlanExecutor` directly.
96 
97---
98 
99## Signer Plugins (`@solana/kit-plugin-signer`)
100 
101Kit clients hold two signer roles:
102- **`payer`** — pays fees and rent
103- **`identity`** — wallet/authority for application accounts
104 
105In most apps both roles are the same keypair, so **default to the `signer*` variants** — they install one keypair into both slots in one call. Use the role-specific `payer*` / `identity*` variants only when fees and authority come from different keypairs (e.g., gasless flows, treasury accounts, multisig).
106 
107| Variant | Sets |
108|---|---|
109| `signer*` (recommended default) | both `payer` and `identity` (same keypair) |
110| `payer*` | only `payer` |
111| `identity*` | only `identity` |
112 
113| Plugin | Behavior |
114|---|---|
115| `signer(s)` / `payer(s)` / `identity(s)` | Install an existing `TransactionSigner` |
116| `generatedSigner()` / `generatedPayer()` / `generatedIdentity()` | Async; generate a new keypair |
117| `generatedSignerWithSol(amount)` / `generatedPayerWithSol(amount)` / `generatedIdentityWithSol(amount)` | Async; generate + airdrop. Requires an airdrop function already on the client (for low-level composition, install `rpcAirdrop()` first). |
118| `signerFromFile(path)` / `payerFromFile(path)` / `identityFromFile(path)` | Async; load keypair from a JSON file |
119| `airdropSigner(amount)` / `airdropPayer(amount)` / `airdropIdentity(amount)` | Airdrop SOL to an already-installed signer. Use with all-in-one `solanaLocalRpc` / `solanaDevnetRpc` / `litesvm` when the RPC plugin needs a payer first. |
120 
121```ts
122import { createClient, lamports } from '@solana/kit';
123import { rpcAirdrop, solanaRpcConnection } from '@solana/kit-plugin-rpc';
124import { generatedSignerWithSol } from '@solana/kit-plugin-signer';
125 
126// `solanaRpcConnection` installs both `rpc` and `rpcSubscriptions`; the WS URL
127// is derived from `rpcUrl` (override with `rpcSubscriptionsUrl` if needed).
128// Airdrop function must exist before generatedSignerWithSol.
129const client = await createClient()
130  .use(solanaRpcConnection({ rpcUrl: 'http://127.0.0.1:8899' }))
131  .use(rpcAirdrop())
132  .use(generatedSignerWithSol(lamports(10_000_000_000n)));
133```
134 
135**Role-split example** (different keypairs for fees vs. authority):
136 
137```ts
138import { createClient } from '@solana/kit';
139import { solanaDevnetRpc } from '@solana/kit-plugin-rpc';
140import { payer, identity } from '@solana/kit-plugin-signer';
141 
142const client = createClient()
143  .use(payer(feePayerSigner))      // pays fees
144  .use(identity(walletSigner))     // owns/authorizes accounts
145  .use(solanaDevnetRpc());
146```
147 
148---
149 
150## Custom Client Composition
151 
152When the all-in-one bundles don't fit (custom transaction planner, partial capabilities, third-party services), build the client out of low-level plugins:
153 
154```ts
155import { createClient } from '@solana/kit';
156import {
157  rpc,
158  rpcAirdrop,
159  rpcGetMinimumBalance,
160  rpcTransactionPlanner,
161  rpcTransactionPlanExecutor,
162} from '@solana/kit-plugin-rpc';
163import { signerFromFile } from '@solana/kit-plugin-signer';
164import { planAndSendTransactions } from '@solana/kit-plugin-instruction-plan';
165 
166const client = await createClient()
167  .use(rpc('https://api.devnet.solana.com'))    // adds client.rpc + client.rpcSubscriptions
168  .use(signerFromFile('path/to/keypair.json'))  // adds client.payer + client.identity
169  .use(rpcAirdrop())                             // adds client.airdrop
170  .use(rpcGetMinimumBalance())                   // adds client.getMinimumBalance
171  .use(rpcTransactionPlanner())                  // adds client.transactionPlanner
172  .use(rpcTransactionPlanExecutor())             // adds client.transactionPlanExecutor
173  .use(planAndSendTransactions());               // adds client.sendTransaction(s)
174```
175 
176### Plugin Ordering
177 
178Plugins that depend on others must come after their dependencies. TypeScript enforces this:
179 
180```ts
181// ✅ Correct — signer + rpc before planner/executor
182createClient()
183  .use(signer(mySigner))
184  .use(rpc(url))
185  .use(rpcTransactionPlanner())
186  .use(planAndSendTransactions());
187 
188// ❌ Type error — solanaRpc requires payer
189createClient()
190  .use(solanaRpc({ rpcUrl: url }))
191  .use(signer(mySigner));
192```
193 
194### Async Plugins
195 
196Some plugins are async (e.g., `signerFromFile`, `generatedSigner`, `generatedSignerWithSol`). The `.use()` method handles awaiting automatically — `await` the final client:
197 
198```ts
199const client = await createClient()
200  .use(signerFromFile('./keypair.json'))        // async
201  .use(solanaLocalRpc());
202```
203 
204---
205 
206## Plugin Catalog
207 
208### Official Plugins
209 
210| Package | Plugins | Purpose |
211|---------|---------|---------|
212| `@solana/kit-plugin-rpc` | `solanaRpc`, `solanaMainnetRpc`, `solanaDevnetRpc`, `solanaLocalRpc`, `rpc`, `solanaRpcConnection`, `rpcAirdrop`, `rpcGetMinimumBalance`, `rpcTransactionPlanner`, `rpcTransactionPlanExecutor` | RPC connectivity + tx planning/execution |
213| `@solana/kit-plugin-signer` | `signer*` (default — sets both roles), `payer*`, `identity*` (role-specific); each comes in plain, `generated*`, `*WithSol`, `*FromFile`, and `airdrop*` forms | Signer management |
214| `@solana/kit-plugin-litesvm` | `litesvm`, `litesvmConnection`, `litesvmAirdrop`, `litesvmTransactionPlanner`, `litesvmTransactionPlanExecutor` | In-memory test environment |
215| `@solana/kit-plugin-airdrop` | `airdrop`, `rpcAirdrop` | SOL faucet (typically pulled in transitively) |
216| `@solana/kit-plugin-instruction-plan` | `planAndSendTransactions` | Instruction batching + sending sugar |
217 
218### Program Plugins
219 
220Codama-generated `@solana-program/*` packages also export program plugins that attach fluent APIs to the client:
221 
222```ts
223import { createClient } from '@solana/kit';
224import { solanaLocalRpc } from '@solana/kit-plugin-rpc';
225import { signerFromFile } from '@solana/kit-plugin-signer';
226import { tokenProgram } from '@solana-program/token';
227 
228const client = await createClient()
229  .use(signerFromFile('~/.config/solana/id.json'))
230  .use(solanaLocalRpc())
231  .use(tokenProgram());
232 
233// Fluent API — auto-derives ATAs, defaults payer from client
234await client.token.instructions
235  .transferToATA({ mint, authority: ownerSigner, recipient, amount: 50n, decimals: 2 })
236  .sendTransaction();
237```
238 
239| Package | Plugin | Adds |
240|---------|--------|------|
241| `@solana-program/token` | `tokenProgram()` | `client.token.instructions` (createMint, mintToATA, transferToATA, etc.) |
242 
243### Example Implementations
244 
245| Package | Exports | Purpose | Code Example |
246|---------|---------|---------|--------------|
247| `@solana/kora` | `createKitKoraClient`, `koraPlugin` | Gasless transactions | https://github.com/solana-foundation/kora/blob/main/sdks/ts/src/kit/index.ts |
248 
249---
250 
251## Building Custom Plugins
252 
253See [advanced.md](advanced.md) for the full guide on authoring plugins and assembling domain-specific clients.
254 
255A plugin is a function that takes a client and returns a new one:
256 
257```ts
258type ClientPlugin<TInput extends object, TOutput extends Promise<object> | object> =
259  (input: TInput) => TOutput;
260```
261 
262Quick example:
263 
264```ts
265function myCustomPlugin() {
266  return <T extends object>(client: T) => ({
267    ...client,
268    myMethod: () => console.log('hello'),
269  });
270}
271 
272const client = createClient().use(myCustomPlugin());
273client.myMethod(); // 'hello'
274```
275 
276Plugins can require capabilities from previous plugins:
277 
278```ts
279function myRpcPlugin() {
280  return <T extends { rpc: SolanaRpc }>(client: T) => ({
281    ...client,
282    fetchBalance: (addr: Address) => client.rpc.getBalance(addr).send(),
283  });
284}
285 
286// ✅ Works — rpc installed first
287createClient().use(rpc(url)).use(myRpcPlugin());
288 
289// ❌ Type error — rpc not present
290createClient().use(myRpcPlugin());
291```
292