HotupdaterHot Updater
Self Hosting (Managed)

AWS S3 Storage + Lambda@Edge Function

This guide walks you through setting up `hot-updater` with AWS S3 Storage and Lambda@Edge Function in a React Native project. You'll configure the environment, install required packages, and initialize AWS for seamless updates.

Prerequisites

Before you begin, make sure the following are ready:

  • Node.js: Version 20 or later is recommended.
  • AWS Account: Sign up at AWS if you don't have one.
  • AWS CLI: Install the AWS CLI and configure your credentials.

Required AWS Permissions

Hot Updater requires specific AWS IAM permissions for setup and ongoing usage:

1. Initialization (One-Time Setup)

Used for hot-updater init:

  • AmazonS3FullAccess: Create and read S3 buckets.
  • AWSLambda_FullAccess: Create and update Lambda functions.
  • CloudFrontFullAccess: Manage CloudFront distributions.
  • IAMFullAccess: Create IAM roles for Lambda@Edge.
  • SSMFullAccess: Create Access to SSM Parameters for storing CloudFront key pairs.

2. Ongoing Usage

Used for hot-updater deploy and hot-updater console:

  • AmazonS3FullAccess: Manage bundles and metadata in the S3 bucket.

For ongoing usage, create a separate access token with limited permissions.

Step 1: Install Required Packages

Run the following command to install dependencies:

npm install hot-updater --save-dev

Step 2: Configure AWS

Run the initialization script to start the interactive setup process. Use the following command with your preferred package manager:

npx hot-updater init

Once the setup is complete, a .env file will be generated containing the following keys:

# This key was generated via SSO login and may expire. Update it with an S3FullAccess and CloudFrontFullAccess key.
HOT_UPDATER_S3_ACCESS_KEY_ID=your-access-key-id
# This key was generated via SSO login and may expire. Update it with an S3FullAccess and CloudFrontFullAccess key.
HOT_UPDATER_S3_SECRET_ACCESS_KEY=your-secret-access-key

HOT_UPDATER_S3_BUCKET_NAME=your-s3-bucket-name
HOT_UPDATER_S3_REGION=your-region

If you're not using the react-native-dotenv solution, the tokens from your .env file will not be included in your app bundle and are therefore not exposed to risks. However, if you're still concerned,

please refer to the article below for more details: Security

Step 3: Generated Configurations

During the initialization process, the following file is automatically generated:

  • hot-updater.config.ts: This file contains the configuration settings for integrating AWS with your project.
hot-updater.config.ts

import { bare } from "@hot-updater/bare";
import { s3Storage, s3Database } from "@hot-updater/aws";
import { defineConfig } from "hot-updater";
import { config } from "dotenv";

config({ path: ".env.hotupdater" });

const commonOptions = {
  bucketName: process.env.HOT_UPDATER_S3_BUCKET_NAME!,
  region: process.env.HOT_UPDATER_S3_REGION!,
  credentials: {
    accessKeyId: process.env.HOT_UPDATER_S3_ACCESS_KEY_ID!,
    secretAccessKey: process.env.HOT_UPDATER_S3_SECRET_ACCESS_KEY!,
  },
};

export default defineConfig({
  build: bare({ enableHermes: true }),
  storage: s3Storage(commonOptions),
  database: s3Database({
    ...commonOptions,
    cloudfrontDistributionId: process.env.HOT_UPDATER_CLOUDFRONT_DISTRIBUTION_ID!,
  }),
});

Step 4: Change .env file (Optional)

By this point, the .env file should already be created. The token inside was generated when you ran the hot-updater init command.

The token may have excessive permissions due to infrastructure setup or expire if SSO was used.

To avoid issues, update it with a permanent token with S3FullAccess and CloudFrontFullAccess.

.env.hotupdater
HOT_UPDATER_S3_ACCESS_KEY_ID=your-access-key-id
HOT_UPDATER_S3_SECRET_ACCESS_KEY=your-secret-access-key

Step 5: Add HotUpdater to Your Project

The HotUpdater component wraps your application, enabling seamless delivery of updates and fallback UI during updates. Follow these steps to integrate it into your App.tsx:

App.tsx
import { HotUpdater, getUpdateSource } from "@hot-updater/react-native";

function App() {
  return (
    <View>
      <Text>Hello World</Text>
    </View>
  );
}

export default HotUpdater.wrap({
  source: getUpdateSource("https://<your-cloudfront-distribution-url>/api/check-update", { 
    updateStrategy: "appVersion", // or "fingerprint"
  }), 
  requestHeaders: {
    // if you want to use the request headers, you can add them here
  },
  fallbackComponent: ({ progress, status }) => (
    <View
      style={{
        flex: 1,
        padding: 20,
        borderRadius: 10,
        justifyContent: "center",
        alignItems: "center",
        backgroundColor: "rgba(0, 0, 0, 0.5)",
      }}
    >
      {/* You can put a splash image here. */}

      <Text style={{ color: "white", fontSize: 20, fontWeight: "bold" }}>
        {status === "UPDATING" ? "Updating..." : "Checking for Update..."}
      </Text>
      {progress > 0 ? (
        <Text style={{ color: "white", fontSize: 20, fontWeight: "bold" }}>
          {Math.round(progress * 100)}%
        </Text>
      ) : null}
    </View>
  ),
})(App);

Step 6: Add Babel / Re.Pack / Expo Plugin to Your Project

In this step, you will configure Babel to set the bundle ID at build time. This is necessary for integrating the hot-updater plugin into your project.

Add the following to your babel.config.js file:

babel.config.js
module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    'hot-updater/babel-plugin', 
  ],
};

Add the following to your rspack.config.mjs file:

npm install -updater/repack
rspack.config.mjs
import { HotUpdaterPlugin } from "@hot-updater/repack";

export default {
  // ...
  plugins: [
    new Repack.RepackPlugin(),
    new HotUpdaterPlugin() 
  ],
};

Add the plugin to your app.json file as shown below:

app.json
{
  "expo": {
    "plugins": [
      [
        "@hot-updater/react-native",
        {
          "channel": "production"
        }
      ]
    ]
  }
}
npx expo prebuild

Run the following command to customize your Babel configuration:

npx expo customize babel.config.js

Add the following to your babel.config.js file:

babel.config.js
module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    'hot-updater/babel-plugin', 
  ],
};

This process automatically generates the code that needs to be added in Step 6.

Step 7: Add Native Code

To complete the integration of hot-updater, you'll need to add native code modifications for both Android and iOS platforms. This step ensures the hot-updater can interact with your app's underlying framework to apply updates seamlessly.

Android

android/app/src/main/java/com/<your-app-name>/MainApplication.kt
package com.hotupdaterexample

import android.app.Application
import com.facebook.react.PackageList
import com.facebook.react.ReactApplication
import com.facebook.react.ReactHost
import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
import com.hotupdater.HotUpdater

class MainApplication : Application(), ReactApplication {

override val reactHost: ReactHost by lazy {
  getDefaultReactHost(
    context = applicationContext,
    packageList =
      PackageList(this).packages.apply {
        // Packages that cannot be autolinked yet can be added manually here, for example:
        // add(MyReactNativePackage())
      },
    jsBundleFilePath = HotUpdater.getJSBundleFile(applicationContext), 
  )

}

override fun onCreate() {
  super.onCreate()
  loadReactNative(this)
}
}
android/app/src/main/java/com/<your-app-name>/MainApplication.kt
package com.hotupdaterexample

import android.app.Application
import com.facebook.react.PackageList
import com.facebook.react.ReactApplication
import com.facebook.react.ReactHost
import com.facebook.react.ReactNativeHost
import com.facebook.react.ReactPackage
import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.load
import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
import com.facebook.react.defaults.DefaultReactNativeHost
import com.facebook.react.soloader.OpenSourceMergedSoMapping
import com.facebook.soloader.SoLoader
import com.hotupdater.HotUpdater 

class MainApplication : Application(), ReactApplication {

  override val reactNativeHost: ReactNativeHost =
      object : DefaultReactNativeHost(this) {
        override fun getPackages(): List<ReactPackage> =
            PackageList(this).packages.apply {
              // Packages that cannot be autolinked yet can be added manually here, for example:
              // add(MyReactNativePackage())
            }

        override fun getJSMainModuleName(): String = "index"

        override fun getUseDeveloperSupport(): Boolean = BuildConfig.DEBUG

        override val isNewArchEnabled: Boolean = BuildConfig.IS_NEW_ARCHITECTURE_ENABLED
        override val isHermesEnabled: Boolean = BuildConfig.IS_HERMES_ENABLED

        override fun getJSBundleFile(): String? {  
          return HotUpdater.getJSBundleFile(applicationContext)  
        }  
      }

  override val reactHost: ReactHost
    get() = getDefaultReactHost(applicationContext, reactNativeHost)

  override fun onCreate() {
    super.onCreate()
    SoLoader.init(this, OpenSourceMergedSoMapping)
    if (BuildConfig.IS_NEW_ARCHITECTURE_ENABLED) {
      // If you opted-in for the New Architecture, we load the native entry point for this app.
      load()
    }
  }
}
android/app/src/main/java/com/<your-app-name>/MainApplication.java

package com.hotupdaterexample;

import android.app.Application;
import com.facebook.react.PackageList;
import com.facebook.react.ReactApplication;
import com.facebook.react.ReactNativeHost;
import com.facebook.react.ReactPackage;
import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint;
import com.facebook.react.defaults.DefaultReactNativeHost;
import com.facebook.soloader.SoLoader;
import java.util.List;
import com.hotupdater.HotUpdater;  

public class MainApplication extends Application implements ReactApplication {

private final ReactNativeHost mReactNativeHost =
    new DefaultReactNativeHost(this) {
      @Override
      public boolean getUseDeveloperSupport() {
        return BuildConfig.DEBUG;
      }

      @Override
      protected List<ReactPackage> getPackages() {
        @SuppressWarnings("UnnecessaryLocalVariable")
        List<ReactPackage> packages = new PackageList(this).getPackages();
        // Packages that cannot be autolinked yet can be added manually here, for example:
        return packages;
      }

      @Override
      protected String getJSMainModuleName() {
        return "index";
      }

      @Override
      protected String getJSBundleFile() {  
          return HotUpdater.Companion.getJSBundleFile(this.getApplication().getApplicationContext());  
      }  

      @Override
      protected boolean isNewArchEnabled() {
        return BuildConfig.IS_NEW_ARCHITECTURE_ENABLED;
      }

      @Override
      protected Boolean isHermesEnabled() {
        return BuildConfig.IS_HERMES_ENABLED;
      }
    };

@Override
public ReactNativeHost getReactNativeHost() {
  return mReactNativeHost;
}

@Override
public void onCreate() {
  super.onCreate();
  SoLoader.init(this, /* native exopackage */ false);

  if (BuildConfig.IS_NEW_ARCHITECTURE_ENABLED) {
    // If you opted-in for the New Architecture, we load the native entry point for this app.
    DefaultNewArchitectureEntryPoint.load();
  }
  ReactNativeFlipper.initializeFlipper(this, getReactNativeHost().getReactInstanceManager());
}
}

iOS

ios/<your-app-name>/AppDelegate.swift
import UIKit
import React
import React_RCTAppDelegate
import ReactAppDependencyProvider
import HotUpdater

@main
class AppDelegate: RCTAppDelegate {
  override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    self.moduleName = "HotUpdaterExample"
    self.dependencyProvider = RCTAppDependencyProvider()

    // You can add your custom initial props in the dictionary below.
    // They will be passed down to the ViewController used by React Native.
    self.initialProps = [:]

    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }

  override func sourceURL(for bridge: RCTBridge) -> URL? {
    self.bundleURL()
  }

  override func bundleURL() -> URL? {
#if DEBUG
    RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
#else
    Bundle.main.url(forResource: "main", withExtension: "jsbundle") 
    HotUpdater.bundleURL() 
#endif
  }
}
ios/<your-app-name>/AppDelegate.mm
#import "AppDelegate.h"
#import <HotUpdater/HotUpdater.h>
#import <React/RCTBundleURLProvider.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  self.moduleName = @"HotUpdaterExample";
  // You can add your custom initial props in the dictionary below.
  // They will be passed down to the ViewController used by React Native.
  self.initialProps = @{};

  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
{
  return [self bundleURL];
}

- (NSURL *)bundleURL
{
#if DEBUG
  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
#else
  return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"]; 
  return [HotUpdater bundleURL]; 
#endif
}

@end

Verifying the Setup

  1. Check your AWS dashboard for the newly created bucket, Lambda@Edge function, and CloudFront distribution.
  2. Test the HotUpdater integration in your React Native app.

You're all set! 🎉 Start using hot-updater with AWS for seamless updates in your React Native app.

This document simplifies the initialization process, making it easy for developers to get started with minimal friction.