Toolchain Best Practices
A condensed summary of the 25 most important toolchain practices drawn from every page in this section.
//
Search across all documentation pages
A condensed summary of the 25 most important toolchain practices drawn from every page in this section.
Pin Agave 4.1.1 everywhere: Use agave-install init 4.1.1 so CLI reports 3.0.10 on laptops and CI (Toolchain Overview).
Commit rust-toolchain.toml: Lock Rust 1.91.1 with rustfmt, clippy, and rust-analyzer components (Editor & rust-analyzer Setup).
Use avm per repo: Run avm use 0.32.1 when entering Anchor workspaces - global Anchor drift breaks IDL builds (Version Management).
Align anchor-lang crate to CLI: anchor-lang = "0.32.1" must match Anchor CLI 0.32.1.
Verify PATH order: which solana should resolve to Agave install, not stale Homebrew binaries.
Document install in README: New hires copy one script block - Agave, avm, rustup, Node for clients.
CI prints versions first: Fail fast when solana --version or anchor --version mismatches manifest pins.
Cache toolchain directories: Key Agave and cargo registry caches on version strings for pipeline speed.
Release builds for deploy: cargo build-sbf --release / anchor build before any devnet or mainnet upload (Building Programs).
Track .so size in CI: Log wc -c target/deploy/*.so to catch binary regressions early.
One scaffold per product: Pick create-solana-dapp, mucho, or manual - avoid mixing templates (create-solana-dapp, Mucho CLI).
Bump @solana/kit explicitly: Client package.json should pin 7.0.0 independently of Agave.
Run solana-verify before mainnet: Publish matching local and on-chain hashes for governance (Verifiable Builds).
Deploy only verify pipeline artifacts: Never upload ad-hoc laptop builds to production program IDs.
Pin Surfpool 0.12.0 for fork dev: Document alongside Agave when teams simulate mainnet state.
Pin LiteSVM 0.6.x in test crates: Fast unit tests stay consistent across machines.
Share .vscode/settings.json: linkedProjects and format-on-save reduce macro confusion.
Open workspace root in IDE: Open folder containing Anchor.toml, not isolated programs/* subcrates only.
Clean target on toolchain upgrades: cargo clean after Agave or Anchor version bumps.
Lock Cargo.lock for programs: Reproducible builds require committed lockfiles in program repos.
Avoid nightly Rust for programs: Stable 1.91.1 matches platform tools expectations.
Separate Node and Rust toolchains: nvm/fnm for frontend; rustup for programs - document both.
Automate doctor checks: Script version gates in pnpm doctor or make check-tools for workshops.
Announce toolchain upgrades: Changelog entry with re-test checklist before team-wide bump.
Keep platform tools bundled: Install Agave bundle holistically - partial copies miss cargo-build-sbf.
Agave 4.1.1, Anchor 0.32.1, Rust 1.91.1, @solana/kit 7.0.0 in respective config files.
Verifiable builds and lockfiles prevent undeclared dependency injection in deployed bytecode.
Docker helps CI; developers still benefit from local Agave for solana logs and deploy iteration.
On security releases or needed features - never auto-float latest in production pipelines.
Proc-macro / anchor-lang skew and platform tools PATH - run full anchor test after every bump.
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