Development Environment Setup

Complete guide to setting up your development environment for SatSigner development

This guide will walk you through setting up a complete development environment for contributing to SatSigner.

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

• Node.js: Version 22.4.0 or higher
• Yarn: Package manager
• Git: Version control

Platform-Specific Requirements

For Android Development

• Android Studio or Android SDK
• Java JDK 17
• Android SDK Build Tools
• Android Platform Tools

For iOS Development (macOS only)

• Xcode (latest version)
• Xcode Command Line Tools
• CocoaPods

Step 1: Install Node.js and Yarn

Install Node.js

Download and install Node.js 22.4.0 or higher from nodejs.org.

Verify installation:

node --version  # Should be >= 22.4.0

Install Yarn

npm install --global yarn

Verify installation:

yarn --version

Step 2: Clone the Repository

git clone https://github.com/satsigner/satsigner.git
cd satsigner

Step 3: Install Dependencies

Install all dependencies from the root of the repository:

yarn install

This will install dependencies for the entire monorepo, including the mobile app and any other packages.

Step 4: Set Up Android Environment

Option A: Using Android Studio (Recommended)

1. Download and install Android Studio
2. Open Android Studio and go to Settings/Preferences
3. Navigate to Appearance & Behavior > System Settings > Android SDK
4. Install Android SDK Platform 34 (or latest)
5. Install Android SDK Build-Tools
6. Install Android SDK Platform-Tools

Option B: Using Command Line Tools

If you prefer not to use Android Studio, install these packages:

# On Arch Linux
sudo pacman -S android-sdk android-sdk-build-tools android-sdk-platform-tools android-tools

# On macOS (using Homebrew)
brew install --cask android-sdk

Set Environment Variables

Add these to your shell profile (~/.bashrc, ~/.zshrc, or ~/.bash_profile):

Linux

export ANDROID_HOME=/opt/android-sdk
export PATH=${PATH}:${ANDROID_HOME}/tools:${ANDROID_HOME}/tools/bin:${ANDROID_HOME}/platform-tools:${ANDROID_HOME}/emulator

macOS

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=${PATH}:${ANDROID_HOME}/tools:${ANDROID_HOME}/tools/bin:${ANDROID_HOME}/platform-tools:${ANDROID_HOME}/emulator

Windows (Git Bash)

Create C:\Users\YOUR_USERNAME\.bash_profile:

export PATH="/c/Users/YOUR_USERNAME/AppData/Local/Android/Sdk/platform-tools:$PATH"
export PATH="/c/Program Files/Java/jdk-17/bin:$PATH"
export ANDROID_HOME="/c/Users/YOUR_USERNAME/AppData/Local/Android/Sdk"

Replace YOUR_USERNAME with your actual Windows username.

Set Up Android Emulator

Install System Image (Requires JDK 8 temporarily)

For downloading system images, you need JDK 8:

# On Arch Linux
sudo archlinux-java set java-8-openjdk

List available system images:

sdkmanager --list

Install a system image (choose based on your CPU architecture):

# For Intel/AMD (x86_64)
sdkmanager --install 'system-images;android-34;default;x86_64'

# For Apple Silicon (arm64)
sdkmanager --install 'system-images;android-34;default;arm64-v8a'

Create Emulator Device

avdmanager create avd -n satsigner-dev -k 'system-images;android-34;default;x86_64'

Switch to JDK 17

After creating the emulator, switch to JDK 17 for building and running the app:

# On Arch Linux
sudo archlinux-java set java-17-openjdk

# On macOS (using Homebrew)
brew install openjdk@17

Verify Java version:

java -version  # Should show version 17

Troubleshooting Android Setup

CXX5304 Build Error

If you encounter [CXX5304] error while building:

unset _JAVA_OPTIONS

Path Issues on Windows

Use Git Bash instead of PowerShell for all commands. Ensure the .bash_profile is in your home directory.

Using direnv (Linux/macOS)

For automatic environment loading, install direnv:

# Install direnv
brew install direnv  # macOS
sudo apt install direnv  # Debian/Ubuntu

# Add to shell (add to ~/.bashrc or ~/.zshrc)
eval "$(direnv hook bash)"  # for bash
eval "$(direnv hook zsh)"   # for zsh

Create apps/mobile/.envrc:

export ANDROID_HOME=/opt/android-sdk
export PATH=$PATH:${ANDROID_HOME}/tools:${ANDROID_HOME}/tools/bin:${ANDROID_HOME}/platform-tools:${ANDROID_HOME}/emulator

Allow direnv:

cd apps/mobile
direnv allow

Step 5: Set Up iOS Environment (macOS only)

Install Xcode

1. Install Xcode from the Mac App Store
2. Install Xcode Command Line Tools:

xcode-select --install

Install CocoaPods

sudo gem install cocoapods

Install iOS Dependencies

cd apps/mobile/ios
pod install
cd ../..

Step 6: Set Up Expo Environment

Follow the official Expo documentation for additional setup.

Important Notes:

• Select “Development build” option
• Disable “Build with Expo Application Services (EAS)”
• Do NOT run npx expo start - use the commands below instead

Step 7: Run the Application

Navigate to the mobile app directory:

cd apps/mobile

Run on Android

yarn android

This will:

1. Start the Metro bundler
2. Build the Android app
3. Install it on your emulator or connected device
4. Launch the app

Run on iOS (macOS only)

yarn ios

This will:

1. Start the Metro bundler
2. Build the iOS app
3. Install it on your simulator or connected device
4. Launch the app

Alternative: Run on Physical Device

Android

1. Enable Developer Options on your Android device
2. Enable USB Debugging
3. Connect via USB
4. Run yarn android

iOS

1. Open apps/mobile/ios/satsigner.xcworkspace in Xcode
2. Select your device from the device dropdown
3. Click the Run button or run yarn ios

Step 8: Development with Storybook

SatSigner includes Storybook for component development in isolation.

Run Storybook on Android

cd apps/mobile
yarn sb:android

Run Storybook on iOS

cd apps/mobile
yarn sb:ios

Generate Storybook Stories

yarn storybook-generate

Development Workflow

Available Scripts

From apps/mobile/ directory:

# Start Metro bundler (usually not needed, done automatically)
yarn start

# Run on Android
yarn android

# Run on iOS
yarn ios

# Run tests
yarn test         # Run all tests
yarn test:unit    # Run unit tests only
yarn test:int     # Run integration tests only

# Type checking
yarn type-check

# Linting
yarn lint         # Check for lint errors
yarn lint:fix     # Fix lint errors automatically

# Formatting
yarn format       # Check formatting
yarn format:fix   # Fix formatting automatically

From repository root:

# Lint all packages
yarn lint
yarn lint:fix

# Format all packages
yarn format
yarn format:fix

Project Structure

SatSigner uses a monorepo structure with Yarn Workspaces:

satsigner/
├── apps/
│   ├── docs/           # Documentation (Mintlify)
│   └── mobile/         # React Native app
├── package.json        # Root package.json
├── turbo.json         # Turborepo configuration
└── yarn.lock          # Dependency lock file

Mobile App Structure

apps/mobile/
├── api/               # Backend API integrations (BDK, Electrum, Esplora)
├── app/               # Expo Router pages
├── components/        # React Native components
├── hooks/             # Custom React hooks
├── store/             # Zustand state stores
├── types/             # TypeScript type definitions
├── utils/             # Utility functions
├── constants/         # App constants
├── config/            # Configuration files
├── storage/           # Storage utilities (MMKV, encrypted)
├── styles/            # Styling and themes
├── tests/             # Tests (unit and integration)
├── android/           # Android native code
├── ios/               # iOS native code
└── package.json       # Mobile app dependencies

Editor Setup

VS Code (Recommended)

Install these extensions:

• ESLint: For linting
• Prettier: For code formatting
• React Native Tools: For React Native development
• TypeScript: For TypeScript support
• Expo Tools: For Expo development

Settings are included in .vscode/ directory.

Other Editors

Ensure your editor supports:

• TypeScript
• ESLint
• Prettier
• React Native syntax

Common Issues

Metro Bundler Issues

Clear Metro cache:

cd apps/mobile
rm -rf node_modules/.cache
yarn start --reset-cache

Build Failures

Clean build:

# Android
cd apps/mobile/android
./gradlew clean
cd ..

# iOS
cd apps/mobile/ios
rm -rf build/
pod deintegrate
pod install
cd ..

Dependency Issues

Reinstall dependencies:

# From repository root
rm -rf node_modules
rm yarn.lock
yarn install

Node Version Issues

Use a Node version manager like nvm or fnm:

# Using nvm
nvm install 22.4.0
nvm use 22.4.0

# Using fnm
fnm install 22.4.0
fnm use 22.4.0

Next Steps

Now that your environment is set up:

1. Read the Architecture guide to understand the codebase
2. Review the Contributing guide for contribution workflows
3. Check out the open issues to find tasks
4. Join the Telegram group to connect with other developers

Happy coding!