Setup Guide

Complete installation and configuration guide for setting up your Solana App Kit development environment

This guide will walk you through setting up your development environment and getting your first Solana mobile app running in minutes.

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Node.js >= 18.0.0

Download from nodejs.org - LTS version recommended

Package Manager

pnpm (recommended), npm, or pnpm - we recommend pnpm for better performance

Git

Version control system - download from git-scm.com

iOS Development

macOS Required: iOS development requires a Mac computer

Xcode

Latest version from Mac App Store - includes iOS Simulator and build tools

CocoaPods

Install with: sudo gem install cocoapods

iOS Simulator

Included with Xcode - for testing on virtual devices

Android Development

Android Studio

With Android SDK - download from developer.android.com

Android Emulator

Or physical Android device - for testing your applications

Java Development Kit (JDK)

Version 11 or newer - required for Android builds

Additional Tools

Expo CLI

Install globally: npm install -g @expo/cli

EAS CLI

For building and deployment: npm install -g eas-cli

Quick Start

1. One Command Setup

   The fastest way to get started is using our CLI tool:

   npx start-solana-app
   
2. Automatic Process

   This command will automatically:

   • Clone the repository
   • Install all dependencies
   • Set up environment variables
   • Launch the development server
3. Ready to Go

   Your app will be running on iOS Simulator, Android Emulator!

That’s it! Most developers can skip the manual installation section below.

Manual Installation

If you prefer to set up manually or need more control:

1. Clone the Repository

   git clone https://github.com/SendArcade/solana-app-kit.git
   cd solana-app-kit
   
2. Install Dependencies

   pnpm (Recommended)

   pnpm install
   

   npm install
   

   pnpm install
   
3. iOS Dependencies (iOS only)

   cd ios
   pod install
   cd ..
   

Environment Configuration

The app requires several environment variables for full functionality:

1. Create Environment File

   cp .env.example .env.local
   
2. Configure Core Variables

   Add your API keys and configuration to .env.local:

Show Core Environment Variables

# Blockchain Configuration
CLUSTER=mainnet-beta
RPC_URL=https://api.mainnet-beta.solana.com

# Wallet Providers
PRIVY_APP_ID=your_privy_app_id
PRIVY_CLIENT_ID=your_privy_client_id
DYNAMIC_ENVIRONMENT_ID=your_dynamic_env_id
DYNAMIC_API_KEY=your_dynamic_api_key

# Turnkey Wallet Configuration
TURNKEY_BASE_URL=https://api.turnkey.com
TURNKEY_RP_ID=host.exp.exponent
TURNKEY_RP_NAME=your_app_name
TURNKEY_ORGANIZATION_ID=your_turnkey_organization_id
TURNKEY_API_PUBLIC_KEY=your_turnkey_public_key
TURNKEY_API_PRIVATE_KEY=your_turnkey_private_key

# API Services
HELIUS_API_KEY=your_helius_api_key
TENSOR_API_KEY=your_tensor_api_key
COINGECKO_API_KEY=your_coingecko_api_key
BIRDEYE_API_KEY=your_birdeye_api_key
OPENAI_API_KEY=your_openai_api_key

# Backend Server
SERVER_URL=http://localhost:3000

Getting API Keys

Required APIs

Essential for core functionality:

Helius

Enhanced Solana RPC - Sign up for better reliability and faster responses

Privy

Embedded Wallets - Get credentials for social login and wallet creation

Optional APIs

For enhanced features:

Dynamic

Multi-chain Wallets - Register for 300+ wallet support

Turnkey

Enterprise Wallets - Apply for institutional-grade security

Tensor

NFT Data - Get API access for NFT marketplace features

CoinGecko

Market Data - Free API for token prices and market info

Birdeye

Token Analytics - Sign up for advanced token data

OpenAI

AI Features - Get API key for AI-powered interactions

Backend Server Setup

The kit includes a powerful backend server for enhanced functionality:

1. Navigate to Server Directory

   cd server
   
2. Install Server Dependencies

   pnpm install
   
3. Configure Server Environment

   cp .env.example .env
   
4. Set Up Database

   # Create database
   createdb solana_app_kit
   
   # Run migrations
   pnpm run migrate
   
5. Start Backend Server

   pnpm dev
   

   Server will be available at http://localhost:3000

Show Required Server Environment Variables

# Blockchain
WALLET_PRIVATE_KEY=your_wallet_private_key
RPC_URL=your_helius_rpc_url
TOKEN_MILL_PROGRAMID=your_token_mill_program_id
TOKEN_MILL_CONFIG_PDA=your_token_mill_config_pda

# Database
DATABASE_URL=postgresql://username:password@localhost:5432/solana_app_kit

# IPFS Storage
PINATA_JWT=your_pinata_jwt
PINATA_GATEWAY=your_pinata_gateway
PINATA_SECRET=your_pinata_secret
PINATA_API_KEY=your_pinata_api_key

# Cloud Storage
GCS_BUCKET_NAME=your_gcs_bucket_name
SERVICE_ACCOUNT_EMAIL=your_service_account_email

# Supabase (optional)
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key

Running the Mobile App

1. Start Development Server

   From the root directory:

   pnpm start
   
2. Choose Your Platform

   iOS

   # Using Expo CLI
   pnpm ios
   
   # Or using Expo development build
   expo run:ios
   

   Android

   # Using Expo CLI
   pnpm android
   
   # Or using Expo development build
   expo run:android
   

   Web Browser

   # Open in web browser
   pnpm web
   

Development Server Commands

When the Expo server is running, use these keyboard shortcuts:

iOS Simulator

Press i to open iOS simulator

Android Emulator

Press a to open Android emulator

Web Browser

Press w to open in web browser

Reload App

Press r to reload the app

Toggle Menu

Press m to toggle the menu

Developer Tools

Press d to open developer tools

Verification

1. Check Mobile App

   ✅ You should see the intro screen with wallet connection options

2. Verify Backend

   ✅ Check http://localhost:3000/health returns 200 status

3. Test Wallet Connection

   ✅ Try connecting with any configured wallet provider

4. Navigate Features

   ✅ Navigate through the app’s main features

Development Mode

The app includes a special development mode for easier debugging:

dev_mode · object

Show Enabling Dev Mode

1. Shake your device or press Cmd+D (iOS) / Cmd+M (Android)
2. Select “Dev Mode” from the developer menu
3. Access debugging tools and mock data

Show Dev Mode Features

Feature	Description
Mock Wallets	Test without real wallet connections
Sample Data	Pre-populated data for UI development
Network Logging	Debug API calls in real-time
State Inspection	Monitor Redux state changes

Troubleshooting

troubleshooting · object

Show Metro Bundler Issues

Issue	Solution
Cache Problems	Run pnpm start --reset-cache
Port Conflicts	Try different port with --port flag
Dependency Issues	Clear node_modules and reinstall

# Reset cache and restart
pnpm start --reset-cache
# or
expo start --clear

Show iOS Build Issues

Step	Command/Action
Update Pods	cd ios && pod install --repo-update
Clear Xcode	Clean build folder and derived data
Reset Simulator	Erase all content and settings

cd ios
pod install --repo-update
cd ..

Show Android Build Issues

Step	Command/Action
Clean Build	cd android && ./gradlew clean
Update Tools	Check SDK Manager for updates
Clear Cache	Clear Android Studio caches

cd android
./gradlew clean
cd ..

Show Environment Variable Issues

Check	Description
File Location	.env.local in root directory
Server Restart	Required after variable changes
Required Vars	All necessary variables set
API Keys	Valid format and permissions

Verification Steps:

1. Check file existence and location
2. Verify variable format and values
3. Restart development server
4. Test API connectivity

Need Help? Join our Telegram community for real-time support from developers and maintainers.

Next Steps

Explore the UI

Navigate through screens and discover the app’s features and capabilities

Review the Code

Understand the structure with our comprehensive project organization guide

Try Features

Test wallet connections and explore token swaps, NFTs, and other functionality

Start Customizing

Modify the app for your specific use case with practical examples

Production Deployment

Ready to ship your app? Deploy to app stores with EAS Build:

iOS App Store

# Build for iOS
eas build --platform ios --profile production

# Submit to App Store
eas submit --platform ios

Google Play Store

# Build for Android
eas build --platform android --profile production

# Submit to Play Store
eas submit --platform android

Learn More: Check out the EAS Build documentation for detailed deployment instructions.

---