@solana/web3-compat

@solana/web3-compat is the bridge between long-lived @solana/web3.js apps and the newer Kit runtime. Swap the import, keep the surface that your app already knows, and progressively adopt Kit features without rewriting every helper or instruction at once.

Install with Kit peers

$ 
npm install @solana/web3-compat @solana/kit @solana/clientCopy

The compatibility layer re-exports classic Web3 types (Connection, PublicKey, Transaction, etc.) while internally delegating to Kit networking and codecs. Keep your existing RPC endpoints, but benefit from Kit's more predictable blockhash handling and wallet abstractions.

Replace imports (no other code changes)

Most projects can migrate file-by-file by switching the import source. Both named and namespace imports mirror the old package.

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

import { Connection, PublicKey } from "@solana/web3-compat";

CommonJS works too:

const solanaWeb3 = require("@solana/web3-compat");
const connection = new solanaWeb3.Connection("https://api.devnet.solana.com");

Behind the scenes Connection forwards reads and writes through @solana/client, so helpers like sendAndConfirmTransaction, simulateTransaction, and getProgramAccounts benefit from the newer runtime without touching your business logic.

Bridge helpers when you need Kit types

As you adopt Kit directly (maybe in new components using @solana/client or @solana/react-hooks), use the bridge helpers shipped in the compat package to convert between the two ecosystems:

import {
  PublicKey,
  toAddress,
  toPublicKey,
  toWeb3Instruction,
  toKitSigner
} from "@solana/web3-compat";

const legacyKey = new PublicKey("11111111111111111111111111111111");
const kitAddress = toAddress(legacyKey);
const backToWeb3 = toPublicKey(kitAddress);

Mixing runtimes becomes safe: newer hooks can emit Kit instructions, then toWeb3Instruction will wrap them for legacy flows until the whole project moves over.

Progressive migration patterns

• Incremental rollouts: Update one feature folder at a time. When a module no longer needs compat, point it straight at @solana/client/@solana/react-hooks without touching the rest of the tree.
• Shared RPC tuning: Because compat relies on Kit connections, tuning commitment levels, prioritization fees, or RPC URLs flows through a single config object.
• SPL + transaction helpers: Keep legacy transaction builders for now, but reach for client.helpers.transaction.prepare once you're ready. Compat can still submit the same signed payloads.
• Testing: Reuse existing Web3 mocks since the public surface stays identical, yet under test you can stub the Kit client for richer simulations.

What ships in Phase 0

• Connection with getLatestBlockhash, getBalance, getAccountInfo, getProgramAccounts, getSignatureStatuses, sendRawTransaction, confirmTransaction, and simulateTransaction.
• Utilities like LAMPORTS_PER_SOL, sendAndConfirmTransaction, and compileFromCompat.
• SystemProgram.transfer plus all core Web3 primitives (Keypair, Transaction, VersionedTransaction, TransactionInstruction).

Pair this guide with the @solana/client overview and @solana/react-hooks guide when you are ready to start building new UI on top of the same Kit runtime.