@orchard9ai/create-vite-vike-tauri/templates/mobile/MOBILE_SETUP.md

Create Vite + Vike + Tauri applications with Orchard9 design system

# Mobile Development Setup

This project supports iOS and Android development through Tauri v2. Follow these steps to set up your mobile development environment.

## Prerequisites

### iOS Development (macOS only)

- Xcode 14+ installed from the App Store
- iOS development tools: `xcode-select --install`
- An Apple Developer account (for device testing)

### Android Development

- **Java 17+** - Install first: `brew install openjdk@17` (macOS) or download from [OpenJDK](https://openjdk.org/)
- **Android Studio** - Download from [developer.android.com](https://developer.android.com/studio)
- **Android SDK** (API level 24+) - Install via Android Studio SDK Manager
- **Android NDK** - Install via Android Studio SDK Manager (required for Tauri)

**Installation Steps:**

1. **Install Java 17+**:

   ```bash
   # macOS
   brew install openjdk@17

   # Add to PATH
   echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc
   ```

2. Install Android Studio
3. Open Android Studio → SDK Manager (Settings → Appearance & Behavior → System Settings → Android SDK)
4. **SDK Platforms tab**: Install Android SDK Platform (API 24+)
5. **SDK Tools tab**: Install:
   - Android SDK Build-Tools
   - **Android NDK (Side by side)** ← Critical for Tauri!
   - Android SDK Command-line Tools
6. Click "Apply" and wait for installation to complete
7. Set environment variables:

```bash
# macOS/Linux (add to ~/.zshrc or ~/.bashrc)
export JAVA_HOME="$(brew --prefix openjdk@17)/libexec/openjdk.jdk/Contents/Home"  # macOS
export JAVA_HOME="/usr/lib/jvm/java-17-openjdk"  # Linux (adjust path as needed)
export ANDROID_HOME=$HOME/Library/Android/sdk  # macOS
export ANDROID_HOME=$HOME/Android/Sdk          # Linux
export NDK_HOME=$ANDROID_HOME/ndk/[version]    # e.g., ndk/26.1.10909125

# Windows (add to system environment variables)
export JAVA_HOME="C:\Program Files\Java\jdk-17"
export ANDROID_HOME=%LOCALAPPDATA%\Android\Sdk
export NDK_HOME=%ANDROID_HOME%\ndk\[version]

# Add to PATH
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/tools
```

**Verify NDK Installation and Find Version:**

```bash
# Check if NDK directory exists
ls $ANDROID_HOME/ndk/

# If NDK directory doesn't exist, install it via Android Studio:
# 1. Open Android Studio
# 2. SDK Manager → SDK Tools tab
# 3. Check "Android NDK (Side by side)"
# 4. Click Apply

# After installation, find your NDK version:
ls $ANDROID_HOME/ndk/
# Use the version number in NDK_HOME, e.g.:
# export NDK_HOME=$ANDROID_HOME/ndk/26.1.10909125
```

### Rust Targets

Install the required Rust targets:

```bash
# For iOS
rustup target add aarch64-apple-ios x86_64-apple-ios aarch64-apple-ios-sim

# For Android
rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android
```

## Building for Mobile

### iOS

1. **Development mode** (with hot reload):

   ```bash
   pnpm tauri:ios:dev
   ```

2. **Build for release**:
   ```bash
   pnpm tauri:ios
   ```

### Android

1. **Development mode** (with hot reload):

   ```bash
   pnpm tauri:android:dev
   ```

2. **Build for release**:
   ```bash
   pnpm tauri:android
   ```

## Common Issues

### "Asset not found: index.html"

This error occurs when the frontend hasn't been built. The mobile scripts now automatically build the frontend first, but if you encounter this:

```bash
pnpm build
```

### iOS Simulator Issues

If the iOS simulator doesn't launch:

1. Open Xcode and ensure simulators are installed
2. Run `xcrun simctl list devices` to see available simulators
3. Manually open a simulator from Xcode before running the build

### Java Issues

If you get "Unable to locate a Java Runtime" or Java-related errors:

1. **Install Java 17+**:

   ```bash
   # macOS
   brew install openjdk@17
   echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc

   # Linux
   sudo apt install openjdk-17-jdk  # Ubuntu/Debian
   # or
   sudo yum install java-17-openjdk-devel  # RHEL/CentOS
   ```

2. **Set JAVA_HOME**:
   ```bash
   # macOS
   export JAVA_HOME="$(brew --prefix openjdk@17)/libexec/openjdk.jdk/Contents/Home"
   # Linux
   export JAVA_HOME="/usr/lib/jvm/java-17-openjdk"
   ```
3. **Verify**: `java -version`

### Android NDK Issues

If you get "NDK_HOME environment variable isn't set" or "doesn't point to an existing directory":

1. **Install NDK**: Open Android Studio → SDK Manager → SDK Tools tab → Check "Android NDK (Side by side)"
2. **Set NDK_HOME**:
   ```bash
   # Find your NDK version
   ls $ANDROID_HOME/ndk/
   # Set the environment variable (replace with your version)
   export NDK_HOME=$ANDROID_HOME/ndk/26.1.10909125
   # Make it persistent
   echo 'export NDK_HOME=$ANDROID_HOME/ndk/26.1.10909125' >> ~/.zshrc
   source ~/.zshrc
   ```
3. **Re-initialize**: `pnpm tauri android init`

### Android SDK Issues

If you get "ANDROID_HOME environment variable isn't set":

```bash
# Set ANDROID_HOME
export ANDROID_HOME=$HOME/Library/Android/sdk  # macOS
export ANDROID_HOME=$HOME/Android/Sdk          # Linux

# Verify it's correct
echo $ANDROID_HOME
ls $ANDROID_HOME/platform-tools

# Make it persistent
echo 'export ANDROID_HOME=$HOME/Library/Android/sdk' >> ~/.zshrc
source ~/.zshrc
```

### Android Emulator Issues

If the Android emulator doesn't launch:

1. Open Android Studio > AVD Manager
2. Create a new virtual device if none exist
3. Start the emulator before running the build

### General Setup Verification

Check your complete setup:

```bash
# Check Java installation
java -version
echo "JAVA_HOME: $JAVA_HOME"

# Check Android environment
echo "ANDROID_HOME: $ANDROID_HOME"
echo "NDK_HOME: $NDK_HOME"
ls $ANDROID_HOME/platform-tools  # Should show adb, etc.
ls $NDK_HOME  # Should show NDK contents

# Verify Tauri can detect your setup
pnpm tauri info
```

## Mobile-Specific Configuration

The Tauri configuration (`src-tauri/tauri.conf.json`) is shared between desktop and mobile builds. Mobile-specific settings can be added in the future using platform conditionals.

## Debugging

### iOS

- Use Safari's Web Inspector for debugging the webview
- Enable developer mode on your iOS device/simulator

### Android

- Use Chrome DevTools for debugging the webview
- Enable USB debugging on your Android device

## Distribution

### iOS

1. Configure your Apple Developer account in Xcode
2. Update the bundle identifier in `tauri.conf.json`
3. Build and archive through Xcode

### Android

1. Generate a signing key for your app
2. Configure the key in your build settings
3. Build the APK/AAB for distribution