Typed Clients Best Practices
25 practices for IDL-driven, fully typed Solana clients.
//
Search across all documentation pages
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/generated differs after anchor 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.
Maintain legacy; new code uses Codama kit output.
Yes with CI drift check, or regen only in CI if IDL artifact stored.
Codama supports compatible IDL JSON schemas.
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.
Reviewed by Chris St. John·Last updated Jul 19, 2026