Local Dev Best Practices
A condensed summary of the 25 most important local development practices drawn from every page in this section.
//
Search across all documentation pages
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.
LiteSVM unit tests plus anchor test on reset localnet - add Surfpool only for DeFi integration.
Only when exploring state manually - CI and PR checks should reset every run.
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.
Reviewed by Chris St. John·Last updated Jul 16, 2026