MelodAI Documentation

Expo 56 Mobile App (melodai-app)

Install and run the MelodAI React Native app on Windows, macOS, and Linux. Covers Expo Go, API configuration, production builds, and Android APK/AAB release.

Requirements

  • Node.js 20 LTS and npm
  • Expo CLI via npx expo (project uses Expo SDK 56)
  • Git
  • Android: Android Studio, JDK 17, Android SDK (for emulator or local APK builds)
  • iOS (macOS only): Xcode 15+, CocoaPods, Apple Developer account for device/store builds
  • Running MelodAI Laravel API (local XAMPP or production HTTPS server)

Project path: melodai-app/ (sibling to Laravel root). Package: com.melodai.app, scheme: melodaiapp.

Step 1: Install Dependencies

cd melodai-app
npm install

Verify Expo version:

npx expo --version

Step 2: Configure Environment

Copy and edit melodai-app/.env.example → .env:

copy .env.example .env
EXPO_PUBLIC_API_URL=http://localhost/melodai/public/api/v1

Rules:

  • Use the Laravel API base including /api/v1 (no trailing slash).
  • Physical phone on same Wi‑Fi: replace localhost with your PC IPv4 from ipconfig / ifconfig.
  • Release APK/AAB must use HTTPS production URL — Expo Go can infer LAN; release builds cannot.

Examples:

EXPO_PUBLIC_API_URL=http://192.168.1.10/melodai/public/api/v1
EXPO_PUBLIC_API_URL=https://melodai.site/api/v1

After changing .env, restart Metro with cache clear: npx expo start -c. Production builds bake the URL via app.config.js → extra.apiUrl.

Step 3: Run with Expo Go

npx expo start
  1. Install Expo Go on your phone (SDK 56 compatible version).
  2. Scan the QR code from the terminal (same network as dev machine).
  3. Press a for Android emulator or i for iOS simulator (macOS).

Windows Development

Prerequisites

  • Install Android Studio → SDK Platform 34+, Build-Tools, Android Emulator.
  • Set ANDROID_HOME (e.g. C:\Users\You\AppData\Local\Android\Sdk).
  • Add platform-tools to PATH.

Start Laravel API (from project root):

composer run dev

Start Expo:

cd melodai-app && npx expo start

Run native Android project (dev client / release build):

npx expo run:android

macOS & iOS Development

xcode-select --install
cd melodai-app && npx expo run:ios

For App Store builds, configure signing in Xcode (ios/ folder after prebuild) with your Apple Team ID.

Linux Development

  • Install Node 20, Watchman (optional), Android SDK for emulator.
  • Use production or LAN API URL in .env.
cd melodai-app && npx expo start
npx expo run:android

Production API Configuration

Before any store or APK release:

  1. Deploy Laravel with HTTPS and valid SSL.
  2. Confirm API works: https://yourdomain.com/api/v1/...
  3. Set EXPO_PUBLIC_API_URL=https://yourdomain.com/api/v1 in melodai-app/.env.
  4. Rebuild native app (EAS or local Gradle) so env is embedded.

YouTube connect from mobile requires Google OAuth redirect registered for production HTTPS (see Providers doc).

EAS Build (Recommended for Production)

Expo Application Services builds signed APK/AAB in the cloud. Install EAS CLI and log in:

npm install -g eas-cli
eas login
cd melodai-app && eas build:configure

Set production env in eas.json or EAS secrets:

eas secret:create --name EXPO_PUBLIC_API_URL --value https://melodai.site/api/v1

Build Android APK (preview) or AAB (Play Store):

eas build --platform android --profile preview
eas build --platform android --profile production

iOS:

eas build --platform ios --profile production

Update app.json → extra.eas.projectId with your EAS project ID after linking.

Local Android APK (Gradle)

Generate native Android project and build release APK locally:

cd melodai-app
npx expo prebuild --platform android
cd android && .\gradlew assembleRelease

APK output (typical path):

melodai-app/android/app/build/outputs/apk/release/app-release.apk

Signing: create a keystore and configure android/app/build.gradle signingConfigs for Play Store uploads.

If CMake/NDK errors occur on Windows, clean android/.cxx and run gradlew clean before rebuild.

Store Release Checklist

  • Production EXPO_PUBLIC_API_URL baked into build
  • App icons and splash assets in assets/images/
  • Version bumped in app.json (version, Android versionCode)
  • usesCleartextTraffic disabled for production HTTPS-only (update app.json android section)
  • Privacy policy URL and store listing prepared
  • Test login, registration, music generation, and profile on release build

Troubleshooting (Mobile)

  • App shows welcome instead of home after login (APK): ensure production API URL is set before build; clear app data and reinstall.
  • Network request failed: API unreachable — check URL, HTTPS cert, and firewall; on LAN use PC IP not localhost.
  • YouTube OAuth blocked: register correct redirect URI in Google Cloud; use server-side connect flow.
  • Expo Go works but APK fails: release build missing EXPO_PUBLIC_API_URL — rebuild with env set.
  • Metro cache issues: npx expo start -c