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.json

import { 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*Instruction returns 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.

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.

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.json

import { 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*Instruction returns 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.

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.

Codama

Search Documentation

Codama