This guide covers everything you need to set up a complete Lernza development environment from scratch. Lernza consists of Soroban smart contracts (Rust) and a React frontend (TypeScript).
Before you begin, ensure you have:
- macOS, Linux, or WSL2 (native Windows not recommended)
- Git installed (
git --version) - Rust 1.80+ (stable toolchain)
- Node.js 24.12.0 (LTS recommended)
- pnpm 10.33.0 (frontend package manager)
- Stellar CLI v25.2+
- WASM target for Rust (
wasm32-unknown-unknown)
Lernza contracts require Rust to compile to WASM. Install the stable toolchain:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shVerify the installation:
rustc --version # Should be 1.80 or higher
cargo --versionThe contracts compile to WebAssembly. Add the target:
rustup target add wasm32-unknown-unknownVerify:
rustup target list | grep wasm32-unknown-unknownUse nvm (Node Version Manager) to install Node.js 24.12.0:
brew install node@24
brew link node@24 --force
# Verify
node --version # Should be v24.12.0curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
# Verify
node --version # Should be v24.12.0curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 24.12.0
nvm use 24.12.0
# Verify
node --version # Should be v24.12.0pnpm is a fast, disk-space efficient package manager. Install it globally:
npm install -g pnpm@10.33.0
# Verify
pnpm --version # Should be 10.33.0If you use nvm, the repository includes a .nvmrc file that specifies the exact Node.js version. When you enter the project directory, nvm will automatically switch to the correct version:
cd lernza
# nvm automatically uses v24.12.0 (if you have nvm installed)
node --version # v24.12.0This ensures all contributors use the same Node.js version, preventing "works on my machine" issues.
The Stellar CLI is required to build Soroban contracts. Install it:
brew install stellar-cli# Download latest release
STELLAR_VERSION="25.2.0"
curl -fsSL https://github.com/stellar/stellar-cli/releases/download/v${STELLAR_VERSION}/stellar-cli-${STELLAR_VERSION}-x86_64-unknown-linux-gnu.tar.gz \
| tar xz -C /usr/local/bin
# Verify
stellar version# Visit https://github.com/stellar/stellar-cli/releases
# Download the x86_64-apple-darwin.tar.gz file
# Extract to /usr/local/bin
tar xz -C /usr/local/bin -f stellar-cli-25.2.0-x86_64-apple-darwin.tar.gz
# Verify
stellar versiongit clone https://github.com/lernza/lernza.git
cd lernzaThe Lernza contracts are in contracts/ and use Soroban SDK v25.
# Rust dependencies are managed by Cargo
# No additional installation neededcargo test --workspaceThis runs all 33 contract tests. You should see:
test result: ok. X passed; 0 failed; 0 ignored; 0 measured
Compile to optimized WASM:
stellar contract build --manifest-path contracts/workspace/Cargo.toml --release
stellar contract build --manifest-path contracts/milestone/Cargo.toml --release
stellar contract build --manifest-path contracts/rewards/Cargo.toml --releaseOr use the provided Makefile:
cd contracts/workspace && make build
cd contracts/milestone && make build
cd contracts/rewards && make build# Run all tests
cargo test --workspace
# Run tests for a single contract
cargo test -p workspace
cargo test -p milestone
cargo test -p rewards
# Run a specific test
cargo test -p milestone -- test_name
# Format code
cargo fmt --all
# Lint
cargo clippy --workspace --all-targets
# Build WASM
stellar contract build --manifest-path contracts/workspace/Cargo.toml --releaseThe frontend is a React 19 + TypeScript app with Vite, Tailwind CSS, and shadcn/ui components.
cd frontend
pnpm install --frozen-lockfile--frozen-lockfile ensures reproducible installs (same as all CI environments).
pnpm devThe app will start on http://localhost:5173
In your browser:
- Install Freighter wallet extension
- Switch to Testnet in Freighter settings
- Return to localhost:5173 and connect your wallet
pnpm buildThis runs type-checking (tsc -b) and builds optimized bundles in dist/.
Check for code style and potential issues:
pnpm lint# Development server
pnpm dev
# Production build
pnpm build
# Type-check only
pnpm tsc -b
# Lint
pnpm lint
# Preview production build locally
pnpm previewThe frontend supports optional environment variables for configuration. Create a .env.local file in the frontend/ directory:
cd frontend
touch .env.local# Optional: Soroban RPC endpoint (defaults to testnet)
# VITE_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
# Optional: Network passphrase
# VITE_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
# Optional: Contract addresses (if deploying custom contracts)
# VITE_WORKSPACE_CONTRACT_ID=CAxxxxxxxxxxxx
# VITE_MILESTONE_CONTRACT_ID=CAxxxxxxxxxxxx
# VITE_REWARDS_CONTRACT_ID=CAxxxxxxxxxxxxVITE_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
VITE_NETWORK_PASSPHRASE=Test SDF Network ; September 2015Note: Variables must be prefixed with VITE_ to be accessible in the browser. See Vite's environment variables guide.
Note: Never commit .env.local to Git. It's in .gitignore for security.
VS Code is recommended for development. Install these extensions for a better experience:
-
rust-analyzer (rust-lang.rust-analyzer) — LSP for Rust
- Provides type hints, error checking, code completion
- Settings: Enable "Inlay Hints" in extension settings
-
Even Better TOML (tamasfe.even-better-toml) — Syntax highlighting for Cargo.toml
-
Crates (serayuzgur.crates) — Dependency version management for Cargo.toml
-
TypeScript Vue Plugin (Volar) (Vue.volar) — TS language server support
- Also provides JSX/TypeScript support in Vite projects
-
ESLint (dbaeumer.vscode-eslint) — Linting integration
- Integrates eslint into the editor for real-time error reporting
-
Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss) — Tailwind class completion
- Shows preview on hover, suggests class names
-
Prettier (esbenp.prettier-vscode) — Code formatter
- Format on save (optional, configure in settings)
-
Git Lens (eamodio.gitlens) — Git history and blame info
- Inline blame, file history, branch/commit navigation
-
Thunder Client (rangav.vscode-thunder-client) — HTTP client (alternative to Postman)
- Test API endpoints directly in VS Code
- Stellar Development (stellar.vscode-stellar) — Stellar/Soroban support
- Syntax highlighting for XDR and Stellar assets
- Open VS Code
- Go to Extensions (Cmd+Shift+X on macOS, Ctrl+Shift+X on Linux/Windows)
- Search for each extension name and click Install
Or install from command line:
code --install-extension rust-lang.rust-analyzer
code --install-extension tamasfe.even-better-toml
code --install-extension serayuzgur.crates
code --install-extension Vue.volar
code --install-extension dbaeumer.vscode-eslint
code --install-extension bradlc.vscode-tailwindcss
code --install-extension esbenp.prettier-vscode
code --install-extension eamodio.gitlens
code --install-extension rangav.vscode-thunder-clientProblem: The WASM target is not installed.
Solution:
rustup target add wasm32-unknown-unknown
rustup updateProblem: Stellar CLI is not in your PATH.
Solution (macOS):
brew reinstall stellar-cliSolution (Linux/WSL2):
# Verify installation location
which stellar
# If not found, download and install manually
STELLAR_VERSION="25.2.0"
curl -fsSL https://github.com/stellar/stellar-cli/releases/download/v${STELLAR_VERSION}/stellar-cli-${STELLAR_VERSION}-x86_64-unknown-linux-gnu.tar.gz \
| tar xz -C /usr/local/binProblem: Build cache is corrupted or disk is full.
Solution:
# Clean build artifacts
cargo clean
# Try running tests again
cargo test --workspace
# If still stuck, check disk space
df -hProblem: pnpm is not installed globally.
Solution:
npm install -g pnpm@9
pnpm --versionProblem: Node.js 24 is not the active version (using nvm).
Solution:
# Set default version
nvm alias default 24
# Use for this session
nvm use 24
# Verify
node --versionProblem: Global packages installed without proper permissions.
Solution (Linux/macOS):
# Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# Reinstall pnpm
npm install -g pnpm@9Problem: pnpm lockfile is out of sync or incompatible.
Solution:
# Remove lock file and reinstall
cd frontend
rm pnpm-lock.yaml
pnpm installProblem: Port 5173 is already in use.
Solution:
# Use a different port
pnpm dev -- --port 5174
# Or kill the process using port 5173
# macOS/Linux
lsof -i :5173 | grep LISTEN | awk '{print $2}' | xargs kill -9
# Windows
netstat -ano | findstr :5173
taskkill /PID <PID> /FProblem: Freighter extension is not installed or not enabled.
Solution:
- Visit Freighter.app
- Install the extension for your browser
- Reload the page (
Cmd+R/Ctrl+R) - Check the extension icon in your browser toolbar
Problem: Freighter is set to mainnet, but the app expects testnet.
Solution:
- Click the Freighter extension icon
- Click the network dropdown (top right)
- Select Test Network
- Reload the page
Problem: Freighter wallet is installed but no account is created.
Solution:
- Click Freighter extension
- Click Create New Account or Import Existing Account
- Follow the setup wizard
- Return to the app and reconnect
Problem: SSH keys are not configured.
Solution (use HTTPS):
git clone https://github.com/lernza/lernza.git
cd lernzaSolution (SSH alternative):
# Generate SSH key
ssh-keygen -t ed25519 -C "your-email@example.com"
# Add to ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
# Add public key to GitHub:
# 1. Go to https://github.com/settings/keys
# 2. Click "New SSH key"
# 3. Paste output of: cat ~/.ssh/id_ed25519.pub
# Try cloning again
git clone git@github.com:lernza/lernza.gitProblem: Repository uses main as default branch, but you're checking out master.
Solution:
git checkout mainOnce installation is complete, verify everything works:
cd contracts
cargo test --workspaceExpected output: test result: ok. 33 passed; 0 failed;
rustup target add wasm32-unknown-unknown
cargo install --locked stellar-clistellar contract buildcargo test --workspacecargo fmt --all -- --check
cargo clippy --workspace --all-targetscd frontend
pnpm install --frozen-lockfile
pnpm buildExpected output: ✓ built in XXs (no errors)
Run both:
# Terminal 1: Contracts (optional - not needed for frontend dev)
cd contracts
cargo test --workspace
# Terminal 2: Frontend
cd frontend
pnpm devOpen http://localhost:5173 → wallet connects → app loads ✓
Periodically update tools to keep security patches and features:
rustup updatenvm install 24 # Install latest 24.x
nvm use 24 # Switch to it
node --version # Verifynpm install -g pnpm@9
pnpm --versioncd frontend
pnpm update
pnpm install --frozen-lockfile- Lernza docs: GitHub Issues
- Stellar docs: docs.stellar.org
- Soroban docs: soroban.stellar.org
- React docs: react.dev
- Vite docs: vitejs.dev
- Read the architecture: See CLAUDE.md for smart contract and frontend architecture
- Contribute: See CONTRIBUTING.md for contribution guidelines
- Start coding: Pick a good first issue
### Development
```bash
pnpm dev # http://localhost:5173
pnpm build # Type-check (tsc -b) + production build
pnpm lint # ESLintThis project uses husky and lint-staged to run checks before commits. Hooks are installed automatically after pnpm install in the frontend directory.
- ESLint on staged
.ts/.tsxfiles - cargo fmt --check on staged
.rsfiles
contracts/— Three Soroban smart contracts (quest, milestone, rewards)frontend/— React 19 + Vite + TypeScript + Tailwind CSS + shadcn/uidocs/— Documentation
- rust-analyzer
- ESLint
- Tailwind CSS IntelliSense
- Prettier
- WASM target missing: Run
rustup target add wasm32-unknown-unknown - pnpm lockfile error: Run
pnpm install --frozen-lockfile(don't usepnpm update) - Stellar CLI not found: Install via
cargo install --locked stellar-clior Homebrew