Helps developers understand when to use @solana/kit vs @solana/web3.js (v1), provides migration guidance, API mappings, and handles edge cases for Solana JavaScript SDK transitions
npxskills add sendaifun/skills--skill solana-kit-migrationLoading…
This skill helps you navigate the transition between @solana/web3.js (v1.x) and @solana/kit (formerly web3.js 2.0), providing guidance on when to use each library and how to migrate between them.
The Solana JavaScript ecosystem has two major SDK options:
| Library | Status | Use Case |
|---|---|---|
@solana/web3.js (1.x) | Maintenance mode | Legacy projects, Anchor-dependent apps |
@solana/kit | Active development | New projects, performance-critical apps |
Key Decision: @solana/kit is the future, but migration isn't always straightforward.
@solana/compat for interoperabilitySTART
│
├─ New project? ─────────────────────────────────────────┐
│ │ │
│ ├─ Using Anchor? ──► YES ──► Use @solana/web3.js │
│ │ │
│ └─ No Anchor? ──► Use @solana/kit │
│ │
└─ Existing project? ────────────────────────────────────┤
│ │
├─ Performance issues? ──► Consider migration │
│ │
├─ Bundle size issues? ──► Consider migration │
│ │
└─ Working fine? ──► Stay with current SDK │
When a user asks about migration, follow these steps:
Run the migration analysis script to detect:
# Use the analyze-migration.sh script in scripts/
./scripts/analyze-migration.sh /path/to/project
Look for these blocking dependencies:
@coral-xyz/anchor or @project-serum/anchor - Wait for Anchor Kit supportCount occurrences of these patterns that need changes:
new Connection(...) → createSolanaRpc(...)Keypair.fromSecretKey(...) → createKeyPairSignerFromBytes(...)new PublicKey(...) → address(...)new Transaction() → createTransactionMessage(...)pipe()Based on findings, recommend:
@solana/compatSee resources/api-mappings.md for complete mappings. Key conversions:
// v1
const connection = new Connection(url, 'confirmed');
const balance = await connection.getBalance(pubkey);
// Kit
const rpc = createSolanaRpc(url);
const { value: balance } = await rpc.getBalance(address).send();
// v1
const keypair = Keypair.fromSecretKey(secretKey);
console.log(keypair.publicKey.toBase58());
// Kit
const signer = await createKeyPairSignerFromBytes(secretKey);
console.log(signer.address);
// v1
const tx = new Transaction().add(
SystemProgram.transfer({
fromPubkey: sender.publicKey,
toPubkey: recipient,
lamports: amount,
})
);
tx.recentBlockhash = blockhash;
tx.feePayer = sender.publicKey;
// Kit
const tx = pipe(
createTransactionMessage({ version: 0 }),
tx => setTransactionMessageFeePayer(sender.address, tx),
tx => setTransactionMessageLifetimeUsingBlockhash(blockhash, tx),
tx => appendTransactionMessageInstruction(
getTransferSolInstruction({
source: sender,
destination: address(recipient),
amount: lamports(BigInt(amount)),
}),
tx
),
);
Kit uses native BigInt everywhere. Watch for:
// WRONG - will fail
const amount = 1000000000;
// CORRECT
const amount = 1_000_000_000n;
// or
const amount = BigInt(1000000000);
// or use helper
const amount = lamports(1_000_000_000n);
Kit may require explicit encoding:
// If you see: "Encoded binary (base 58) data should be less than 128 bytes"
// Add encoding parameter:
await rpc.getAccountInfo(address, { encoding: 'base64' }).send();
Kit keypair creation is async (uses WebCrypto):
// v1 - synchronous
const keypair = Keypair.generate();
// Kit - MUST await
const keypair = await generateKeyPairSigner();
Kit RPC calls require .send():
// v1
const balance = await connection.getBalance(pubkey);
// Kit - don't forget .send()!
const { value: balance } = await rpc.getBalance(address).send();
These are different types and not interchangeable:
// Use @solana/compat for conversion
import { fromLegacyPublicKey, toLegacyPublicKey } from '@solana/compat';
const kitAddress = fromLegacyPublicKey(legacyPublicKey);
const legacyPubkey = toLegacyPublicKey(kitAddress);
Signing flow is different:
// v1
transaction.sign(keypair);
// or
const signed = await connection.sendTransaction(tx, [keypair]);
// Kit - use signer pattern
const signedTx = await signTransactionMessageWithSigners(txMessage);
const signature = await sendAndConfirmTransaction(signedTx);
Anchor generates v1 types. If using Anchor:
// Keep @solana/web3.js for Anchor interactions
import { Connection, PublicKey } from '@solana/web3.js';
import { Program } from '@coral-xyz/anchor';
// Use Kit for non-Anchor parts if needed
// Bridge with @solana/compat
Kit uses AsyncIterators:
// v1
const subscriptionId = connection.onAccountChange(pubkey, callback);
connection.removeAccountChangeListener(subscriptionId);
// Kit - use AbortController
const abortController = new AbortController();
const notifications = await rpcSubscriptions
.accountNotifications(address)
.subscribe({ abortSignal: abortController.signal });
for await (const notification of notifications) {
// handle notification
}
// To unsubscribe:
abortController.abort();
// v1
const versionedTx = new VersionedTransaction(messageV0);
// Kit - transactions are versioned by default
const tx = createTransactionMessage({ version: 0 });
Address Lookup Tables work differently:
// v1
const lookupTable = await connection.getAddressLookupTable(tableAddress);
const messageV0 = new TransactionMessage({...}).compileToV0Message([lookupTable.value]);
// Kit
// Lookup tables are handled in transaction compilation
// See resources/lookup-tables-example.md
If Kit feels too low-level, consider Gill:
import { createSolanaClient, sendSol } from 'gill';
const client = createSolanaClient({ rpcUrl });
await sendSol(client, { from: signer, to: recipient, amount: lamports(1n) });
@solana/compat for gradual migrationssolana-kit-migration/
├── SKILL.md # This file
├── scripts/
│ ├── analyze-migration.sh # Codebase analysis script
│ └── detect-patterns.js # Pattern detection utility
├── resources/
│ ├── api-mappings.md # Complete API reference
│ ├── compatibility-matrix.md # SDK compatibility info
│ └── package-comparison.md # Feature comparison
├── examples/
│ ├── v1-to-kit/ # Migration examples
│ │ ├── basic-transfer.md
│ │ ├── token-operations.md
│ │ └── subscription-handling.md
│ └── mixed-codebase/ # Hybrid approach examples
│ └── anchor-with-kit.md
└── docs/
└── edge-cases.md # Detailed edge cases
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).