Codama
Generate @solana/kit 7.0.0 clients from Anchor 0.32.1 IDLs.
Recipe
npm install -D @codama/cli @codama/nodes-from-anchor @codama/renderers-js{
"idl": "target/idl/my_program.json",
"scripts": { "js": "@codama/renderers-js" }
}When to reach for this:
- Any Anchor program needing typed frontend clients.
- Sharing instruction builders across web and API routes.
- Eliminating hand-maintained discriminators.
Working Example
anchor build
npx codama run --config codama.jsonimport { createSolanaRpc } from "@solana/kit";
import { fetchCounter, getIncrementInstruction } from "./generated/clients/js";
const rpc = createSolanaRpc(process.env.RPC_URL!);
const account = await fetchCounter(rpc, counterAddress);
const ix = getIncrementInstruction({ counter: counterAddress, authority: signer });What this demonstrates:
fetch*helpers combine RPC + decoder.get*Instructionreturns kit-native instructions.- Output folder is safe to commit with CI drift checks.
Deep Dive
How It Works
- Codama parses IDL into an AST node graph.
- Renderers emit TypeScript tuned to @solana/kit codecs.
- Works with Anchor IDL; native Shank IDLs supported with compatible schema.
- Update renderer when bumping kit major.
Gotchas
- Forgot anchor build - stale IDL input. Fix: codegen step depends on build artifact.
- Renderer/kit version skew - type errors. Fix: pin compatible versions in docs.
- Manual edits in generated folder - wiped on regen. Fix: extend via wrappers only.
- Missing accounts in builder - simulation fails. Fix: trust generated account metas.
- Checked-in IDL from wrong cluster - wrong program id. Fix: per-environment config.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| anchor-client-gen (legacy) | Old repos | New Codama pipeline |
| Hand-written codecs | Tiny one-off | Production Anchor apps |
FAQs
Anchor 0.32.1 IDL?
Run anchor build; point Codama at target/idl JSON.
Regenerate when?
Every on-chain interface change in CI.
kit typed clients?
Codama renders @solana/kit native functions.
gill required?
Optional sugar atop kit.
Next.js?
Import generated clients in client components for writes.
Testing?
Surfpool + devnet integration tests.
web3.js?
Do not mix with generated kit clients.
Multiple programs?
One Codama config per program or monorepo workspace.
Account fetch?
Use generated decoders with getAccountInfo.
Errors?
Map program error codes from IDL metadata.
Related
- Building Instructions - use builders
- Keeping Clients in Sync - CI workflow
- @solana/kit, Codama & gill - stack
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.