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:

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

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

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

# Install the deployed contract locally for use with stellar-cli
stellar registry create-alias 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:

stellar registry publish --wasm contract.wasm --wasm-name my-contract    # Publish contract to the registry
stellar registry deploy --contract-name instance --wasm-name my-contract # Deploy a contract instance
stellar registry create-alias my-contract-instance                       # Install deployed contracts locally

Use --help on any command for usage instructions.

---

Smart Contract Deployment

1. Publish Your Contract

# Publish with automatic metadata extraction
stellar registry publish --wasm target/stellar/my_contract.wasm

# Or specify details manually
stellar registry publish \
  --wasm target/stellar/my_contract.wasm \
  --wasm-name my-contract \
  --binver "1.0.0"

2. Deploy the Contract

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

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

3. Install the Deployed Contract

stellar registry create-alias 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.

Happy hacking!