Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Building and Publishing

Building for Android and iOS

Set up Android Studio and Xcode, run Ionic apps on emulators and real devices, use live reload, create debug and release builds, and understand signing and build variants.

So far the app ran in a browser. To put it on a phone you build native projects with the platform tools: Android Studio (Gradle) for Android and Xcode for iOS. Capacitor does not hide these tools; it prepares the projects and you use the IDEs to run, debug and release. This lesson walks through the toolchain, the run commands, debugging and the first look at signing.

What you need

Android iOS
Operating system Windows, macOS or Linux macOS only
IDE Android Studio Xcode (from the Mac App Store)
Language runtime JDK (bundled with Android Studio) Swift toolchain (in Xcode), CocoaPods or Swift Package Manager
Emulator Android Virtual Device (AVD) iOS Simulator
Store account Google Play Console (one-time fee) Apple Developer Program (yearly fee)

You cannot build an iOS app on Windows or Linux. Teams without a Mac use a cloud build service (for example Ionic Appflow or other CI providers with macOS runners).

The build loop

flowchart LR
  A["Edit web code"] --> B["npm run build"]
  B --> C["npx cap sync"]
  C --> D["npx cap run android / ios"]
  D --> E["App on emulator or phone"]
  E -->|"change code"| A

Real commands, read-only:

Terminal
npm run build
npx cap sync
npx cap run android          # pick a device or emulator from the list
npx cap run ios              # needs a Mac; pick a simulator or device
npx cap open android         # open the project in Android Studio
npx cap open ios             # open the workspace in Xcode

Live reload

Rebuilding for every change is slow. With live reload, the native app loads your dev server over the network and refreshes when you save:

Terminal
npx cap run android -l --external

The phone and the computer must be on the same Wi-Fi network. This temporarily sets server.url in the native project, so always check that it is gone in release builds. Plugin changes (anything native) still need a rebuild.

Debugging

  • Android: open chrome://inspect in Chrome, pick your device and inspect the web view like a normal page. Logcat in Android Studio shows native logs.
  • iOS: enable "Web Inspector" in Safari's advanced settings on the device, then use Safari's Develop menu. Xcode's console shows native logs.
  • console.log output also appears in the native log, which helps when you cannot attach an inspector.

Many problems are native, not web: a missing permission string, a plugin that was not synced, a minimum OS version. Read the native log first.

Debug and release builds

Debug Release
Purpose development store or testers
Optimization none minified, optimized
Signing automatic debug key your own key
Web view inspectable yes usually not

Create a release build in a repeatable way:

Terminal
# Android: from the project root
npm run build && npx cap sync android
cd android
./gradlew bundleRelease        # an .aab for Google Play
./gradlew assembleRelease      # an .apk for direct installs

On iOS, choose "Any iOS Device" in Xcode and use Product, Archive, then distribute through the Organizer.

Signing

Both stores require every app to be signed, which proves that updates come from the same author.

  • Android: you create a keystore file with a key. Newer apps use Play App Signing: Google keeps the real signing key, and you sign uploads with an upload key. If you lose a classic signing key, you can never update the app. Back up the keystore and its passwords in a password manager, and never commit them to Git.
  • iOS: certificates and provisioning profiles tie the app, the developer and the devices together. Xcode's "Automatically manage signing" handles most of it for development.

Keep keystores, certificates and passwords out of the repository. Inject them in CI through secret variables, and add *.keystore and *.jks to .gitignore.

Versions

Each release needs a human version and a machine number:

  • Android: versionName ("1.4.0") and versionCode (an integer that must increase on every upload).
  • iOS: CFBundleShortVersionString ("1.4.0") and CFBundleVersion (the build number, which must increase within a version).

Automate the bump so you never upload a duplicate.

JS A version bump helper

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Checking the native config

Before a release it is worth validating the things that cause rejections. This stand-in checks a config object the way a CI step might.

JS A pre-release checklist script

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which operating system is required to build an iOS app locally?

    Xcode only runs on macOS, so iOS builds need a Mac or a cloud macOS runner.
  2. 2. You changed only TypeScript code. What is the fastest way to see it on a device?

    Live reload serves your dev server to the app, so web changes show up on save.
  3. 3. What happens if you lose the signing key of a classic Android app?

    Updates must be signed with the same key, which is why keystores must be backed up securely.
  4. 4. What must be true of Android versionCode on each upload?

    The store rejects an upload whose versionCode is not higher than previous ones.

Summary

  • Android Studio and Xcode build the native projects; Capacitor prepares them with sync.
  • Live reload speeds web iteration; native changes need a rebuild.
  • Debug with Chrome inspect or Safari Web Inspector and read native logs.
  • Release builds are signed: protect keystores and certificates.
  • Version names are for people; version codes and build numbers must always increase.

Next: App Icons, Splash Screens and Permissions