solana-kit-migration
Skill12 starsChanged 9 months agoMITView on GitHub
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
In this repository81 other files it gives its agents.
- ab-test-setupSkill
- agent-browserSkill
- analytics-trackingSkill
- brainstormingSkill
- browser-useSkill
- c4-architectureSkill
- code-reconSkill
- competitor-alternativesSkill
- copy-editingSkill
- copywritingSkill
- crafting-effective-readmesSkill
- dflowSkill
- drift-protocolSkill
- email-sequenceSkill
- enterprise-readinessSkill
- epub-translateSkill
- example-skillSkill
- form-croSkill
- free-tool-strategySkill
- git-workflowSkill
- heliusSkill
- hugging-face-cliSkill
- hugging-face-tool-builderSkill
- hugging-face-evaluationSkill
- hugging-face-paper-publisherSkill
- kaminoSkill
- launch-strategySkill
- magicblockSkill
- marketing-ideasSkill
- marketing-psychologySkill
- mermaid-diagramsSkill
- meteoraSkill
- hugging-face-model-trainerSkill
- n8n-code-javascriptSkill
- n8n-code-pythonSkill
- n8n-expression-syntaxSkill
- n8n-mcp-tools-expertSkill
- n8n-node-configurationSkill
- n8n-validation-expertSkill
- n8n-workflow-patternsSkill
- obsidian-vault-managerSkill
- onboarding-croSkill
- openai-knowledgeSkill
- page-croSkill
- paid-adsSkill
- paywall-upgrade-croSkill
- pinocchio-developmentSkill
- popup-croSkill
- pricing-strategySkill
- programmatic-seoSkill
- raydiumSkill
- referral-programSkill
- remotion-best-practicesSkill
- schema-markupSkill
- seo-auditSkill
- signup-flow-croSkill
- skill-boilerplateSkill
- social-contentSkill
- solana-agent-kitSkill
- solana-kitSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 11 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 37
Dependencies require v1: - Check if your SDKs support Kit
- Very specific: line 43
Gradual migration: - Use @solana/compat for interoperability
- Distinctive: line 69
When a user asks about migration, follow these steps:
- Distinctive: line 73
Run the migration analysis script to detect:
- Distinctive: line 86
Look for these blocking dependencies:
- Distinctive: line 102
Full Migration: If no blockers and < 50 migration points
- Very specific: line 103
Gradual Migration: If 50-200 migration points, use @solana/compat
- Distinctive: line 104
Wait: If Anchor-dependent or critical SDKs don't support Kit
- Distinctive: line 105
Hybrid: If only specific modules need Kit performance
- Distinctive: line 296
If Kit feels too low-level, consider Gill:
- Distinctive: line 311
Always check Anchor compatibility before recommending Kit migration
- Distinctive: line 315
Don't migrate stable, working code without clear benefits
- Distinctive: line 316
Test thoroughly - Kit has different error types and behaviors
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Solana Kit Migration Assistant
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.
Overview
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.
When to Use Each Library
Use @solana/kit When:
- Starting a new project without Anchor dependencies
- Bundle size matters - Kit is tree-shakeable (26% smaller bundles)
- Performance is critical - ~200ms faster confirmation latency, 10x faster crypto ops
- Using standard programs (System, Token, Associated Token)
- Building browser applications where bundle size impacts load time
- Type safety is important - Better TypeScript support catches errors at compile time
- Using modern JavaScript - Native BigInt, WebCrypto, AsyncIterators
Use @solana/web3.js (v1.x) When:
- Using Anchor - Anchor doesn't support Kit out of the box yet
- Existing large codebase - Migration cost outweighs benefits
- Dependencies require v1 - Check if your SDKs support Kit
- Rapid prototyping - v1's OOP style may be more familiar
- Documentation/examples - More community resources for v1
Use Both (Hybrid Approach) When:
- Gradual migration - Use
@solana/compatfor interoperability - Mixed dependencies - Some libs require v1, some support Kit
- Feature-by-feature migration - Convert hot paths first
Quick Decision Flowchart
START
│
├─ 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 │Instructions for Migration Analysis
When a user asks about migration, follow these steps:
Step 1: Analyze Current Codebase
Run the migration analysis script to detect:
- Which SDK version is currently used
- Anchor dependencies
- Third-party SDK dependencies
- Usage patterns that need migration
# Use the analyze-migration.sh script in scripts/
./scripts/analyze-migration.sh /path/to/projectStep 2: Check Dependencies
Look for these blocking dependencies:
@coral-xyz/anchoror@project-serum/anchor- Wait for Anchor Kit support- SDKs that haven't migrated (check their package.json)
Step 3: Assess Migration Complexity
Count occurrences of these patterns that need changes:
new Connection(...)→createSolanaRpc(...)Keypair.fromSecretKey(...)→createKeyPairSignerFromBytes(...)new PublicKey(...)→address(...)new Transaction()→createTransactionMessage(...)- Class-based patterns → Functional composition with
pipe()
Step 4: Recommend Strategy
Based on findings, recommend:
- Full Migration: If no blockers and < 50 migration points
- Gradual Migration: If 50-200 migration points, use
@solana/compat - Wait: If Anchor-dependent or critical SDKs don't support Kit
- Hybrid: If only specific modules need Kit performance
API Migration Reference
See resources/api-mappings.md for complete mappings. Key conversions:
Connection → RPC
// 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();Keypair → KeyPairSigner
// v1
const keypair = Keypair.fromSecretKey(secretKey);
console.log(keypair.publicKey.toBase58());
// Kit
const signer = await createKeyPairSignerFromBytes(secretKey);
console.log(signer.address);Transaction Building
// 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
),
);Edge Cases & Gotchas
1. BigInt Conversion
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);2. Base58 Encoding Errors
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();3. Async Keypair Generation
Kit keypair creation is async (uses WebCrypto):
// v1 - synchronous
const keypair = Keypair.generate();
// Kit - MUST await
const keypair = await generateKeyPairSigner();4. RPC Method Chaining
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();5. PublicKey vs Address
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);6. Transaction Signing
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);7. Anchor Incompatibility
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/compat8. Subscription Handling
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();9. VersionedTransaction Migration
// v1
const versionedTx = new VersionedTransaction(messageV0);
// Kit - transactions are versioned by default
const tx = createTransactionMessage({ version: 0 });10. Lookup Tables
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.mdAlternative: Consider Gill
If Kit feels too low-level, consider Gill:
- Built on Kit primitives
- Higher-level abstractions
- Simpler API for common tasks
- Full Kit compatibility
import { createSolanaClient, sendSol } from 'gill';
const client = createSolanaClient({ rpcUrl });
await sendSol(client, { from: signer, to: recipient, amount: lamports(1n) });Guidelines
- Always check Anchor compatibility before recommending Kit migration
- Recommend
@solana/compatfor gradual migrations - Bundle size benefits matter most for browser applications
- Performance benefits matter most for high-throughput backends
- Don't migrate stable, working code without clear benefits
- Test thoroughly - Kit has different error types and behaviors
Files in This Skill
solana-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 casesNotes
- Kit was released as @solana/web3.js@2.0.0 on December 16, 2024
- It was later renamed to @solana/kit to avoid confusion
- The 1.x line is in maintenance mode but still widely used
- Migration tooling is evolving - check for updates regularly
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

