Android Installation

This guide will help you set up your development environment for building Android applications with Cuppa.

Prerequisites

Before you begin, ensure you have the following installed:

• JDK 17 or higher
• Android Studio Hedgehog (2023.1.1) or later
• Android SDK with API level 26 or higher
• Node.js 20.0.0 or higher
• pnpm 9.0.0 or higher (recommended) or npm/yarn

Installing Android Studio

Download Android Studio from the official website:

1. Visit developer.android.com/studio
2. Download and install Android Studio
3. During setup, ensure you install:
   • Android SDK
   • Android SDK Platform
   • Android Virtual Device (AVD)

Installing JDK

Check if JDK is installed:

# Check Java version
java -version

# If not installed, install via Homebrew (macOS)
brew install openjdk@17

# Or download from Oracle/OpenJDK website

Creating a New Android Project

Option 1: Using Cuppa CLI (Recommended)

# Create a new Cuppa project with Android support
pnpm create @mycuppa/app my-app --platforms android

cd my-app

Option 2: Adding Android to Existing Project

If you already have a Cuppa project:

# Navigate to your project
cd my-cuppa-app

# Add Android platform
pnpm cuppa add-platform android

Project Structure

After installation, your project will have this structure:

my-app/
├── android/                    # Android native code
│   ├── app/
│   │   ├── src/
│   │   │   └── main/
│   │   │       ├── kotlin/
│   │   │       │   └── com/myapp/
│   │   │       │       ├── MainActivity.kt
│   │   │       │       └── MainApplication.kt
│   │   │       └── AndroidManifest.xml
│   │   └── build.gradle.kts
│   ├── gradle/
│   └── build.gradle.kts
├── src/                        # Shared TypeScript code
│   ├── components/
│   ├── hooks/
│   └── services/
└── package.json

Installing Android Dependencies

Install the required Cuppa packages for Android:

# Install Cuppa Android packages
pnpm add @mycuppa/android @mycuppa/core @mycuppa/ui

Gradle Configuration

Ensure your android/app/build.gradle.kts includes Cuppa dependencies:

dependencies {
    implementation("io.mycuppa:cuppa-android:1.0.0")
    implementation("io.mycuppa:cuppa-core:1.0.0")
    implementation("io.mycuppa:cuppa-ui:1.0.0")

    // Jetpack Compose
    implementation(platform("androidx.compose:compose-bom:2024.01.00"))
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.material3:material3")
    implementation("androidx.compose.ui:ui-tooling-preview")

    // Other dependencies
    implementation("androidx.activity:activity-compose:1.8.2")
    implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.7.0")
}

Running Your Android App

Using Android Studio

1. Open android/ directory in Android Studio
2. Wait for Gradle sync to complete
3. Select a device or emulator
4. Click Run button or press Shift+F10

Using CLI

# Run on Android emulator
pnpm android

# Run on specific emulator
pnpm android --emulator="Pixel_7_API_34"

# Run on physical device
pnpm android --device

Creating an Emulator

If you don't have an emulator:

# List available AVDs
emulator -list-avds

# Create new AVD via Android Studio:
# Tools → Device Manager → Create Device

Or use command line:

# Download system image
sdkmanager "system-images;android-34;google_apis;x86_64"

# Create AVD
avdmanager create avd \
  --name Pixel_7_API_34 \
  --package "system-images;android-34;google_apis;x86_64" \
  --device "pixel_7"

# Start emulator
emulator -avd Pixel_7_API_34

Troubleshooting

Gradle Sync Failed

Try cleaning and rebuilding:

cd android
./gradlew clean
./gradlew build

SDK Not Found

Set ANDROID_HOME environment variable:

# Add to ~/.zshrc or ~/.bashrc
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

Compose Preview Not Working

Enable Compose preview in build.gradle.kts:

android {
    buildFeatures {
        compose = true
    }
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.8"
    }
}

App Won't Install

Clear app data and reinstall:

# Uninstall app
adb uninstall com.myapp

# Reinstall
pnpm android

Next Steps

Now that you have Cuppa installed for Android, continue to the Quick Start guide to build your first Android app.