This release builds, runs and releases the Android and iOS apps from the CLI, without opening Android Studio or Xcode. The web runtime has no breaking changes. Universal apps should read the breaking changes below and the 1.1.x to 1.2.0 section of the Version Upgrades guide. After upgrading, run npm audit fix: the body-parser floor is raised to ^1.20.9.
One command to run, one to release
New apps have four scripts. npm run android and npm run ios check the toolchain and install what is missing after asking, start the dev server when nothing answers on NODE_SERVER_PORT, and build, install and open the app on an emulator, simulator or phone. Android also saves the app as a debug APK in build-output/android/debug/ that can be shared. npm run android:release writes a signed App Bundle, a signed APK and upload_certificate.pem to build-output/android/<version>-<build>/, and npm run ios:release writes a signed IPA and a zip of its dSYMs to build-output/ios/<version>-<build>/. The scripts run catalyst buildApp:android and catalyst buildApp:ios, with --release for the store builds, so older apps keep buildApp:<platform> and build a release with npm run buildApp:<platform> -- --release. setupEmulator:android and setupEmulator:ios still work and are no longer needed.
App config
A native app needs WEBVIEW_CONFIG.appId, appName and url. appId is the Android application id and the iOS bundle id, and android.packageName and ios.bundleIdentifier (then ios.appBundleId) win over it. url is the deployed site a release opens; debug builds load the dev server. New apps get appId and appName from the project name. A release run in a terminal asks once for an app id or website that is missing or a placeholder, and saves the answer to config/config.json.
Signing
Signing files live in credentials/android/ and credentials/ios/, which new apps keep out of git. The first Android release in a terminal creates one upload key per app after asking; back it up, because Google Play only accepts updates signed with it. npx catalyst credentials:export <platform> prints the folder as one value for the CATALYST_ANDROID_CREDENTIALS or CATALYST_IOS_CREDENTIALS CI secret. On a Mac signed in to Xcode, an iOS release signs with the Apple account or an installed App Store profile and needs no files; the order the build tries is in the iOS release guide. The version comes from package.json, and the build number is CATALYST_BUILD_NUMBER or the minutes since 2024-01-01 UTC. Android apps target API 36 and align their native libraries for 16 KB memory pages.
Breaking changes
- An iOS bundle id with an underscore fails with
NATIVE-010. Setios.bundleIdentifierto an id without one. - A release with a placeholder app id (any
com.example.id or a template id) fails withNATIVE-003. A release whose start URL islocalhost, a private or link-local address, a.localname or this machine fails withNATIVE-001, unlessWEBVIEW_CONFIG.allowPrivateHostistrue. Run in a terminal, the build asks for the value instead. - A debug build no longer installs on a connected phone by itself. A terminal run asks once where to run the app and remembers the answer in
.catalyst/local.json; without a terminal the emulator or simulator is used. Pass--devicefor the phone. - The first debug build rewrites
config/config.jsononce: a value equal to this machine's LAN address, and a privateLOCAL_IPthatNODE_SERVER_HOSTNAMEalso holds, go back tolocalhost. Each change is printed. It never runs for a release, in CI or withallowPrivateHost: true. - Keystore passwords in
android.keystoreConfigandandroid.keystoreare no longer used. Apps that uploaded a build signed with the keystore shipped in the template, or with a key generated by an earlier release build, need an upload key reset in Play Console.
create-catalyst-app
New apps get a new starter page, an animated HTML splash screen that is on by default (splashScreen.minDuration 7000), a restyled offline page, a placeholder public/icon.png, and a server/index.js with an empty stub for preServerInit and each per-request hook. Their .gitignore covers credentials/, .catalyst/ and build-output/.
Fixes
MetaTagwaits for asplit()route's chunk before it replaces the head tags, so the server's tags are no longer removed before the route'ssetMetaDatais available.- Startup warns when
server/index.jsputs a lifecycle hook insideexport default { ... }, where Catalyst never calls it. Export each hook by name. npm run startprints a hint whenNODE_SERVER_HOSTNAMEis not an address of this machine.