Local Dev Best Practices

A condensed summary of the 25 most important local development practices drawn from every page in this section.

Default to localnet for CI: Run solana-test-validator --reset in pipelines - avoid devnet rate limits (Local Dev Basics).
Pin RPC in Anchor.toml: Provider URL must match active cluster to prevent accidental devnet deploys during anchor test.
Always --reset in CI: Deterministic genesis prevents flaky tests from prior ledger state (solana-test-validator).
Start logs before transactions: Run solana logs in a second terminal prior to sends (Local Logs & Debugging).
Commit fixture files: Version JSON fixtures with documented origin slot (Loading Programs & Fixtures).
Minimize clone sets: Clone only accounts your instruction touches - startup time scales linearly (Cloning Mainnet Accounts).
Use provider RPC for clones: Mainnet fetch during clone needs reliable --url with API key.
Match program IDs everywhere: --bpf-program pubkey must equal declare_id! and client constants.
Layer LiteSVM for speed: Unit test hot paths in LiteSVM 0.6.x; reserve validator for integration.
Use Surfpool for DeFi graphs: When clones explode, switch to Surfpool 0.12.0 fork simulation (Surfpool).
Document cluster choice per PR: Follow Localnet vs Devnet Workflow and record decision.
Fund local wallets generously: Local airdrops are free - test rent-heavy layouts realistically.
Measure CU locally: Read computeUnitsConsumed before setting mainnet compute budgets.
Reduce msg! in production builds: Log noise truncates and wastes CU - feature-gate verbose logs.
Skip-local-validator intentionally: When managing long-running validator, pass anchor test --skip-local-validator consistently.
Kill orphaned validators: Free port 8899 before CI reruns - stale processes cause connection refused.
Separate ledger dirs for experiments: --ledger per feature branch when exploring persistent state.
Sync toolchain pins: Local validator must run Agave 4.1.1 matching deploy artifacts.
Test v0 transactions locally: Include ALTs in local tests when mainnet uses versioned transactions.
Do not rely on devnet for CI gates: Treat devnet as optional smoke, not merge blocker.
Refresh stale clones: Restart validator when mainnet layout changes break CPI tests.
Export failing tx JSON: Attach solana transaction output to issues for reproducibility.
Wallet demos on devnet: Point Phantom at devnet RPC for stakeholder demos - localnet localhost is fragile.
Probe mainnet with dust: Final landing checks need real fees - not replaceable by localnet alone.
Pair local tests with kit clients: Point @solana/kit 7.0.0 integration tests at same RPC URL as CLI.

FAQs

What is the fastest reliable test stack?

LiteSVM unit tests plus anchor test on reset localnet - add Surfpool only for DeFi integration.

Should ledger persist locally?

Only when exploring state manually - CI and PR checks should reset every run.

How do local practices affect mainnet incidents?

Good fixtures and CU measurement prevent "worked locally" landing failures - see tx optimization section.

Local Dev Basics - section entry
solana-test-validator - validator reference
Testing Best Practices - broader test policy
Solana CLI Best Practices - CLI hygiene

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.

Local Dev Best Practices

A condensed summary of the 25 most important local development practices drawn from every page in this section.

Default to localnet for CI: Run solana-test-validator --reset in pipelines - avoid devnet rate limits (Local Dev Basics).

Pin RPC in Anchor.toml: Provider URL must match active cluster to prevent accidental devnet deploys during anchor test.

Always --reset in CI: Deterministic genesis prevents flaky tests from prior ledger state (solana-test-validator).

Start logs before transactions: Run solana logs in a second terminal prior to sends (Local Logs & Debugging).

Commit fixture files: Version JSON fixtures with documented origin slot (Loading Programs & Fixtures).

Minimize clone sets: Clone only accounts your instruction touches - startup time scales linearly (Cloning Mainnet Accounts).

Use provider RPC for clones: Mainnet fetch during clone needs reliable --url with API key.

Match program IDs everywhere: --bpf-program pubkey must equal declare_id! and client constants.

Layer LiteSVM for speed: Unit test hot paths in LiteSVM 0.6.x; reserve validator for integration.

Use Surfpool for DeFi graphs: When clones explode, switch to Surfpool 0.12.0 fork simulation (Surfpool).

Document cluster choice per PR: Follow Localnet vs Devnet Workflow and record decision.

Fund local wallets generously: Local airdrops are free - test rent-heavy layouts realistically.

Measure CU locally: Read computeUnitsConsumed before setting mainnet compute budgets.

Reduce msg! in production builds: Log noise truncates and wastes CU - feature-gate verbose logs.

Skip-local-validator intentionally: When managing long-running validator, pass anchor test --skip-local-validator consistently.

Kill orphaned validators: Free port 8899 before CI reruns - stale processes cause connection refused.

Separate ledger dirs for experiments: --ledger per feature branch when exploring persistent state.

Sync toolchain pins: Local validator must run Agave 4.1.1 matching deploy artifacts.

Test v0 transactions locally: Include ALTs in local tests when mainnet uses versioned transactions.

Do not rely on devnet for CI gates: Treat devnet as optional smoke, not merge blocker.

Refresh stale clones: Restart validator when mainnet layout changes break CPI tests.

Export failing tx JSON: Attach solana transaction output to issues for reproducibility.

Wallet demos on devnet: Point Phantom at devnet RPC for stakeholder demos - localnet localhost is fragile.

Probe mainnet with dust: Final landing checks need real fees - not replaceable by localnet alone.

Pair local tests with kit clients: Point @solana/kit 7.0.0 integration tests at same RPC URL as CLI.

FAQs

What is the fastest reliable test stack?

LiteSVM unit tests plus anchor test on reset localnet - add Surfpool only for DeFi integration.

Should ledger persist locally?

Only when exploring state manually - CI and PR checks should reset every run.

How do local practices affect mainnet incidents?

Good fixtures and CU measurement prevent "worked locally" landing failures - see tx optimization section.

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.

Local Dev Best Practices

FAQs

Related

Search Documentation

Local Dev Best Practices

FAQs

Related