Getting Started

Learn how to set up Turbopush and ship your first OTA update to a React Native or Expo app in minutes.

Welcome to Turbopush! This guide will teach you how to do the initial Turbopush setup and perform your first release.

Want to test immediately?

We have a pre-built Expo example app ready for you to test OTA updates in minutes, without any setup. Just scan a QR code and start testing!

1. CLI Installation

First, install the Turbopush CLI in your project:

npm install --save-dev @turbopush/cli

yarn add --dev @turbopush/cli

pnpm add --dev @turbopush/cli

Verify the installation was successful:

npx turbopush --version

yarn turbopush --version

pnpm turbopush --version

2. Account Creation

If you don't have an account yet, create one at https://app.turbopush.org/sign-up.

3. Authentication

To start using Turbopush, you need to log in:

npx turbopush login

yarn turbopush login

pnpm turbopush login

This command will:

Open your browser for authentication
Generate an access key
Prompt you to paste the key in the terminal

To verify you're logged in:

npx turbopush whoami

yarn turbopush whoami

pnpm turbopush whoami

3.1 Set your default organization

npx turbopush org set <organization-slug>

yarn turbopush org set <organization-slug>

pnpm turbopush org set <organization-slug>

If you don't know your organization slug, you can list all your organizations with:

npx turbopush org list

yarn turbopush org list

pnpm turbopush org list

4. Registering Your Application

Create separate apps for iOS and Android, this ensures each platform has appropriate update packages.

iOS

npx turbopush app add MyApp-iOS --appSlug myapp-ios

yarn turbopush app add MyApp-iOS --appSlug myapp-ios

pnpm turbopush app add MyApp-iOS --appSlug myapp-ios

Android

npx turbopush app add MyApp-Android --appSlug myapp-android

yarn turbopush app add MyApp-Android --appSlug myapp-android

pnpm turbopush app add MyApp-Android --appSlug myapp-android

The appSlug is used to identify the app in the CLI and API for publishing and managing releases. If not provided, the slug will be generated from the app name.

After creating the app

The command will return deployment keys for Staging and Production. Write down these keys, you'll need them to configure your React Native app, example:

┌────────────┬─────────────────────────────────────┐
│ Name       │ Deployment Key                      │
├────────────┼─────────────────────────────────────┤
│ Production │ dk_19ffa8fc2a91f2cd9afb3bfecafef06d │
├────────────┼─────────────────────────────────────┤
│ Staging    │ dk_5g5dc7aa6197c1f292cd12ca28f39bb3 │
└────────────┴─────────────────────────────────────┘

5. SDK Configuration

Installation

npm install --save @turbopush/react-native-code-push

yarn add @turbopush/react-native-code-push

pnpm add @turbopush/react-native-code-push

iOS Setup

Run cd ios && pod install && cd .. to install all the necessary CocoaPods dependencies.
Change bundleUrl on AppDelegate file.

Add an import statement for the CodePush headers;

Find the following line of code, which sets the source URL for bridge for production release and replace it with the following line;

import React
import CodePush

override func bundleURL() -> URL? {
#if DEBUG
   RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
#else
  Bundle.main.url(forResource: "main", withExtension: "jsbundle") 
  CodePush.bundleURL() 
#endif
}

Add the CodePushDeploymentKey key (generated in the create app step):

<key>CodePushDeploymentKey</key>
<string>YOUR_IOS_DEPLOYMENT_KEY</string>

Certifies that your deployment_target is 15.5 or higher:

platform :ios, '15.5'

Android Setup

Add this line at the end of the file:

apply from: "../../node_modules/@turbopush/react-native-code-push/android/codepush.gradle"

Update the MainApplication file to use CodePush via the following changes:

For React Native 0.76 and above:

import com.facebook.react.ReactHost
import com.facebook.soloader.SoLoader
import com.microsoft.codepush.react.CodePush 

class MainApplication : Application(), ReactApplication {
    override val reactNativeHost: ReactNativeHost =
      object : DefaultReactNativeHost(this) {
          override fun getJSBundleFile(): String { 
            return CodePush.getJSBundleFile()  
          } 
    };

    override fun onCreate() {
      super.onCreate()
      val deploymentKey = getString(R.string.CodePushDeploymentKey) 
      CodePush.getInstance(deploymentKey, this, BuildConfig.DEBUG) 
      loadReactNative(this)
    }
}

Add the CodePushDeploymentKey key (generated in the create app step):

<string name="CodePushDeploymentKey">YOUR_ANDROID_DEPLOYMENT_KEY</string>

Basic JavaScript configuration

import codePush from "@turbopush/react-native-code-push"; 

const App = () => {
  // Your app component
};

export default App; 
export default codePush(App);

For advanced configuration, refer to the JavaScript API Reference.

6. First Release

Creating a Release (React Native)

For React Native, use the specific command that automatically generates the bundle:

npx turbopush release-react myapp-ios ios -t "1.0.0"

yarn turbopush release-react myapp-ios ios -t "1.0.0"

pnpm turbopush release-react myapp-ios ios -t "1.0.0"

npx turbopush release-react myapp-android android -t "1.0.0"

yarn turbopush release-react myapp-android android -t "1.0.0"

pnpm turbopush release-react myapp-android android -t "1.0.0"

Important release parameters

Parameter	Required	Default	Description
`--deploymentName`, `-d`	No	`Staging`	Specifies the deployment
`--description`, `--des`	No	-	Description of changes
`--mandatory`, `-m`	No	`false`	Marks as mandatory update
`--rollout`, `-r`	No	`100`	Sets rollout percentage
`--targetBinaryVersion`, `-t`	No	auto-detected	Sets the target binary version

Example with parameters

npx turbopush release-react myapp-ios ios \
--deploymentName Production \
--description "Critical bug fixes" \
--mandatory \
--rollout 50 \
--targetBinaryVersion "1.0.0"

yarn turbopush release-react myapp-ios ios \
--deploymentName Production \
--description "Critical bug fixes" \
--mandatory \
--rollout 50 \
--targetBinaryVersion "1.0.0"

pnpm turbopush release-react myapp-ios ios \
--deploymentName Production \
--description "Critical bug fixes" \
--mandatory \
--rollout 50 \
--targetBinaryVersion "1.0.0"

Verify deployment keys are correct
Make sure codePush.sync() is being called
Check device logs

Now you're ready to start using Turbopush!

For version 0.75 and below or CodePushServerURL usage

For version 0.75 and below, you need to use the old react-native-code-push instead of the new @turbopush/react-native-code-push package.

This is not supported in expo projects.

npm install --save react-native-code-push

yarn add react-native-code-push

pnpm add react-native-code-push

In ios/[ProjectName]/Info.plist, you need to add the following:

<key>CodePushServerURL</key>
<string>https://api.turbopush.org</string>

And in android/app/src/main/res/values/strings.xml, you need to add the following:

<string name="CodePushServerURL">https://api.turbopush.org</string>