Typed Clients Best Practices
25 practices for IDL-driven, fully typed Solana clients.
-
Treat IDL as API contract: Every account and arg change is a breaking change review (Typed Clients Basics).
-
Regenerate in CI: Fail when
clients/generateddiffers afteranchor build+ Codama. -
Pin Codama renderer with kit 7.0.0: Renderer majors track codec layouts.
-
Never edit generated files: Wrap extensions in hand-written modules.
-
Commit IDL or verifiable build artifact: Support must reproduce client gen.
-
Namespace multi-program outputs: Avoid export name collisions.
-
Use fetch helpers:* Combine RPC + decode to reduce mistakes (Fetching & Decoding Accounts).
-
Simulate instruction batches: Catch constraint errors before wallet modal.
-
Map program errors: Surface IDL error codes in UI copy.
-
bigint for u64: Match on-chain Borsh types in TypeScript.
-
Coordinate deploy + frontend: Ship client updates with program upgrades.
-
Environment-specific program IDs: devnet ≠ mainnet in .env files.
-
Document IDL hash in releases: Changelog entry per interface bump.
-
Prefer Codama over hand codecs: Maintenance cost is lower long-term.
-
gill for bootstrap, kit for edge cases: Understand both layers (gill).
-
Server reads typed: Next.js routes import decoders without wallets.
-
Client writes typed: Wallet signs generated instructions only.
-
Test decode fixtures: Snapshot account bytes in unit tests.
-
Avoid getProgramAccounts on mainnet UI: Use indexer or filtered RPC.
-
Anchor 0.32.1 alignment: IDL from matching anchor-lang crate.
-
No web3.js in generated path: Single Address model via kit.
-
Lazy load large IDLs: Split programs to reduce bundle size.
-
Wrap RPC errors: Translate 429 and timeout for users.
-
Audit CPI accounts in IDL: Clients must include remaining accounts when needed.
-
Educate team on codegen commands: CONTRIBUTING.md lists exact steps.
FAQs
Anchor TS client still?
Maintain legacy; new code uses Codama kit output.
Commit generated?
Yes with CI drift check, or regen only in CI if IDL artifact stored.
Native non-Anchor IDL?
Codama supports compatible IDL JSON schemas.
Related
- Codama - codegen tool
- @solana/kit Best Practices - RPC layer
- Generating TS Clients - workflow
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.