Hot Updater - Self-hosted OTA updates for React Native

Deploy Hot Updater on Cloudflare with D1, R2, and a Worker, then connect your app.

Overview

Use this preset to provision an OTA server on Cloudflare. For a new app, start with Choose infrastructure. Provision the provider resources here, then connect your app with the verified URL and key.

Prerequisites

You need the following resources and access. An AI agent can prepare missing resources through its available provider tools.

Node.js: The CLI requires 20.19+. Agent setup uses a client-key helper that requires Node 22.18+ or Node 24+; prepare it before provisioning resources.
Cloudflare Account: Sign up at Cloudflare if you don't have one.
Cloudflare D1 API Token: Create an API Token at https://dash.cloudflare.com/{your-account-id}/api-tokens with D1 Edit permission.

Step 1: Install required packages

Complete Install packages in the React Native project before running init or an agent scaffold. Install the CLI, React Native SDK, and the build adapter that matches your app, then install this provider:

npm install @hot-updater/cloudflare --save-dev

An agent can perform these steps after inspecting the app's package manager and build configuration.

Step 2: Configure Cloudflare

Choose how to set up Cloudflare:

Install the Hot Updater skill, then ask your coding agent:

$hot-updater Set up infrastructure on Cloudflare for this project.

The agent inspects your app, discovers existing configuration and resources, and asks only for missing choices or access. It uses hot-updater agent infra setup to generate the deployment templates, then applies and verifies them with available provider tools. If authentication is needed, sign in through the provider or save credentials in a local ignored file; do not paste secrets into the conversation. See Agent Infrastructure for setup and resume.

After setup, review the local configuration. Interactive init writes the settings below to .env.hotupdater; an agent merges the needed settings into your project. Resource names, IDs, and R2 privacy are persisted for deterministic reruns. API and R2 credentials are persisted only when you consent.

HOT_UPDATER_CLOUDFLARE_ACCOUNT_ID=your-account-id
HOT_UPDATER_CLOUDFLARE_R2_BUCKET_NAME=your-r2-bucket-name
HOT_UPDATER_CLOUDFLARE_R2_PRIVATE=true
HOT_UPDATER_CLOUDFLARE_D1_DATABASE_ID=your-d1-database-id
HOT_UPDATER_CLOUDFLARE_D1_DATABASE_NAME=your-d1-database-name
HOT_UPDATER_CLOUDFLARE_WORKER_NAME=your-worker-name
HOT_UPDATER_API_KEY=your-api-key
# Included only when credential persistence is approved:
HOT_UPDATER_CLOUDFLARE_API_TOKEN=your-api-token
HOT_UPDATER_CLOUDFLARE_R2_ACCESS_KEY_ID=your-r2-access-key-id
HOT_UPDATER_CLOUDFLARE_R2_SECRET_ACCESS_KEY=your-r2-secret-access-key

Managed init reuses HOT_UPDATER_API_KEY when supplied or creates an API key, registers it in D1, and persists the plaintext value locally. Send this API key in the app's x-api-key request header. To list, add, or revoke keys later, run hot-updater api-key from the app directory.

Provider credentials from .env.hotupdater are not included in your app bundle unless you explicitly configure that behavior. The API key is the exception: add HOT_UPDATER_API_KEY to your React Native build-time configuration as shown in Set up your app, but never add the Cloudflare API or R2 credentials.

See Security.

Optional: Bundle signing

Managed Cloudflare init does not create or enable a signing key. After provisioning the OTA infrastructure, configure local PEM, AWS KMS, or Google Cloud KMS signing, embed its public key in a native release, and only then deploy signed bundles. Storage and database selection does not constrain the signer. KMS signing runs directly in the protected deploy job; no Worker proxy is required. A compatible signing service can also be used through remoteSigning.

Step 3: Add HotUpdater to your project

After provisioning, record these outputs for Set up your app:

Output	Value
Client base URL	`https://<your-worker-name>.<your-subdomain>.workers.dev`
Client request header	`x-api-key`
Client API key	The saved `HOT_UPDATER_API_KEY` in your ignored `.env.hotupdater`
Deploy configuration	`hot-updater.config.ts` and the selected provider resources

Use the actual URL returned by deployment. Configure the SDK and native bundle loader through Set up your app, using the selected build adapter and the same update strategy as hot-updater.config.ts. Only the client API key belongs in the mobile app's build-time configuration; provider credentials stay in the deploy environment.

The managed Cloudflare runtime exposes /version publicly. OTA update checks, Insights ingestion, and Remote Config fetches require x-api-key: $HOT_UPDATER_API_KEY. Internally, the Worker runs the insights(), apiKeys(), and remoteConfig() plugins and mounts only handlers.client. Admin routes, including Insights queries and Remote Config publishing, are not mounted on the public worker URL.

Generated configuration and operations

Init generates hot-updater.config.ts with your Cloudflare storage and database, and plugins: the server plugins the managed Worker runs, apiKeys(), insights(), and remoteConfig(), imported from hot-updater/plugins. The CLI and the Console reach D1 and R2 through these settings and run the same plugins as the Worker. The managed Worker runs these official plugins only; to run other server plugins, use a custom server.

On a rerun, init updates storage, database, and plugins in the existing file and keeps your other settings, including a wrapped build such as withSentry(bare()). When it cannot edit hot-updater.config.ts, such as a config that a function returns, it leaves the file unchanged and prints the storage, database, and plugins lines to add.

hot-updater.config.ts

import { bare } from "@hot-updater/bare";
import { d1Database, r2Storage } from "@hot-updater/cloudflare";
import { apiKeys, insights, remoteConfig } from "hot-updater/plugins";
import { defineConfig } from "hot-updater";
import { existsSync } from "node:fs";

if (existsSync(".env.hotupdater")) {
  process.loadEnvFile(".env.hotupdater");
}

export default defineConfig({
  build: bare({ enableHermes: true }),
  storage: r2Storage({
    bucketName: process.env.HOT_UPDATER_CLOUDFLARE_R2_BUCKET_NAME!,
    accountId: process.env.HOT_UPDATER_CLOUDFLARE_ACCOUNT_ID!,
    credentials: {
      accessKeyId: process.env.HOT_UPDATER_CLOUDFLARE_R2_ACCESS_KEY_ID!,
      secretAccessKey: process.env.HOT_UPDATER_CLOUDFLARE_R2_SECRET_ACCESS_KEY!,
    },
  }),
  database: d1Database({
    databaseId: process.env.HOT_UPDATER_CLOUDFLARE_D1_DATABASE_ID!,
    accountId: process.env.HOT_UPDATER_CLOUDFLARE_ACCOUNT_ID!,
    cloudflareApiToken: process.env.HOT_UPDATER_CLOUDFLARE_API_TOKEN!,
  }),
  plugins: [apiKeys(), insights(), remoteConfig()],
  updateStrategy: "appVersion", // or "fingerprint"
});

The persisted HOT_UPDATER_CLOUDFLARE_R2_PRIVATE value replays the privacy choice on later init runs.

Step 4: If you use Expo, add the config plugin

Follow the Expo path in Set up your app. It applies the config plugin and generates the native integration. For DOM components, continue with Expo DOM components.

Step 5: Add native code

For Bare or Rock, follow the Android and iOS instructions in Set up your app. Keep the integration appropriate to your React Native version and rebuild the native app after changing it.

Upgrade infrastructure

With the Hot Updater skill attached, ask your agent:

$hot-updater Upgrade this project's existing Cloudflare server infrastructure.

The agent discovers the existing deployment, uses hot-updater agent infra upgrade, and reads the applicable version files before changing resources. It applies pending changes and verifies the server with doctor. See Upgrade an existing server for the workflow or Doctor for terminal instructions.

For server templates to apply with your own deployment tooling, use hot-updater infra scaffold --provider cloudflare. See Infrastructure Templates.

Verifying the setup

Confirm the selected Cloudflare resources and the deployed client base URL.
From the React Native project, check the server and native integration:
```
npx hot-updater doctor --server-base-url <client-base-url> --json
```
Doctor checks the public /version endpoint. It does not prove an authenticated update download or application.
Complete Test an OTA update on a release build. Verify that the app downloads and runs the changed code, then survives a restart.

An agent should report the selected resources, verified URL, configuration file paths and verification result. Report a missing access, billing or native-build prerequisite explicitly instead of marking an untested installation complete.

Host the Console

The console can run on Cloudflare Workers, Vercel, Netlify, or Docker/Node. Workers uses native D1/R2 bindings; Node hosts use D1 API and R2 S3 credentials. See the console hosting matrix and Cloudflare from Node.

Cloudflare Provider