Solana KitShift

Automate the first safe step from deprecated @solana/web3.js toward the modern Solana Kit ecosystem.

Solana KitShift is a production-grade codemod built with the Codemod toolkit and jssg. It performs deterministic compatibility migrations using @solana/web3-compat, updates dependencies, avoids unsafe rewrites, and generates AI instructions for edge cases.

Why This Matters

@solana/web3.js is deprecated. The modern Solana ecosystem has moved to @solana/kit (formerly @solana/web3.js v2). But a full migration is risky — signer logic, transaction construction, instruction handling, and RPC behavior all need careful review.

@solana/web3-compat provides a safe bridge: it re-exports the classic web3.js surface while internally delegating to the Kit runtime. Most projects can migrate file-by-file by switching the import source.

Solana KitShift automates that switch — safely and deterministically.

What Is Automated

• Detecting @solana/web3.js named imports
• Replacing safe imports with @solana/web3-compat equivalents
• Merging into existing @solana/web3-compat import statements (no duplicates)
• Adding bridge helper imports (toAddress, toWeb3Instruction) when usage is detected
• Adding @solana/web3-compat to package.json
• Inserting TODO(Solana KitShift) comments for patterns that need review
• Generating solana-kitshift-report.md
• Generating AI_MIGRATION_INSTRUCTIONS.md

What Is Intentionally NOT Automated

• Namespace imports (import * as web3 from "@solana/web3.js") — too risky
• Unknown or unverified symbols — skipped and reported
• Signer / Keypair rewriting — semantics must be verified manually
• Transaction construction rewriting — too many variants
• Removing @solana/web3.js from package.json — only safe after full migration
• Any change where the replacement is not semantically equivalent

Install

npm install

Or install the Codemod CLI globally:

npm install -g codemod

Run

Option A — Codemod workflow (recommended)

npx codemod workflow run -w . -t /path/to/your/solana/project

Option B — Node.js runner

node src/run.js /path/to/your/solana/project

Option C — jssg test runner (for development)

npx codemod jssg test -l tsx ./scripts/codemod.ts
npx codemod jssg test -l ts ./scripts/codemod.ts

Before / After Example

Before:

import {
  PublicKey,
  Transaction,
  Connection,
  MessageV0,
} from "@solana/web3.js";

const connection = new Connection("https://api.mainnet-beta.solana.com");
const key = new PublicKey("11111111111111111111111111111111");

After:

import { MessageV0 } from "@solana/web3.js";
import { PublicKey, Transaction, Connection } from "@solana/web3-compat";

const connection = /* TODO(Solana KitShift): Connection now uses Kit runtime internally.
  Verify RPC endpoint, commitment level, and subscription behavior. */
  new Connection("https://api.mainnet-beta.solana.com");
const key = new PublicKey("11111111111111111111111111111111");

What happened:

• PublicKey, Transaction, Connection → moved to @solana/web3-compat
• MessageV0 → left in @solana/web3.js (not yet covered by compat)
• Connection constructor → got a TODO comment for manual review

Reading the Migration Report

After running, check solana-kitshift-report.md in your project root. It shows:

• Files scanned and changed
• Imports migrated
• Bridge helpers added
• Unsafe patterns skipped (with details)
• A manual review checklist
• Estimated automation coverage
• Next steps

AI / Manual Review

AI_MIGRATION_INSTRUCTIONS.md contains detailed instructions for an AI assistant (or a developer) to handle the remaining edge cases:

• PublicKey / Address conversions
• TransactionInstruction → Kit IInstruction
• Signer and Keypair behavior
• Connection and RPC behavior
• Transaction sending and confirmation
• TypeScript type errors after migration

Safe Symbols (v1)

These symbols are migrated automatically:

| Symbol | Notes | |--------|-------| | PublicKey | Safe — identical surface | | Transaction | Safe — compat re-exports | | VersionedTransaction | Safe — compat re-exports | | TransactionInstruction | Safe — compat re-exports | | Connection | Safe — but gets a TODO comment (RPC behavior differs internally) | | Keypair | Safe — compat re-exports | | SystemProgram | Safe — compat re-exports | | LAMPORTS_PER_SOL | Safe — constant | | sendAndConfirmTransaction | Safe — but gets a TODO comment | | sendRawTransaction | Safe — compat re-exports |

Known Limitations

• Namespace imports (import * as web3) are not migrated
• CJS require() style is detected but not migrated in v1
• Symbols not in the safe list are skipped (conservative by design)
• @solana/web3-compat coverage is still expanding — check the official docs
• The codemod does not verify that your project builds after migration — run tsc --noEmit yourself

Roadmap

• v1.1: CJS require() support
• v1.2: Deeper bridge helper insertion (auto-insert toAddress() at call sites)
• v2.0: Full @solana/kit migration support (signer, transaction, instruction rewriting)
• v2.1: Multi-file semantic analysis (track PublicKey usage across files)

Hackathon Submission

This project was built for the Codemod Hackathon.

Positioning: Solana KitShift automates the first safe step from deprecated @solana/web3.js toward the modern Solana Kit ecosystem. Instead of attempting a risky full rewrite, it performs deterministic compatibility migrations, inserts bridge helpers only where safe, updates dependencies, and produces AI instructions for the remaining edge cases. This allows real Solana teams to reduce manual upgrade work while keeping migration risk low.

Built with: Codemod toolkit + jssg + @jssg/utils