Gumroad Mobile

Gumroad is an e-commerce platform that enables creators to sell products directly to consumers. This repository contains source code for the Gumroad mobile application, built with Expo.

Get started

Prerequisites

Gumroad

In development this application is intended to connect to a local Gumroad development instance. You will need to set up and run the Gumroad web application locally alongside this application.

Node.js

• https://nodejs.org/en/download
• Install the version listed in the .node-version file

Android Studio and/or Xcode

The application will run on an emulator or device, which you will need to set up via Android Studio or Xcode. Download and install at least one, and follow the instructions to create at least one virtual device (Android) or simulator (iOS).

• https://developer.android.com/studio
• https://developer.apple.com/xcode/

Rooted Android Emulator

Since Android emulators don't forward to the host machine's localhost, you will need to edit the hosts file on an emulator with root access to make our https://gumroad.dev development domain work.

1. Create a new Android Virtual Device (AVD) with a "Google APIs" system image (NOT the default "Google Play"):

   • In Android Studio, go to Tools > Device Manager.
   • Click Create Virtual Device.
   • Select any device definition.
   • Under System Image, go to the ARM Images tab and select an image with a "Target" that looks like Android X.X (Google APIs).
   • Click Next and then Finish.

2. Find your AVD's name by running emulator -list-avds.

3. Start the AVD with a writable file system. You will need to run this every time you start the emulator, it won't work if Expo starts it for you.

   emulator -avd your-avd-name -writable-system

4. Add entries to hosts so that gumroad.dev resolves to the host machine's IP address instead of localhost:

   adb root
   adb remount
   adb shell "echo '10.0.2.2 gumroad.dev' >> /etc/hosts; echo '10.0.2.2 api.gumroad.dev' >> /etc/hosts; echo '10.0.2.2 app.gumroad.dev' >> /etc/hosts; echo '10.0.2.2 minio.gumroad.dev' >> /etc/hosts"

You should now be able to load https://gumroad.dev in your browser. Once that works, you can run the app on the emulator.

Running locally

1. Install dependencies

   npm install

2. Make sure you have Gumroad running locally with the latest seed data (rails db:seed).

3. Start the app. Run one of:

   npm run android # run this only AFTER starting the rooted emulator as described above
   npm run ios

Configuring

The app will run without any custom credentials, but can be configured using environment variables. Copy .env.example to .env (gitignored) and edit the values — for example, swap the URLs and client ID to point at production.

Building for production

Use the Claude Code slash commands /build-app and /submit-app to build and submit to app stores.

Prerequisites

• 1Password CLI: Credentials are fetched automatically from 1Password. Install with arch -arm64 brew install 1password-cli, enable the desktop app integration (Settings → Developer → CLI), and sign in with op signin.
• Xcode: Required for iOS builds. The user must be signed into an Apple Developer account in Xcode (Settings → Accounts) with access to the correct team.
• JDK 17+: Required for Android builds (Gradle 9). Install with arch -arm64 brew install openjdk@17, then symlink:

  sudo ln -sfn /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk

• Android SDK: Required for local Android builds. Install Android Studio and complete the setup wizard to download the SDK.

Testing

E2E tests

E2E tests use Maestro. To run the tests:

1. Install Maestro:

   curl -fsSL "https://get.maestro.mobile.dev" | bash

2. Ensure you have the app running in either an iOS simulator or Android emulator.

3. Ensure you have Gumroad running locally with the latest seed data (rails db:seed).

4. For Android, route the local API and object storage ports through the emulator:

   adb reverse tcp:3000 tcp:3000
   adb reverse tcp:9000 tcp:9000

5. Run a test file:

   npm run e2e:ios .maestro/<test>.yaml
   npm run e2e:android .maestro/<test>.yaml

   The iOS suite excludes flows tagged android-only, such as flaky-network-recovery.yaml. Directly targeting one with the iOS command fails with an Android-only error.

Unit tests

Unit tests use Jest. To run the tests, use npm run test.

Release QA

Jest gates every PR, but it mocks the native layer (expo-av, PDF viewer, WebViews), so release candidates get a Maestro pass over the flows in .maestro/ — they cover the standing release checklist: audio playback (play, pause/resume, skip, background audio), tab navigation with buyer empty states, library purchased content, creator dashboard, creator analytics, Agent tab, payouts WebView, login, and logout.

Baseline (every release candidate, no spend)

Run the full .maestro/ suite on an iOS simulator and an Android emulator against a local Gumroad backend with seed data loaded (see E2E tests above). Maestro records a video of each run — keep the recordings as the release's evidence trail.

Big releases: on-demand real devices, pay per use

No standing device-cloud subscription. For big releases and releases carrying promised bug fixes:

• Android real hardware: AWS Device Farm pay-as-you-go ($0.17/device-minute) — a full flow pass costs a few dollars. Upload the release build plus the .maestro/ flows and run on a Samsung device.
• iOS real device or a manual recorded session: BrowserStack App Live, single month ($39), cancel after.

Is it a big release? Yes if any of: a native-layer change (playback, PDF viewer, navigation shell, WebView bridge), a store-listing or build-config change, or the release carries a bug fix that was promised to a user. Routine dependency bumps and web-only changes ship on the emulator baseline alone.

Still manual

Lock screen controls, biometrics prompts, and anything needing a physical sensor stay manual on a device in hand.