Initial Setup and First Release

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
yarn

npm install --save-dev @turbopush/cli

yarn add --dev @turbopush/cli

Verify the installation was successful:

npm
yarn

npx turbopush --version

yarn 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:

npm
yarn

npx turbopush login

yarn 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:

npm
yarn

npx turbopush whoami

yarn turbopush whoami

3.1 Set your default organization

npm
yarn

npx turbopush org set <organization-slug>

yarn turbopush org set <organization-slug>

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

npm
yarn

npx turbopush org list

yarn turbopush org list

4. Registering Your Application

warning

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

npm
yarn

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

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

npm
yarn

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

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

info

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

React Native
Expo

Installation

npm
yarn

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

yarn 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.

Objective-C
Swift

Open up the ios/[ProjectName]/AppDelegate.m file, and add an import statement for the CodePush headers:
```
#import <CodePush/CodePush.h>
```
Find the following line of code, which sets the source URL for bridge for production releases:
```
return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
```

Replace it with this line:

return [CodePush bundleURL];

Your sourceURLForBridge method should look like this:

- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
{
  #if DEBUG
    return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
  #else
    return [CodePush bundleURL];
  #endif
}

Open up the ios/[ProjectName]/AppDelegate.swift file, and add an import statement for the CodePush headers:
```
import CodePush
```
Find the following line of code, which sets the source URL for bridge for production release:
```
Bundle.main.url(forResource: "main", withExtension: "jsbundle")
```

Replace it with this line:

CodePush.bundleURL()

Your bundleUrl method should look like this:

override func bundleURL() -> URL? {
#if DEBUG
   RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
#else
   CodePush.bundleURL()
#endif
}

Add the CodePushDeploymentKey key (generated in the create app step) in the file ios/[ProjectName]/Info.plist

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

Certifies that your deployment_target is 15.5 or higher in your ios/Podfile file.

platform :ios, '15.5'

Android Setup

In your android/app/build.gradle file, add the codepush.gradle file as an additional build task definition to 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: update the MainApplication.kt

Important! : PackageList must be instantiated only one in application lifetime.

    ...
    // 1. Import the plugin class.
    import com.microsoft.codepush.react.CodePush

    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())
                }

               // 2. Override the getJSBundleFile method in order to let
               // the CodePush runtime determine where to get the JS
               // bundle location from on each app start
               override fun getJSBundleFile(): String {
                 return CodePush.getJSBundleFile() 
               }
        };
    }

Add the CodePushDeploymentKey key (generated in the create app step) in the file android/app/src/main/res/values/strings.xml

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

Basic JavaScript configuration

In your main app file (e.g., App.js):

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

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

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:

npm
yarn

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

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

npm
yarn

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

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

Important release parameters

--deploymentName or -d: Specifies the deployment (default: "Staging")
--description or --des: Description of changes
--mandatory or -m: Marks as mandatory update
--rollout or -r: Sets rollout percentage (e.g., --rollout 25)
--targetBinaryVersion or -t: Sets the target binary version (e.g., --targetBinaryVersion 1.0.0)

Example with parameters

npm
yarn

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

Installation

npm
yarn

npm install --save @turbopush/react-native-code-push @turbopush/turbopush-expo-plugin expo-build-properties

yarn add @turbopush/react-native-code-push @turbopush/turbopush-expo-plugin expo-build-properties

Expo Plugin Setup

Add the following to your app.json or app.config.ts file:

note

Turbopush SDK requires a minimum deployment target of 15.5, if you're using a higher version, you can ignore the expo-build-properties plugin.

{
  "plugins": [
    [
      "expo-build-properties",
      {
        "ios": {
          "deploymentTarget": "15.5",
        },
      },
    ],
    [
      "@turbopush/turbopush-expo-plugin",
      {
        "android": {
          "CodePushDeploymentKey": "YOUR_ANDROID_CODE_PUSH_KEY", // generated in the create app step
        },
        "ios": {
          "CodePushDeploymentKey": "YOUR_IOS_CODE_PUSH_KEY", // generated in the create app step
        },
      }
    ]
  ]
}

note

For the sake of simplicity, we're using the deployment key hardcoded in the app.json file. However, we recommend using environment variables to store your deployment keys. e.g. process.env.EXPO_PUBLIC_TURBOPUSH_ANDROID_KEY and process.env.EXPO_PUBLIC_TURBOPUSH_IOS_KEY.

Prebuild

Run npx expo prebuild to generate the native code for your app.

Basic JavaScript configuration

In your main app file (e.g., App.js):

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

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

export default codePush(App);

For advanced configuration, refer to the JavaScript API Reference.

6. First Release

Creating a Release (Expo)

Use the specific command that automatically generates the bundle:

npm
yarn

npx turbopush release-expo myapp-ios ios 1.0.0

yarn turbopush release-expo myapp-ios ios 1.0.0

npm
yarn

npx turbopush release-expo myapp-android android 1.0.0

yarn turbopush release-expo myapp-android android 1.0.0

Important release parameters

--deploymentName or -d: Specifies the deployment (default: "Staging")
--description or --des: Description of changes
--mandatory or -m: Marks as mandatory update
--rollout or -r: Sets rollout percentage (e.g., --rollout 25)

Example with parameters

npm
yarn

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

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

Troubleshooting

Binary version error

Make sure the version specified in the release corresponds to the version in Info.plist (iOS) or build.gradle (Android).

App not receiving updates

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.

warning

This is not supported in expo projects.

npm
yarn

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

yarn 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>

1. CLI Installation​

2. Account Creation​

3. Authentication​

4. Registering Your Application​

After creating the app​

5. SDK Configuration​

Installation​

iOS Setup​

Android Setup​

Basic JavaScript configuration​

6. First Release​

Important release parameters​

Example with parameters​

Installation​

Expo Plugin Setup​

Prebuild​

Basic JavaScript configuration​

6. First Release​

Important release parameters​

Example with parameters​

Troubleshooting​

Binary version error​

App not receiving updates​

For version 0.75 and below or CodePushServerURL usage​

1. CLI Installation

2. Account Creation

3. Authentication

4. Registering Your Application

After creating the app

5. SDK Configuration

Installation

iOS Setup

Android Setup

Basic JavaScript configuration

6. First Release

Important release parameters

Example with parameters

Installation

Expo Plugin Setup

Prebuild

Basic JavaScript configuration

6. First Release

Important release parameters

Example with parameters

Troubleshooting

Binary version error

App not receiving updates

For version 0.75 and below or CodePushServerURL usage