---

name: foundry-project description: Set up and configure Foundry projects. Use when initializing new projects, configuring foundry.toml, managing dependencies, or structuring Solidity codebases.

Foundry Project Setup

Initialize, configure, and manage Foundry projects.

When to Use

• Creating new Foundry projects
• Configuring foundry.toml settings
• Managing dependencies (forge-std, OpenZeppelin, etc.)
• Setting up remappings
• Optimizing build and test settings

Quick Start

New Project

Copy# Create new project
forge init my-project
cd my-project

# Create from template
forge init my-project --template https://github.com/foundry-rs/forge-template

Existing Project

Copy# Initialize in existing directory
forge init --force

# Clone and build
git clone https://github.com/some/project
cd project
forge build

Project Structure

Copymy-project/
├── foundry.toml          # Configuration
├── .env                  # Environment variables (gitignored)
├── .gitignore
├── README.md
├── lib/                  # Dependencies
│   └── forge-std/        # Standard library
├── script/               # Deployment scripts
│   └── Deploy.s.sol
├── src/                  # Source contracts
│   └── MyContract.sol
└── test/                 # Tests
    └── MyContract.t.sol

foundry.toml Configuration

See config.md for all options.

Basic Configuration

Copy[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc = "0.8.24"
optimizer = true
optimizer_runs = 200

[profile.default.fuzz]
runs = 256

[profile.default.invariant]
runs = 256
depth = 15

With RPC Endpoints

Copy[rpc_endpoints]
mainnet = "${MAINNET_RPC_URL}"
sepolia = "${SEPOLIA_RPC_URL}"
arbitrum = "${ARBITRUM_RPC_URL}"

[etherscan]
mainnet = { key = "${ETHERSCAN_API_KEY}" }
sepolia = { key = "${ETHERSCAN_API_KEY}" }
arbitrum = { key = "${ARBISCAN_API_KEY}" }

With Remappings

Copy[profile.default]
remappings = [
    "@openzeppelin/=lib/openzeppelin-contracts/",
    "@uniswap/=lib/v3-periphery/contracts/",
    "solmate/=lib/solmate/src/"
]

Dependency Management

Install Dependencies

Copy# Install forge-std (usually included by default)
forge install foundry-rs/forge-std

# Install OpenZeppelin
forge install OpenZeppelin/openzeppelin-contracts

# Install specific version
forge install OpenZeppelin/openzeppelin-contracts@v4.9.0

# Install without commit
forge install OpenZeppelin/openzeppelin-contracts --no-commit

Update Dependencies

Copy# Update all
forge update

# Update specific
forge update lib/openzeppelin-contracts

Remove Dependencies

Copyforge remove openzeppelin-contracts

Common Dependencies

Copy# OpenZeppelin contracts
forge install OpenZeppelin/openzeppelin-contracts

# OpenZeppelin upgradeable
forge install OpenZeppelin/openzeppelin-contracts-upgradeable

# Solmate (gas-optimized)
forge install transmissions11/solmate

# Solady (ultra-optimized)
forge install Vectorized/solady

# PRB Math (fixed-point math)
forge install PaulRBerg/prb-math

# Uniswap V3
forge install Uniswap/v3-core
forge install Uniswap/v3-periphery

Remappings

Auto-generate

Copy# Generate remappings from lib/
forge remappings > remappings.txt

Manual remappings.txt

Copyforge-std/=lib/forge-std/src/
@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/
@openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts/
solmate/=lib/solmate/src/

In foundry.toml

Copy[profile.default]
remappings = [
    "forge-std/=lib/forge-std/src/",
    "@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/"
]

Build Commands

Copy# Build all contracts
forge build

# Build with sizes
forge build --sizes

# Clean and rebuild
forge clean && forge build

# Build specific contract
forge build --contracts src/MyContract.sol

Profile Management

Multiple Profiles

Copy[profile.default]
optimizer = true
optimizer_runs = 200

[profile.ci]
optimizer = true
optimizer_runs = 200
fuzz = { runs = 1000 }

[profile.lite]
optimizer = false

[profile.production]
optimizer = true
optimizer_runs = 10000
via_ir = true

Using Profiles

Copy# Use CI profile
FOUNDRY_PROFILE=ci forge test

# Use production profile for deployment
FOUNDRY_PROFILE=production forge script script/Deploy.s.sol --broadcast

Environment Variables

.env File

Copy# .env
MAINNET_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your-key
SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/your-key
ETHERSCAN_API_KEY=your-etherscan-key
PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

Loading .env

Copy# Load before commands
source .env && forge script script/Deploy.s.sol

# Or use dotenv in scripts
export $(cat .env | xargs) && forge test

In Scripts

Copycontract DeployScript is Script {
    function run() public {
        uint256 deployerKey = vm.envUint("PRIVATE_KEY");
        address owner = vm.envAddress("OWNER_ADDRESS");
        string memory rpcUrl = vm.envString("RPC_URL");

        vm.startBroadcast(deployerKey);
        // ...
    }
}

Common Tasks

Run Tests

Copyforge test                    # All tests
forge test -vvv               # With traces
forge test --match-test test_Deposit  # Specific test
forge test --watch            # Watch mode
forge test --gas-report       # Gas report

Run Scripts

Copyforge script script/Deploy.s.sol              # Dry run
forge script script/Deploy.s.sol --broadcast  # Execute
forge script script/Deploy.s.sol --verify     # Verify contracts

Generate Documentation

Copyforge doc                     # Generate docs
forge doc --serve             # Serve locally
forge doc --out docs          # Output to docs/

Check Code

Copyforge fmt                     # Format code
forge fmt --check             # Check formatting
forge snapshot                # Gas snapshot
forge snapshot --diff         # Compare with previous

.gitignore

Copy# Foundry
/out
/cache
/broadcast

# Environment
.env
.env.*
!.env.example

# Dependencies (if not using git submodules)
# /lib

# Coverage
lcov.info
coverage/

Best Practices

1. Pin Solidity version in foundry.toml
2. Use remappings for cleaner imports
3. Separate profiles for CI, development, production
4. Never commit .env files with real keys
5. Use forge-std Test contract for all tests
6. Organize tests by contract (MyContract.t.sol)
7. Document with NatSpec comments