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 {
124  rpcAirdrop,
125  solanaRpcConnection,
126  solanaRpcSubscriptionsConnection,
127} from '@solana/kit-plugin-rpc';
128import { generatedSignerWithSol } from '@solana/kit-plugin-signer';
129 
130// Airdrop function must exist before generatedSignerWithSol
131const client = await createClient()
132  .use(solanaRpcConnection('http://127.0.0.1:8899'))
133  .use(solanaRpcSubscriptionsConnection('ws://127.0.0.1:8900'))
134  .use(rpcAirdrop())
135  .use(generatedSignerWithSol(lamports(10_000_000_000n)));
136```
137 
138**Role-split example** (different keypairs for fees vs. authority):
139 
140```ts
141import { createClient } from '@solana/kit';
142import { solanaDevnetRpc } from '@solana/kit-plugin-rpc';
143import { payer, identity } from '@solana/kit-plugin-signer';
144 
145const client = createClient()
146  .use(payer(feePayerSigner))      // pays fees
147  .use(identity(walletSigner))     // owns/authorizes accounts
148  .use(solanaDevnetRpc());
149```
150 
151---
152 
153## Custom Client Composition
154 
155When the all-in-one bundles don't fit (custom transaction planner, partial capabilities, third-party services), build the client out of low-level plugins:
156 
157```ts
158import { createClient } from '@solana/kit';
159import {
160  rpc,
161  rpcAirdrop,
162  rpcGetMinimumBalance,
163  rpcTransactionPlanner,
164  rpcTransactionPlanExecutor,
165} from '@solana/kit-plugin-rpc';
166import { signerFromFile } from '@solana/kit-plugin-signer';
167import { planAndSendTransactions } from '@solana/kit-plugin-instruction-plan';
168 
169const client = await createClient()
170  .use(rpc('https://api.devnet.solana.com'))    // adds client.rpc + client.rpcSubscriptions
171  .use(signerFromFile('path/to/keypair.json'))  // adds client.payer + client.identity
172  .use(rpcAirdrop())                             // adds client.airdrop
173  .use(rpcGetMinimumBalance())                   // adds client.getMinimumBalance
174  .use(rpcTransactionPlanner())                  // adds client.transactionPlanner
175  .use(rpcTransactionPlanExecutor())             // adds client.transactionPlanExecutor
176  .use(planAndSendTransactions());               // adds client.sendTransaction(s)
177```
178 
179### Plugin Ordering
180 
181Plugins that depend on others must come after their dependencies. TypeScript enforces this:
182 
183```ts
184// ✅ Correct — signer + rpc before planner/executor
185createClient()
186  .use(signer(mySigner))
187  .use(rpc(url))
188  .use(rpcTransactionPlanner())
189  .use(planAndSendTransactions());
190 
191// ❌ Type error — solanaRpc requires payer
192createClient()
193  .use(solanaRpc({ rpcUrl: url }))
194  .use(signer(mySigner));
195```
196 
197### Async Plugins
198 
199Some plugins are async (e.g., `signerFromFile`, `generatedSigner`, `generatedSignerWithSol`). The `.use()` method handles awaiting automatically — `await` the final client:
200 
201```ts
202const client = await createClient()
203  .use(signerFromFile('./keypair.json'))        // async
204  .use(solanaLocalRpc());
205```
206 
207---
208 
209## Plugin Catalog
210 
211### Official Plugins
212 
213| Package | Plugins | Purpose |
214|---------|---------|---------|
215| `@solana/kit-plugin-rpc` | `solanaRpc`, `solanaMainnetRpc`, `solanaDevnetRpc`, `solanaLocalRpc`, `rpc`, `solanaRpcConnection`, `rpcAirdrop`, `rpcGetMinimumBalance`, `rpcTransactionPlanner`, `rpcTransactionPlanExecutor` | RPC connectivity + tx planning/execution |
216| `@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 |
217| `@solana/kit-plugin-litesvm` | `litesvm`, `litesvmConnection`, `litesvmAirdrop`, `litesvmTransactionPlanner`, `litesvmTransactionPlanExecutor` | In-memory test environment |
218| `@solana/kit-plugin-airdrop` | `airdrop`, `rpcAirdrop` | SOL faucet (typically pulled in transitively) |
219| `@solana/kit-plugin-instruction-plan` | `planAndSendTransactions` | Instruction batching + sending sugar |
220 
221### Program Plugins
222 
223Codama-generated `@solana-program/*` packages also export program plugins that attach fluent APIs to the client:
224 
225```ts
226import { createClient } from '@solana/kit';
227import { solanaLocalRpc } from '@solana/kit-plugin-rpc';
228import { signerFromFile } from '@solana/kit-plugin-signer';
229import { tokenProgram } from '@solana-program/token';
230 
231const client = await createClient()
232  .use(signerFromFile('~/.config/solana/id.json'))
233  .use(solanaLocalRpc())
234  .use(tokenProgram());
235 
236// Fluent API — auto-derives ATAs, defaults payer from client
237await client.token.instructions
238  .transferToATA({ mint, authority: ownerSigner, recipient, amount: 50n, decimals: 2 })
239  .sendTransaction();
240```
241 
242| Package | Plugin | Adds |
243|---------|--------|------|
244| `@solana-program/token` | `tokenProgram()` | `client.token.instructions` (createMint, mintToATA, transferToATA, etc.) |
245 
246### Example Implementations
247 
248| Package | Exports | Purpose | Code Example |
249|---------|---------|---------|--------------|
250| `@solana/kora` | `createKitKoraClient`, `koraPlugin` | Gasless transactions | https://github.com/solana-foundation/kora/blob/main/sdks/ts/src/kit/index.ts |
251 
252---
253 
254## Building Custom Plugins
255 
256See [advanced.md](advanced.md) for the full guide on authoring plugins and assembling domain-specific clients.
257 
258A plugin is a function that takes a client and returns a new one:
259 
260```ts
261type ClientPlugin<TInput extends object, TOutput extends Promise<object> | object> =
262  (input: TInput) => TOutput;
263```
264 
265Quick example:
266 
267```ts
268function myCustomPlugin() {
269  return <T extends object>(client: T) => ({
270    ...client,
271    myMethod: () => console.log('hello'),
272  });
273}
274 
275const client = createClient().use(myCustomPlugin());
276client.myMethod(); // 'hello'
277```
278 
279Plugins can require capabilities from previous plugins:
280 
281```ts
282function myRpcPlugin() {
283  return <T extends { rpc: SolanaRpc }>(client: T) => ({
284    ...client,
285    fetchBalance: (addr: Address) => client.rpc.getBalance(addr).send(),
286  });
287}
288 
289// ✅ Works — rpc installed first
290createClient().use(rpc(url)).use(myRpcPlugin());
291 
292// ❌ Type error — rpc not present
293createClient().use(myRpcPlugin());
294```
295