v1.2.1Latest

Native builds that just work.

Build, run and release the Android and iOS apps from the CLI, without opening Android Studio or Xcode, plus openInBrowser and the X-App-Info header. Everything since 1.1.0.

npm run android and npm run ios. The toolchain sets itself up after asking.

npm run android:release writes a signed AAB and APK. iOS writes a signed IPA.

Everything since 1.1.0, from 1.2.0 and 1.2.1. The web runtime has no breaking changes. Universal apps should read the upgrade guide before upgrading.

01 / Try it

Two commands for each platform.

TerminalBuilds, installs and opens the app
npm run android
npm run ios
TerminalSigned store builds in build-output/
npm run android:release
npm run ios:release

Older apps keep buildApp:<platform> and build a release with npm run buildApp:<platform> -- --release. Full setup: Universal App Deployment and the upgrade guides from 1.1.x to 1.2.0 and 1.2.0 to 1.2.1.

02 / What's new

New since 1.1.0.

No Android Studio, no Xcode

npm run android and npm run ios check the toolchain and install what is missing after asking, start the dev server when nothing answers, and open the app on an emulator, simulator or phone. Android also saves a debug APK in build-output/android/debug/ that you can share.

Store builds, one command

npm run android:release writes a signed App Bundle, a signed APK and upload_certificate.pem. npm run ios:release writes a signed IPA and a zip of its dSYMs. A Mac signed in to Xcode needs no signing files, and CI needs one secret per platform from catalyst credentials:export.

03 / Goodbye, hello

Goodbye keystore passwords in config, hello credentials/.

Signing files live in credentials/android/ and credentials/ios/, which new apps keep out of git, and the passwords in android.keystoreConfig are no longer used. If you uploaded a build signed with the keystore that shipped in the template, or with a key an earlier release build generated, ask for an upload key reset in Play Console.

04 / Also new

Smaller things, sorted.

  • useIntent() adds openInBrowser(url), which opens an http or https link in the default browser, or in the app that owns the link.
  • The Android and iOS apps send WEBVIEW_CONFIG.appInfo to your server in an X-App-Info request header.
  • iOS with edgeToEdge.enabled no longer adds the safe-area insets itself, matching Android. Pad the page with useSafeArea(); content that relied on the automatic inset moves up.
  • New apps get a new starter page, the animated HTML splash screen on by default, a restyled offline page and a placeholder public/icon.png.
  • The template's server/index.js exports a stub for preServerInit and each per-request hook, and startup warns when a hook sits inside export default {}, where it is never called.
  • Android apps target API 36 and align their native libraries for 16 KB memory pages.
  • MetaTag waits for a split() route's chunk, so the server's head tags stay until the route's setMetaData is ready.
  • Debug builds on a physical iPhone reach the dev server, with one Keychain prompt.
  • Android AI system prompts without attachment components have regression tests in CI.

The three changes at the top of this list are new in 1.2.1. Everything else on this page first shipped in 1.2.0 on 13 November.

Thank you.

Catalyst 1.2.1 was built by these people.

Questions or ideas? Find us on Discord, X and GitHub Discussions.

Full release notes
  • useIntent() adds openInBrowser(url), which opens a link outside the WebView: in the default browser, or in the app that owns the link when one is installed. Only http and https URLs are accepted; any other scheme fails with an error.
  • The Android and iOS apps send WEBVIEW_CONFIG.appInfo in an X-App-Info request header, next to the X-Safe-Area-* headers. The header is left out when appInfo is empty.
  • iOS: with edgeToEdge.enabled, the WebView no longer adds the safe-area insets itself, matching Android. Pages draw under the status bar and home indicator, so pad them with useSafeArea(). Apps that relied on the automatic inset will see their content move up.