Releasing a Full App

This page takes a Catalyst app from a working debug build to a first release in Google Play internal testing and TestFlight. Follow it in order the first time. Later releases only need steps 3 to 7.

1. Prepare the app

  1. Deploy the web app over HTTPS.
  2. In config/config.json, set WEBVIEW_CONFIG.appId to your own reverse-DNS id (not com.example.), appName to the name under the icon, and url to the deployed address, for example https://shop.acme.com. The id cannot change after the first upload. If you leave the id or url unset, the first release in a terminal asks for them and saves your answers.
  3. Set the version in package.json, for example 1.0.0.
  4. Replace public/icon.png with your icon: square, opaque, at least 1024x1024 pixels.
  5. For iOS, sign in to Xcode with the Apple account that is in your company's developer team: Xcode > Settings > Accounts.

See Universal App Deployment for what each key does.

2. Create the store records

Google Play:

  1. In Play Console, choose Create app and fill in the name, language and the app or game and free or paid answers.
  2. Under Test and release > Testing > Internal testing, create a tester list with your own Google account.

App Store Connect:

  1. Under Certificates, Identifiers & Profiles on developer.apple.com, register an App ID with your appId as the bundle ID.
  2. In App Store Connect, choose Apps > + > New App and pick that bundle ID.
  3. For cloud signing in CI, create an App Store Connect API key with the Admin role under Users and Access > Integrations, and download the .p8.

3. Build the Android release

npm run android:release

In apps created before 1.2.0, run npm run buildApp:android -- --release. Run it in a terminal. The first time, answer yes to creating the upload key and no to "Has this app been uploaded to Google Play before". Then back up the key right away:

npx catalyst credentials:export android

Keep the printed value in a password manager. Without this key you cannot update the app.

The build writes three files to build-output/android/<version>-<build>/: <App>.aab, the bundle for Google Play, <App>.apk, the same release for test phones, and upload_certificate.pem. The APK will not install over a copy from Google Play, so uninstall that first.

4. Upload to Google Play internal testing

  1. In Play Console, open the app and go to Test and release > Testing > Internal testing, then Create new release.
  2. Accept Play App Signing when asked. Google keeps the app signing key, and your key becomes the upload key.
  3. Upload the .aab, add release notes, then review the release and roll it out.
  4. Open the opt-in link from the Testers tab on your phone and install the app from Google Play.

Play Console checks the bundle after upload. App bundle explorer lists the target API level and warns about native libraries that do not support 16 KB memory pages; Catalyst's own libraries are aligned, so a warning there points at a library your app added.

5. Build the iOS release

  1. Run npm run ios:release in a terminal (npm run buildApp:ios -- --release in apps created before 1.2.0).
  2. On a Mac signed in to Xcode, no signing files are needed. The build uses the App Store profile installed for the app when there is one, or signs with your Xcode account. The team comes from that profile or from Xcode. When Xcode has several teams, the build asks once which one to use, and a team read from Xcode is saved as ios.developmentTeam.
  3. For CI, put the signing files in credentials/ios/ and back them up with npx catalyst credentials:export ios. Building and Releasing a Catalyst iOS App has the details.

The IPA is in build-output/ios/<version>-<build>/.

6. Upload to TestFlight

  1. Open Transporter, sign in with your Apple account, drag in the IPA and choose Deliver.
  2. Wait for the email that the build has finished processing.
  3. In App Store Connect, open the app's TestFlight tab, create an internal group with yourself in it, and add the build.
  4. Install TestFlight on your iPhone and install the app from the invitation.

7. Check the installed apps

On a real phone from each store:

  • the app opens your production site, not a dev server or an error page
  • the name and icon on the home screen are right
  • the version and build number in Play Console and App Store Connect match build-output/<platform>/<version>-<build>/
  • sign-in, deep links, file pickers, the camera and notifications work, and their permission prompts appear
  • with the network off, the offline page shows

8. Set up CI

  1. Add CATALYST_ANDROID_CREDENTIALS and CATALYST_IOS_CREDENTIALS as repository secrets, from the two credentials:export commands above.
  2. Copy the workflow template from Native CI to .github/workflows/catalyst-native.yml.
  3. Push a v* tag, download the android-aab and ios-ipa artifacts, and upload them as in steps 4 and 6.

Next releases

Bump the version in package.json, run the two release scripts (or push a tag), and upload. The build number rises by itself, and the same upload key and signing files are used every time.

Framework contributors can also check the 16 KB alignment of a bundle locally with node scripts/native-release-check.mjs align <file.aab> from the Catalyst repository. App developers can rely on Play Console's checks.