Running Flagship Apps

Contents

• Step 1: Yarn
• Step 2: TypeScript Compiler (TSC)
• Step 3: Init
• Step 4: Run the App
  • iOS
    • Simulator
    • Physical Device
  • Android
    • Emulator
    • Physical Device

Step 1: Yarn

Flagship and Flagship apps use Yarn for dependency management. Simply run yarn in the project root to make sure that your project's dependencies are up-to-date.

Step 2: TypeScript Compiler (TSC)

Whenever you pull down or write new code, you'll need to run TSC in order to compile the TypeScript code into vanilla JS before it can be run on device with React Native.

From your project root, run ./node_modules/.bin/tsc or simply tsc if you have the package installed globally.

Note: Most Flagship apps and the Flagship Template project define TSC as part of the prepare hook in package.json, meaning that TSC will run whenever you run yarn, making this extra step unnecessary.

Step 3: Init

Whenever you pull down a project for the first time, add native dependencies to your project, or update your environment files you'll need to run Flagship init.

Note that you do not need to re-run init unless you change native dependencies or environment files!

The init script does the following:

• Copies the ios and android folders from @brandingbrand/flagship into your project. These contain the native projects for iOS and Android.
• Edits the native projects to customize values per your configuration for items such as app name and bundle identifier.
• Runs react-native link to install native dependencies.
• Runs custom scripts defined in the Flagship package to set up native dependencies that don't link automatically.
• Adds native dependencies using Cocoapods (iOS) and Gradle (Android).
• Registers your environment files and generates env.js for the current selected environment.

You can manually run init as follows: ./node_modules/.bin/flagship init

However, we recommend adding a convenience script to your project's package.json that wraps the script with a clean step that removes the ios and android directories ahead of time. (This already exists in projects created with the Flagship Project Template.)

"scripts": {
  "init": "flagship clean && flagship init native"
}

This would be run as follows: yarn run init

Step 4: Run the App

iOS

Simulator

To start your app in an iOS simulator, you can simply run ./node-modules/.bin/react-native run-ios. However, please note that this doesn't account for TypeScript so you'll need to run tsc whenever you make a change before it'll appear on your simulator.

To accommodate for this, Branding Brand apps and the Flagship Template app define a convenience script in package.json that starts up a TypeScript file watcher, the React Native packager, and the app in one go.

It normally looks like this in package.json:

"compile-ios": "react-native run-ios --simulator \"iPhone X\" --no-packager",
"ios": "run-p start tsc:watch compile-ios"

And you run it like this:

yarn run ios

This will launch the app in a simulator and automatically run TSC whenever your code changes.

Physical Device

1. Connect your device to your computer with a USB cable
2. Open Xcode
3. Use the "Open" menu to open /ios/.xcworkspace
4. Select your device from the devices dropdown (top left next to the app name)
5. Click the Run (▶) button to run the app on your selected device
6. Note that you will need to run tsc after making changes in your code to be reflected in your app

Android

Emulator

Unlike iOS, React Native cannot start an Android emulator. As such, you'll need to manually start an emulator before continuing.

1. Open Android Studio
2. Select Tools > AVD Manager
3. Click "Create Virtual Device" and follow the wizard to create a new emulator, or click the start (▶) button to launch an existing emulator

To start your app in an Android emulator, you can simply run ./node-modules/.bin/react-native run-android. However, please note that this doesn't account for TypeScript so you'll need to run tsc whenever you make a change before it'll appear on your simulator.

To accommodate for this, Branding Brand apps and the Flagship Template app define a convenience script in package.json that starts up a TypeScript file watcher, the React Native packager, and the app in one go.

It normally looks like this in package.json:

"compile-android": "react-native run-android --no-packager",
"android": "run-p start tsc:watch compile-android"

And you run it like this:

yarn run android

This will launch the app in the emulator and automatically run TSC whenever your code changes.

Physical Device

1. Connect an Android device to your computer via USB
2. Open the Settings app
3. Navigate to "About phone"
4. Tap on the "Build number" item 10x in a row to enable developer mode
5. Go back to the main Settings menu and select "Developer options"
6. Verify that the "USB debugging" checkbox is enabled
7. You may need to change your phone's USB mode from charging only to data transfer mode. Refer to your phone's documentation for more information.
8. From your computer, run adb devices which will list all physical and emulator devices and their debugging status
   • If the device isn't displayed, either the phone isn't in developer mode, USB debugging mode is disabled, or the USB mode is set to charging only
   • If the device is listed as "unauthorized", USB debugging is disabled or you haven't given the current computer permission to access your device. Try tapping "Revoke USB debugging authorizations" and then turn USB debugging off then on again and you should get a prompt to allow debugging
   • If the device is listed as "device" debugging should be ready to go.

Once your device is set up for development, the process is the same as running on an emulator: run ./node_modules/.bin/react-native run-android or yarn run android and the app will run on your connected Android device. Note that if you use run-android you'll need to manually run tsc whenever you make a change to your code.