Scaffolding, test-harness and CI toolkit for Soroban smart contracts on Stellar — think create-react-app for Soroban development.
soroban-forge wraps and complements the official stellar-cli; it never reimplements it. Building and deploying always go through stellar contract build / stellar contract deploy — forge gets you to that point faster:
soroban-forge new— start from a working, tested contract templatesoroban-forge test-init— generate fixtures, a smoke test and a snapshot helper for an existing contractsoroban-forge ci-init— add GitHub Actions workflows (build+test, contract-size check, optional testnet deploy)soroban-forge doctor— verify your toolchain and get fix instructionssoroban-forge bindings ts— generate a TypeScript client package from a built contractsoroban-forge verify <contract-id>— check that a deployed contract matches your local build
You need Rust ≥ 1.84 (rustup) and git. The two remaining
pieces — the wasm32v1-none target and stellar-cli — are what doctor --fix
installs in step 2.
# 1. install soroban-forge (from source, v0.1)
git clone https://github.com/soroban-forge-labs/soroban-forge
cd soroban-forge && cargo install --path . && cd ..
# 2. install anything missing from your toolchain, then re-check
# (--fix prompts before running each install; drop it to only report)
soroban-forge doctor --fix
# 3. create a project (`soroban-forge templates` lists all six)
soroban-forge new my-token --template token
cd my-token
# 4. build the deployable wasm -> target/wasm32v1-none/release/my_token.wasm
stellar contract build
# 5. run the tests — the template passes them out of the box
cargo testStep 5 should end in test result: ok. 6 passed; 0 failed. From here,
soroban-forge test-init --force adds a generated test harness with fixtures
and a snapshot helper, and soroban-forge ci-init --deploy writes GitHub
Actions workflows for build+test, contract size and manual testnet deploys.
New to Soroban entirely? Follow the full walkthrough: docs/tutorial-zero-to-testnet.md.
Hitting an error? Check the troubleshooting / FAQ page first.
| command | what it does |
|---|---|
new <name> --template <t> |
scaffold a project (--list-templates to see options) |
templates |
list the bundled templates with a one-line description |
test-init |
generate tests/ fixtures + smoke test for a contract |
ci-init --provider github |
write CI workflows; --deploy adds manual testnet deploy |
doctor |
check rustc/cargo, wasm32v1-none target, stellar-cli |
bindings ts |
generate a TypeScript client package from a built contract wasm |
verify <contract-id> |
compare a deployed contract's wasm hash with the local release build (exit 1 on mismatch) |
All commands read an optional forge.toml in the
project directory (name, authors, default template) — generated projects get
one automatically.
Five modules, five owners, minimal merge conflicts. Each module is a crate
with its own README, tests and a small public surface; they meet only at the
ForgePlugin trait defined in core:
| module | crate | subcommand |
|---|---|---|
| 1 — CLI core & framework | crates/core |
(routing, config, errors) |
| 2 — Scaffolding & templates | crates/scaffold + templates/ |
new |
| 3 — Test harness generator | crates/testgen |
test-init |
| 4 — CI/CD presets | crates/ci-presets + presets/ |
ci-init |
| 5 — Docs & DX | crates/doctor + docs/ + examples/ |
doctor |
| 6 — TypeScript bindings | crates/bindings-ts |
bindings ts |
| 7 — Deployment verification | crates/verify |
verify |
Note: See
examples/README.mdfor instructions on regenerating the checked-in example projects.
See CONTRIBUTING.md for the ownership map and how to pick up an issue — ISSUES.md lists well-scoped starter work.
- Rust ≥ 1.84 with the
wasm32v1-nonetarget - stellar-cli for building/deploying contracts
- Generated contracts use soroban-sdk 26.x
soroban-forge doctor checks all of this for you.
soroban-forge uses a small set of stable exit codes (0 success, 1
user error, 2 missing tool, 3 internal error) so CI/scripts can branch
on outcome — see docs/exit-codes.md.
See CHANGELOG.md for a full history of notable changes and release notes.