Soldeer

Soldeer is a Solidity-native package manager that provides an alternative to git submodules. It offers versioned dependencies, a package registry, and simpler dependency management.

Installation

Soldeer comes bundled with Foundry. Initialize it in your project:

$ forge soldeer init

This creates a soldeer.toml configuration file.

Installing packages

$ forge soldeer install @openzeppelin-contracts~5.0.0

Packages are stored in dependencies/ by default.

Configuration

Configure Soldeer in soldeer.toml:

[soldeer]
remappings_generate = true
remappings_regenerate = false
remappings_version = true
remappings_prefix = "@"
remappings_location = "config"
 
[dependencies]
"@openzeppelin-contracts" = "5.0.0"
"@solmate" = "6.7.0"

Key options:

Using packages

Import installed packages:

import {ERC20} from "@openzeppelin-contracts/contracts/token/ERC20/ERC20.sol";

When remappings_location = "config", remappings are added to foundry.toml. Otherwise, they go to remappings.txt.

Updating packages

$ forge soldeer update

Publishing packages

Publish your own packages to the Soldeer registry:

$ forge soldeer login

[package]
name = "my-library"
version = "1.0.0"
description = "My awesome Solidity library"

$ forge soldeer push my-library~1.0.0

Git submodules vs Soldeer

Use git submodules when:

• You need a specific commit
• The library isn't on the Soldeer registry
• Your team is familiar with git submodules

Use Soldeer when:

• You want semantic versioning
• You need reproducible builds (lock file)
• You prefer npm-style dependency management

Migrating from git submodules

Convert existing submodule dependencies to Soldeer:

# Remove the submodule
$ forge remove openzeppelin-contracts
 
# Install via Soldeer
$ forge soldeer install @openzeppelin-contracts~5.0.0

Update your imports to use the new remapping prefix:

import {ERC20} from "openzeppelin-contracts/contracts/token/ERC20/ERC20.sol";