Development Environment Setup

This chapter provides detailed instructions for setting up a complete Solana development environment. We'll configure everything you need for both client-side development and on-chain program development.

Overview

A complete Solana development setup includes:

Component	Purpose
Node.js + Bun	JavaScript/TypeScript runtime and package manager
Rust + Cargo	On-chain program development
Solana CLI	Blockchain interaction and local validator
Anchor	Program development framework
IDE Setup	Code editor with proper extensions

Detailed Installation Guide

macOS Setup

macOS is the most straightforward platform for Solana development.

Install Homebrew (if not installed)

Bash

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Dependencies

Bash

# Install build tools
xcode-select --install

# Install required packages
brew install openssl pkg-config libudev-zero

Install Rust

Bash

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

# Verify
rustc --version
cargo --version

Install Solana CLI

Bash

sh -c "$(curl -sSfL https://release.solana.com/v1.18.0/install)"

# Add to your shell profile (~/.zshrc or ~/.bashrc)
echo 'export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify
solana --version

Linux Setup (Ubuntu/Debian)

Install System Dependencies

Bash

sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev libudev-dev

Install Rust

Bash

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

Install Solana CLI

Bash

sh -c "$(curl -sSfL https://release.solana.com/v1.18.0/install)"

# Add to your shell profile
echo 'export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows Setup (WSL 2)

Windows users should use WSL 2 (Windows Subsystem for Linux).

Enable WSL 2

PowerShell

# Run in PowerShell as Administrator
wsl --install
wsl --set-default-version 2

Install Ubuntu

PowerShell

wsl --install -d Ubuntu

Configure Ubuntu

After Ubuntu installs and you create a user, follow the Linux setup instructions above.

Node.js and Bun Setup

Install Node.js via nvm

Bash

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Restart terminal or run:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Install Node.js LTS
nvm install --lts
nvm use --lts

# Verify
node --version  # v20.x.x or later
npm --version

Install Bun

Bash

curl -fsSL https://bun.sh/install | bash

# Restart terminal or run:
source ~/.bashrc  # or ~/.zshrc

# Verify
bun --version

Anchor Framework Setup

Anchor is the standard framework for Solana program development.

Install Anchor Version Manager (avm)

Bash

cargo install --git https://github.com/coral-xyz/anchor avm --force

# Install latest Anchor version
avm install latest
avm use latest

# Verify
anchor --version

Troubleshooting Anchor Installation

If you encounter issues:

Bash

# Ensure you have the required Rust components
rustup component add rustfmt clippy

# For "linking with cc failed" errors on Linux:
sudo apt install build-essential

# For macOS, ensure Xcode tools are installed:
xcode-select --install

Solana CLI Configuration

Configure for Development

Bash

# Set to devnet (test network)
solana config set --url devnet

# Create a new keypair for development
solana-keygen new --outfile ~/.config/solana/devnet.json

# Set as default keypair
solana config set --keypair ~/.config/solana/devnet.json

# View your configuration
solana config get

Understanding Networks

Network	URL	Purpose
Mainnet	https://api.mainnet-beta.solana.com	Production
Devnet	https://api.devnet.solana.com	Development & testing
Testnet	https://api.testnet.solana.com	Validator testing
Localnet	http://localhost:8899	Local development

Get Devnet SOL

Bash

# Request airdrop (up to 2 SOL per request)
solana airdrop 2

# Check balance
solana balance

# If airdrop fails, use the faucet:
# https://faucet.solana.com/

Local Validator Setup

For faster development, run a local Solana validator:

Bash

# Start local validator
solana-test-validator

# In a new terminal, switch to localnet
solana config set --url localhost

# Airdrop works instantly on localnet
solana airdrop 100

Validator Options

Bash

# Start with a clean slate
solana-test-validator --reset

# Clone accounts from devnet
solana-test-validator --clone <ACCOUNT_ADDRESS> --url devnet

# Start with specific programs
solana-test-validator --bpf-program <PROGRAM_ID> <PROGRAM.so>

VS Code Setup

Install VS Code Extensions

Bash

# Install essential extensions
code --install-extension rust-lang.rust-analyzer
code --install-extension tamasfe.even-better-toml
code --install-extension serayuzgur.crates
code --install-extension vadimcn.vscode-lldb
code --install-extension esbenp.prettier-vscode

Configure rust-analyzer

Create .vscode/settings.json in your project:

JSON

{
  "rust-analyzer.linkedProjects": ["programs/*/Cargo.toml"],
  "rust-analyzer.diagnostics.disabled": ["unresolved-proc-macro"],
  "rust-analyzer.cargo.features": "all",
  "editor.formatOnSave": true,
  "[rust]": {
    "editor.defaultFormatter": "rust-lang.rust-analyzer"
  }
}

Project Templates

Create a New Anchor Project

Bash

# Create new Anchor project
anchor init my-solana-project
cd my-solana-project

# Project structure:
# my-solana-project/
# ├── Anchor.toml        # Project configuration
# ├── Cargo.toml         # Rust workspace config
# ├── programs/          # On-chain programs
# │   └── my-solana-project/
# │       ├── Cargo.toml
# │       └── src/
# │           └── lib.rs
# ├── tests/             # Integration tests
# │   └── my-solana-project.ts
# ├── app/               # Frontend (optional)
# └── migrations/        # Deployment scripts

Create a Client-Only Project

Bash

mkdir solana-client-project
cd solana-client-project
bun init -y

# Install Solana packages
bun add @solana/web3.js @solana/spl-token
bun add -d typescript @types/node

# Create tsconfig.json
cat > tsconfig.json << 'EOF'
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}
EOF

mkdir src

Environment Verification Script

Create and run this script to verify your setup:

Bash

#!/bin/bash
# save as verify-setup.sh

echo "=== Solana Development Environment Check ==="
echo ""

# Check Node.js
if command -v node &> /dev/null; then
    echo "✅ Node.js: $(node --version)"
else
    echo "❌ Node.js: Not installed"
fi

# Check Bun
if command -v bun &> /dev/null; then
    echo "✅ Bun: $(bun --version)"
else
    echo "❌ Bun: Not installed"
fi

# Check Rust
if command -v rustc &> /dev/null; then
    echo "✅ Rust: $(rustc --version | cut -d' ' -f2)"
else
    echo "❌ Rust: Not installed"
fi

# Check Cargo
if command -v cargo &> /dev/null; then
    echo "✅ Cargo: $(cargo --version | cut -d' ' -f2)"
else
    echo "❌ Cargo: Not installed"
fi

# Check Solana CLI
if command -v solana &> /dev/null; then
    echo "✅ Solana CLI: $(solana --version | cut -d' ' -f2)"
else
    echo "❌ Solana CLI: Not installed"
fi

# Check Anchor
if command -v anchor &> /dev/null; then
    echo "✅ Anchor: $(anchor --version | cut -d' ' -f2)"
else
    echo "❌ Anchor: Not installed"
fi

echo ""
echo "=== Solana Configuration ==="
solana config get
echo ""
echo "=== Wallet Address ==="
solana address
echo ""
echo "=== Balance ==="
solana balance

Common Issues and Solutions

"Error: insufficient funds for rent"

Your account doesn't have enough SOL:

Bash

solana airdrop 2  # On devnet

"Error: Transaction simulation failed"

Usually a program error. Check:

Correct account permissions
Sufficient lamports
Valid account data

"rust-analyzer not working"

Bash

# Update rust-analyzer
rustup component add rust-analyzer

# In VS Code, reload window
# Cmd/Ctrl + Shift + P -> "Developer: Reload Window"

"Anchor build fails"

Bash

# Clear build cache
anchor clean
rm -rf target/

# Rebuild
anchor build

Next Steps

Your development environment is ready! You can now:

Continue with the handbook from Blockchain History
Jump to Your First Solana Transaction for hands-on coding
Start with Anchor Framework if you want to build programs

Choose your path based on your goals and experience level.