Quickstart

This section walks you through setting up Stellar Scaffold from scratch.

Prerequisites

Before you begin, make sure you have the following installed:

Tool	Description	Install Link
Rust & Cargo	For writing and compiling smart contracts	curl https://sh.rustup.rs -sSf | sh
Node.js & npm	For frontend development	Download from official site
Stellar CLI	For building, deploying, and interacting with smart contracts	Link for the repo
Docker	For running a Stellar node locally	Download from official site

1. Install the Stellar Scaffold CLI

cargo install --locked stellar-scaffold-cli

The Stellar Scaffold CLI is installed as a plugin under the stellar CLI.

We recommend the use of cargo-binstall to install pre-compiled binaries.

2. Create a New Project

stellar scaffold init my-project
cd my-project

init asks which frontend framework you want. Pass --template react or --template svelte to skip the prompt, or --template none for a contracts-only project with no frontend at all.

3. Configure Your Frontend Environment

Edit .env with your preferred network, and other settings.

4. Install Frontend Dependencies

# Install Frontend dependencies
npm install

5. Start Development

npm run dev

This starts two processes together: stellar scaffold watch, which rebuilds and redeploys your contracts and regenerates their clients on every change, and Vite, which serves the frontend. You should see your app at http://localhost:5173.

6. For testnet/mainnet deployment:

The registry has two namespaces: verified (requires manager approval) and unverified (open to all). Use the unverified/ prefix for the unverified registry:

# First publish your contract to the unverified registry
stellar registry publish --wasm path/to/contract.wasm --wasm-name unverified/my-contract --binver "1.0.0"

# Then deploy an instance with constructor parameters
stellar registry deploy \
  --contract-name unverified/my-contract-instance \
  --wasm-name unverified/my-contract \
  -- \
  --param1 value1

# Can access the help docs for constructor parameters
stellar registry deploy \
  --contract-name unverified/my-contract-instance \
  --wasm-name unverified/my-contract \
  -- \
  --help

# Create an alias the deployed contract locally for use with stellar-cli
stellar registry create-alias unverified/my-contract-instance

Project Layout

After scaffolding a project, your folder structure will look like this:

my-project/
├── contracts/            # Your Rust smart contracts (compiled to Wasm)
├── app/                  # Your frontend
│   └── src/              # Components, pages, hooks, entry point
├── app-lib/              # Utility code, ready to use from your app
│   ├── clients/          # Generated contract clients — regenerated, don't edit
│   ├── wallet.ts         # Wallet connection
│   └── ...               # Network config, storage, formatting helpers
├── e2e/                  # End-to-end tests
├── environments.toml     # Networks, accounts, and contracts per environment
├── scaffold.yml          # CLI configuration
├── .env                  # Local environment variables
├── Cargo.toml            # Rust workspace
├── package.json          # npm workspace root
├── target/               # Build outputs

All of it is yours. There is no hidden framework and nothing to eject from — app/ and app-lib/ are ordinary source files you can read, edit, or delete.

app-lib/ holds the plumbing most Stellar apps need: connecting a wallet, reading network settings from your environment, funding a test account, formatting balances. Your app imports it as @stellar-scaffold/app-lib. Use it, change it, or ignore it and write your own — nothing in the toolchain depends on you keeping it.

The one exception is app-lib/clients/, which is generated.

Contract clients

Every time your contracts build or redeploy, Stellar Scaffold rewrites app-lib/clients/ to match them. Treat it as build output:

• app-lib/clients/<name>/ — one package per contract: a type-safe interface with every method, argument, and return type taken from the contract itself.
• app-lib/clients/index.ts — connects each of those to your current environment's network and deployed address, and exports one ready-to-call object per contract.

That means your components never hold a contract address or an RPC URL. They import a name and call a method:

import { guessTheNumber } from "@stellar-scaffold/app-lib/clients";

const { result } = await guessTheNumber.get_prize();

Switching environments — local to testnet, say — changes what those objects point at, with no change to your code.

Because the directory is rewritten on every build, edits inside it are lost. To customize how a contract is called, wrap it in your own module under app/ and import that instead.

See the CLI Documentation for detailed command information and the Environments Guide for configuration details.

---

CLI Tools

Stellar Scaffold provides two main CLI tools:

stellar-scaffold Initialize and manage dApp projects:

stellar scaffold init my-project
stellar scaffold build

stellar-registry Manage contract deployment and versions:

# Publish to unverified registry (no approval needed)
stellar registry publish --wasm contract.wasm --wasm-name unverified/my-contract

# Deploy a contract instance
stellar registry deploy --contract-name unverified/instance --wasm-name unverified/my-contract

# Install deployed contracts locally
stellar registry create-alias unverified/instance

Use --help on any command for usage instructions. Use the unverified/ prefix for open publishing.

---

Smart Contract Deployment

The registry supports two namespaces:

• Verified registry (default) - Requires manager approval for initial publishes
• Unverified registry - Open for anyone to publish (use unverified/ prefix)

1. Publish Your Contract

# Publish to the unverified registry (no approval needed)
stellar registry publish \
  --wasm target/stellar/my_contract.wasm \
  --wasm-name unverified/my-contract \
  --binver "1.0.0"

2. Deploy the Contract

# Deploy without initialization
stellar registry deploy \
  --contract-name unverified/my-contract-instance \
  --wasm-name unverified/my-contract

# Deploy with constructor parameters
stellar registry deploy \
  --contract-name unverified/my-token \
  --wasm-name unverified/token \
  --version "1.0.0" \
  -- \
  --name "My Token" \
  --symbol "MTK" \
  --decimals 7

3. Install the Deployed Contract

stellar registry create-alias unverified/my-contract-instance

After installation, you can interact with the contract using stellar-cli:

stellar contract invoke --id my-contract-instance -- --help

You can deploy to testnet or mainnet depending on your .env and environments.toml. Names are normalized (underscores → hyphens, lowercase).

Happy hacking!