Quickstart

This section walks you through setting up Scaffold Stellar 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 Scaffold Stellar CLI

cargo install --locked stellar-scaffold-cli

The Scaffold Stellar 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

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

You should see your React frontend 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/            # Rust smart contracts (compiled to WASM)
├── packages/             # Auto-generated TypeScript contract clients
├── src/                  # React frontend code
│   ├── components/       # Reusable UI pieces
│   ├── contracts/        # Contract interaction logic
│   ├── App.tsx           # Main app component
│   └── main.tsx          # Entry point
├── environments.toml     # Configuration per environment (dev/test/prod)
├── .env                  # Local environment variables
├── package.json          # Frontend packages
├── target/               # Build outputs

This template provides a ready-to-use frontend application with example smart contracts and their TypeScript clients. You can use these as reference while building your own contracts and UI. The frontend is set up with Vite, React, and includes basic components for interacting with the contracts.

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

---

CLI Tools

Scaffold Stellar 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!