Skip to content

README.md

Latest commit

 

History

History
104 lines (67 loc) · 11.2 KB

README.md

File metadata and controls

104 lines (67 loc) · 11.2 KB
Raw

Codemagic Patch

Discord   react-native-patch on npm   capacitor-patch on npm   npm downloads   GitHub Stars   Follow @codemagicio   LinkedIn

Codemagic Patch is a self-hosted over-the-air (OTA) update service for React Native and Capacitor apps. Ship JavaScript and web-asset changes straight to installed apps, with no app-store review for changes that live outside the native binary.

Evaluation quickstart

You have two options to try out Patch.

Local + simulator - Installs the stack locally and lets you deliver updates to the simulator, including to the included demo app.

Local + ngrok + device - Installs the stack locally, plus uses a free ngrok account so you can deliver updates to the app on your real device.

Local stack + simulator

Run the server on localhost, with a one-click local login. No OAuth account, ngrok account, or domain. You need Docker. This reaches the iOS Simulator, an Android emulator, and a USB-connected Android device. A phone on the network cannot reach it.

npm install -g @codemagic/patch-cli
cmpatch selfhost local-eval

When it finishes, the dashboard is at http://localhost:8080. Then run the guided demo. It builds a React Native storefront on a simulator or emulator, publishes a one-line fix, and lets you watch the running app install it:

cmpatch demo

The demo needs Node.js 22.20+, Yarn (via Corepack), and either Xcode with an iOS Simulator or an Android SDK with a running emulator. See the on-device demo. To connect your own app instead, see Quickstart: try it locally.

Local stack + ngrok + device

Run the real server, with sign-in, on your own machine, and reach it from any phone at the free https:// address your ngrok account comes with. You need Docker, a free ngrok account, and a GitHub, Bitbucket, or GitLab account to sign in with. No domain, DNS records, certificates, or open ports.

npm install -g @codemagic/patch-cli
cmpatch selfhost install --ngrok

The command finds your ngrok address, walks you through the OAuth app with that address filled in, installs the server, and points cmpatch at it. When it finishes, it prints the dashboard and the two values your app is configured with, both on the ngrok address:

App config key Value
CodemagicPatchApiUrl https://<address>
CodemagicPatchDownloadBaseUrl https://<address>/codemagic-patch

Connect your app

  • React Native: run cmpatch login, then cmpatch init from your project root, as the installer prints them. init creates one app per platform and writes the URLs and deployment keys into your native projects. Build a release build, then publish with cmpatch release-react. Guides: Native setup · First release.
  • Capacitor: install the SDK (@codemagic/capacitor-patch) in your app and the CLI (@codemagic/capacitor-patch-cli) globally. Sign in with cmpatch-capacitor login --server-url https://<address>, create one app per platform with cmpatch-capacitor app create, and copy each app's deployment key from cmpatch-capacitor deployment list. Put the two URLs and the keys in capacitor.config.ts (one block per platform), run npx cap sync, and build. Publish with cmpatch-capacitor release create. Guides: Native setup · First release.

This is for testing: ngrok's free plan carries 1 GB and 20,000 requests a month, and apps keep the address they were built with, so install on your own domain before you ship. See Install › ngrok.

Going to production

Install the server from your own machine. You need a host you can reach over SSH, two hostnames (one for the API and dashboard, one for artifact storage), and a GitHub, Bitbucket Cloud, or GitLab account for sign-in. The wizard asks for everything else, and offers to put Cloudflare or CloudFront in front of storage. Without a server or domain of your own, cmpatch selfhost install --fly deploys Patch onto Fly.io instead (see Install › Fly.io).

npm install -g @codemagic/patch-cli
cmpatch selfhost install

Then connect your app and publish a release:

React Native Capacitor
Connect the app cmpatch init cmpatch-capacitor app create, then capacitor.config.ts
Publish a release cmpatch release-react cmpatch-capacitor release create
Guides Native setup · First release Native setup · First release

Start with the Install guide for the server. Backups, restores, and upgrades also run from your machine, with cmpatch selfhost backup, restore, and upgrade (see Operations).

Documentation

The full documentation is at patch.codemagic.io/docs. Pages that differ between frameworks have a React Native / Capacitor switcher.

Topic Pages
Learn How it works · Core concepts · How delivery works · How Patch compares: React Native / Capacitor
Run the server Install · Cloudflare · CloudFront · Infrastructure · Ongoing maintenance
Integrate the SDK Native setup: React Native / Capacitor · Checking for updates · Applying updates · Manual control
Ship releases Dashboard · Releasing updates · Fingerprinting (React Native) · Binary versions (Capacitor) · Verify a test release · Preparing for production · Production control · Security and code signing · CI integration
Operate Operations · Analytics · Troubleshooting · FAQ
Reference SDK · cmpatch CLI · cmpatch-capacitor CLI · Configuration · Delivery protocol
Migrate From CodePush · From Expo Updates · From Appflow Live Updates
Release notes All components

Community and feedback

Your feedback helps us improve Codemagic Patch. Tell us what works well, what has been challenging, and what you would like to see next.