1---
2title: Kit ↔ web3.js Interop
3description: Patterns for bridging @solana/kit and legacy @solana/web3.js at adapter boundaries while migrating incrementally.
4---
5 
6# Kit ↔ web3.js Interop (boundary patterns)
7 
8## The rule
9- New code: Kit types and Kit-first APIs.
10- Legacy dependencies: isolate web3.js-shaped types behind an adapter boundary.
11 
12## Preferred bridge: @solana/web3-compat
13Use `@solana/web3-compat` when:
14- A dependency expects `PublicKey`, `Keypair`, `Transaction`, `VersionedTransaction`, `Connection`, etc.
15- You are migrating an existing web3.js codebase incrementally.
16 
17### Why this approach works
18- web3-compat re-exports web3.js-like types and delegates to Kit where possible.
19- It includes helper conversions to move between web3.js and Kit representations.
20 
21## Practical boundary layout
22Keep these modules separate:
23 
24- `src/solana/kit/`:
25  - all Kit-first code: addresses, instruction builders, tx assembly, typed codecs, generated clients
26 
27- `src/solana/web3/`:
28  - adapters for legacy libs (Anchor TS client, older SDKs)
29  - conversions between `PublicKey` and Kit `Address`
30  - conversions between web3 `TransactionInstruction` and Kit instruction shapes (only at edges)
31 
32## Conversion helpers (examples)
33Use web3-compat helpers such as:
34- `toAddress(...)`
35- `toPublicKey(...)`
36- `toWeb3Instruction(...)`
37- `toKitSigner(...)`
38 
39## When you still need @solana/web3.js
40Some methods outside web3-compat's compatibility surface may fall back to a legacy web3.js implementation.
41If that happens:
42- keep `@solana/web3.js` as an explicit dependency
43- isolate fallback usage to adapter modules only
44- avoid letting `PublicKey` bleed into your core domain types
45 
46## Common mistakes to prevent
47- Mixing `Address` and `PublicKey` throughout the app (causes type drift and confusion)
48- Building transactions in one stack and signing in another without explicit conversion
49- Passing web3.js `Connection` into Kit-native code (or vice versa) rather than using a single source of truth
50 
51## Decision checklist
52If you're about to add web3.js:
531) Is there a Kit-native equivalent? Prefer Kit.
542) Is the only reason a dependency? Use web3-compat at the boundary.
553) Can you generate a Kit-native client (Codama) instead? Prefer codegen.
56