Skip to main content

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.

1. CLI Installation​

First, install the Turbopush CLI in your project:

npm install --save-dev @turbopush/cli

Verify the installation was successful:

npm turbopush --version

2. Account Creation​

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

3. Authentication​

To start using Turbopush, you need to log in:

npm turbopush login

This command will:

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

To verify you're logged in:

npm turbopush whoami

3.1 Set your default organization

npm turbopush org set <organization-slug>

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

npm turbopush org list

4. Registering Your Application​

warning

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

npm turbopush app add MyApp-iOS --appSlug myapp-ios
npm 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​

Installation​

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

iOS Setup​

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

  1. Open up the ios/[ProjectName]/AppDelegate.m file, and add an import statement for the CodePush headers:

    #import <CodePush/CodePush.h>

  2. Find the following line of code, which sets the source URL for bridge for production releases:

    return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];

  3. 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
    }
  1. 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>
  1. Certifies that your deployment_target is 15.5 or higher in your ios/Podfile file.
platform :ios, '15.5'

Android Setup​

  1. 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"
...

  1. 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() 
               }
        };
    }
  1. 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 turbopush release-react myapp-ios ios -t 1.0.0

or

npm 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 turbopush release-react myapp-ios ios --deploymentName Production --description "Critical bug fixes" --mandatory --rollout 50 --targetBinaryVersion 1.0.0

Read more about Releasing Updates.

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​

  1. Verify deployment keys are correct
  2. Make sure codePush.sync() is being called
  3. 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 install --save 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>