Build Standalone Expo .apk and .ipa with Turtle CLI

March 12, 2019 - 18 min

A great way to start writing React Native applications is to use Expo. You don’t even need to setup a development environment to get started thanks to Snack, an online React Native application editor. Your application is public by default. Sharing has never been that easy.

Photo by Wexor Tmg on Unsplash Brown turtle swimming underwater, Photo by Wexor Tmg on Unsplash

However, you would like to share an application exlusively with some people, not through an app store or any public channel. One possibility is to share the built application file, e.g. an .apk file for Android and an .ipa file for iOS.

Expo is so great a service (oh, and did I mention free?) that they offer you to publish your app on their servers and if you wanted to build these .apk and .ipa files, you could do so on their servers.

The flow looks like:

$ expo publish
$ expo build:<PLATFORM>

and you obtain a nice URL to the artifact created for you when the build finishes.

But, again, this is public. On a server you don’t control. (Although, if you made the same mistake as I did, a ticket to their support can delete any files you had wished to keep private. 🥇)

Luckily for you, Expo provide the tools they are using on their servers for free (did I mention they’re great!?). The build process relies on a CLI tool called turtle-cli. It is open-source and available on GitHub.

Let us go through an example of how to create your application file without resorting to Expo servers. That means you can keep an application private and also build your application while being offline.

The following instructions assume you have bash and Node.js (version 8 or newer) available. In my experience, using the current LTS version of Node.js (version 10.15.3) works best.

Caveat: I could not complete the iOS instructions to the end since I do not have an Apple Developer paid account.

We will go through the following steps:

  1. Install Turtle CLI
  2. Create a dummy application
  3. Publish Expo app on local server

  4. Create APK file — Android

    1. Prerequisites
    2. Create Keystore
    3. Build APK

  5. Create IPA file — iOS

    1. Prerequisites
    2. Create Signing keys
    3. Build IPA

  6. Distribute and install

    1. on Android
    2. on iOS

1. Turtle CLI

To install Turtle CLI, run

$ npm install -g turtle-cli

This will make command turtle globally available on your system. To verify it was correctly installed, let’s print the version:

$ turtle -V
0.5.12

You can also print the CLI manual by using the flag --help:

$ turtle --help
Usage: turtle [options] [command]

Options:
  -V, --version                             output the version number
  -h, --help                                output usage information

Commands:
  setup:ios|si [options]                    Setup environment for building Ios standalone apps.
  setup:android|sa [options]                Setup environment for building Android standalone apps.
  build:ios|bi [options] [project-dir]      Build a standalone IPA for your project, signed and ready for submission to the Apple App Store.
  build:android|ba [options] [project-dir]  Build a standalone APK for your project, signed and ready for submission to the Google Play Store.

2. Create a dummy application

Let’s create a dummy application using Expo CLI. In your terminal, run

$ npx expo init ExampleApplication

(This assumes you have at least version 5.2.0 for npm; you could otherwise install Expo CLI globally with npm install -g expo-cli).

It will ask you a few questions:

? Choose a template: (Use arrow keys)
❯ blank
  minimum dependencies to run and an empty root component
  tabs
  several example screens and tabs using react-navigation

Blank template is enough for us.

? Choose a template: expo-template-blank
? Please enter a few initial configuration values.
  Read more: https://docs.expo.io/versions/latest/workflow/configuration/ › 50% completed
 {
   "expo": {
     "name": "<The name of your app visible on the home screen>",
     "slug": "ExampleApplication"
   }
 }

Provide an app name; ExampleApplication will do.

? Choose a template: expo-template-blank
✔ Please enter a few initial configuration values.
  Read more: https://docs.expo.io/versions/latest/workflow/configuration/ · 100% completed
? Yarn v1.13.0 found. Use Yarn to install dependencies? (Y/n)

You can choose yarn to install dependencies if you have it installed like me, but npm should work just as well.

Your project is ready at ./ExampleApplication
To get started, you can type:

  cd ExampleApplication
  yarn start

Let’s verify the generated boilerplate works:

To finish setting up the dummy application, you need to configure the app.json file; some configuration keys must be specified to build a standalone app.

If you would like to know more about these standalone app specific configurations, check Expo’s documentation for iOS and for Android.

For this tutorial, it is only necessary to specify the keys "bundleIdentifier" under "ios", and "package" under "android" in your app.json file:

...
    "ios": {
      ...
      "bundleIdentifier": "com.example.exampleApplication",
      ...
    },
    "android": {
      ...
      "package": "com.example.example_application",
      ...
    }
...

3. Publish Expo app on local server

Expo has this notion of app publishing: it allows you to share a link or QR code to Expo’s website and anyone can run your app through the Expo app on their devices.

Having your app published is also necessary for over-the-air (OTA) updates, allowing seamless updates to your application, and to publish your application (i.e. building your application files on Expo servers).

You would typically run

$ expo login -u $EXPO_USERNAME -p $EXPO_PASSWORD
$ expo publish

and your app would then be available at https://expo.io/<EXPOUSERNAME>/<APPNAME>.

To have your Expo app “published” on your local server (and avoid public publishing on Expo servers), you will use a different command:

$ expo export --public-url <your-url-here>

Warning: This feature is still in Beta.

Run a local server

There are several ways you could run a local server where you will publish your Expo app.

  • with Python Go to the folder and run

    # If Python version returned above is 3.X
$ python3 -m http.server
# If Python version returned above is 2.X
$ python -m SimpleHTTPServer

    You should be able to go to http://127.0.0.1:8000 to see the files available in the current folder.

  • with Web Server for Chrome This is a Chrome extension allowing you to run a web server through a user interface. Available here.

Web Server for Chrome serving /dist directory on port 8000

In the following, we will assume that your local web server is running on http://127.0.0.1:8000.

Export the app

Your server does not need to be running for this step, but you do need to know which local URL you are going to use in advance.

As introduced above, you can now run:

$ expo export --public-url http://127.0.0.1:8000
...
Export was successful. Your exported files can be found in dist

This command will create a dist directory containing the iOS and Android JavaScript bundles and the different assets you are using.

dist
├── android-index.json
├── assets
│   ├── 140c53a7643ea949007aa9a282153849
│   ├── 3a2ba31570920eeb9b1d217cabe58315
│   ├── 43ec0dcbe5a156bf9e650bb8c15e7af6
│   ├── 5cdf883b18a5651a29a4d1ef276d2457
│   ├── 6beba7e6834963f7f171d3bdd075c915
│   ├── 73b8cff012825060b308d2162f31dbb2
│   ├── 744ce60078c17d86006dd0edabcd59a7
│   ├── a37b0c01c0baf1888ca812cc0508f6e2
│   ├── b06871f281fee6b241d60582ae9369b9
│   ├── b2e0fc821c6886fb3940f85a3320003e
│   ├── d15c1216957060fac577af6151fb8cfe
│   ├── d2285965fe34b05465047401b8595dd0
│   ├── e20945d7c929279ef7a6f1db184a4470
│   └── fa6577fecc0a7838f15a254577639984
├── bundles
│   ├── android-0d2eb108fcf8b4015c36718ff6556ff4.js
│   └── ios-93c994cb24cc6ed3dd007d5d45b11908.js
└── ios-index.json

You can now serve the dist directory on your web server, e.g.

$ cd dist
$ python3 -m http.server

Note: if for some reason you need to re-export your application (because you modified your app.json file since the last export, for instance), you must first remove the dist directory:

# assuming you are at the root of the project
$ rm -rf dist
$ expo export --public-url http://127.0.0.1:8000

4. Create APK file — Android

First, verify that your local server is running, e.g.

$ curl http://127.0.0.1:8000/android-index.json
{"name":"example-app","slug":"ExampleApplication","privacy":"public","sdkVersion":"32.0.0","platforms":["ios","android"],"version":"1.0.0","orientation":"portrait","icon":"./assets/icon.png","splash":{"image":"./assets/splash.png","resizeMode":"contain","backgroundColor":"#ffffff","imageUrl":"http://127.0.0.1:8000/assets/43ec0dcbe5a156bf9e650bb8c15e7af6"},"updates":{"fallbackToCacheTimeout":0},"ios":{"supportsTablet":true},"locales":{},"iconUrl":"http://127.0.0.1:8000/assets/fa6577fecc0a7838f15a254577639984","bundledAssets":["asset_3a2ba31570920eeb9b1d217cabe58315.ttf","asset_744ce60078c17d86006dd0edabcd59a7.ttf","asset_140c53a7643ea949007aa9a282153849.ttf","asset_6beba7e6834963f7f171d3bdd075c915.ttf","asset_b06871f281fee6b241d60582ae9369b9.ttf","asset_e20945d7c929279ef7a6f1db184a4470.ttf","asset_b2e0fc821c6886fb3940f85a3320003e.ttf","asset_d15c1216957060fac577af6151fb8cfe.ttf","asset_a37b0c01c0baf1888ca812cc0508f6e2.ttf","asset_73b8cff012825060b308d2162f31dbb2.ttf","asset_d2285965fe34b05465047401b8595dd0.ttf","asset_5cdf883b18a5651a29a4d1ef276d2457.ttf"],"assetUrlOverride":"./assets","publishedTime":"2019-03-09T15:40:08.924Z","commitTime":"2019-03-09T15:40:08.924Z","revisionId":"DPbm3jm04W","id":"@robincsl/ExampleApplication","bundleUrl":"http://127.0.0.1:8000/bundles/android-0d2eb108fcf8b4015c36718ff6556ff4.js","platform":"android"}⏎

4.1. Prerequisites

For Turtle CLI to work correctly to create an .apk file for Android, you need to make sure the following dependencies are installed:

If you know which Expo SDK version you are going to use, you can run

$ turtle setup:android --sdk-version <SDK-VERSION>

This will take some time:

Mar 9 16:59:41 turtle[37434] INFO:  shell app for SDK 32.0.0 doesn't exist, downloading...
  platform: "ios"
  environment: null
  buildPhase: "setting up environment"
downloading [=                   ] 5% 385.4s
...
...
Mar 9 17:05:24 turtle[37434] INFO:  dependencies installed!
  platform: "ios"
  environment: null
  buildPhase: "setting up environment"
Mar 9 17:05:24 turtle[37434] INFO:  it's all set!
  platform: "ios"
  environment: null
  buildPhase: "setting up environment

In the meantime, you can move on to the next section.

4.2. Create Keystore

Just like any other Android app, this app must be signed with some security certificates. In Android-land, as far as I understand, it’s called a keystore. The instructions to create such a keystore file are available on the Android Developers documentation.

Basically, just create a dummy Android project with Android Studio, and then go to Build > Generate Signed APK.... The UI will ask you which app you want to sign, and your dummy app should be pre-selected. Press Next. The next screen will offer you to Create new...; just fill the form and you’re good to go.

As a TL;DR, you can just download a dummy certificate on the accompanying repository under should-be-private/keystore.jks, for testing purposes only. The keystore file is hugely important if you ever plan to submit your app to Google Play store: it’s the only way to assert you’re the rightful owner to provide new updates to your app.

File: keystore.jks
Keystore Password: keystorepassword
Keystore Key Alias: keyalias
Keystore Key Password: keypassword

4.3. Build APK

Make sure that you are serving the dist directory on http://127.0.0.1:8000 as explained above in Run a local server. Assuming you are using bash as your shell, from the root of your project, run:

EXPO_ANDROID_KEYSTORE_PASSWORD="keystorepassword" \
EXPO_ANDROID_KEY_PASSWORD="keypassword" \
turtle build:android \
  --keystore-path ./should-be-private/keystore.jks \
  --keystore-alias "keyalias" \
  --public-url http://127.0.0.1:8000/android-index.json

Note that you need the flag --public-url to point to http://127.0.0.1:8000/android-index.json.

Once the build finishes, you should see this output in your terminal:

Mar 12 22:14:15 turtle[27274] INFO:  copied build to ~/expo-apps/@anonymous\ExampleApplication-2404b41be7714d8ea4e754193c63164b-signed.apk
  platform: "ios"
  environment: null
  buildPhase: "copying build artifact"

This message gives you the location of your built .apk file. You can now move on to the Distribute and install section below if you are not interested in creating an .ipa file for iOS.

5. Create IPA file — iOS

First, verify that your local server is running, e.g.

$ curl http://127.0.0.1:8000/ios-index.json
{"name":"example-app","slug":"ExampleApplication","privacy":"public","sdkVersion":"32.0.0","platforms":["ios","android"],"version":"1.0.0","orientation":"portrait","icon":"./assets/icon.png","splash":{"image":"./assets/splash.png","resizeMode":"contain","backgroundColor":"#ffffff","imageUrl":"http://127.0.0.1:8000/assets/43ec0dcbe5a156bf9e650bb8c15e7af6"},"updates":{"fallbackToCacheTimeout":0},"ios":{"bundleIdentifier":"com.example.exampleApplication"},"android":{"package":"com.example.example_application"},"locales":{},"iconUrl":"http://127.0.0.1:8000/assets/fa6577fecc0a7838f15a254577639984","bundledAssets":["asset_3a2ba31570920eeb9b1d217cabe58315.ttf","asset_744ce60078c17d86006dd0edabcd59a7.ttf","asset_140c53a7643ea949007aa9a282153849.ttf","asset_6beba7e6834963f7f171d3bdd075c915.ttf","asset_b06871f281fee6b241d60582ae9369b9.ttf","asset_e20945d7c929279ef7a6f1db184a4470.ttf","asset_b2e0fc821c6886fb3940f85a3320003e.ttf","asset_d15c1216957060fac577af6151fb8cfe.ttf","asset_a37b0c01c0baf1888ca812cc0508f6e2.ttf","asset_73b8cff012825060b308d2162f31dbb2.ttf","asset_d2285965fe34b05465047401b8595dd0.ttf","asset_5cdf883b18a5651a29a4d1ef276d2457.ttf"],"assetUrlOverride":"./assets","publishedTime":"2019-03-12T21:11:14.411Z","commitTime":"2019-03-12T21:11:14.411Z","revisionId":"VWnRyAPE3d","id":"@robincsl/ExampleApplication","bundleUrl":"http://127.0.0.1:8000/bundles/ios-22789d0970b943f6f1c94dffd3b8200f.js","platform":"ios"}

5.1. Prerequisites

For Turtle CLI to work correctly to create an .ipa file for iOS, you need to make sure your system is macOS and that the following dependencies are installed:

  • Xcode (version 9.4.1 or newer)
  • fastlane

Note: make sure that you have run Xcode at least once and that you have agreed to the license agreements.

For more details, see Expo’s documentation.

If you know which Expo SDK version you are going to use, you can run

$ turtle setup:ios --sdk-version <SDK-VERSION>

This will take some time:

Mar 12 22:26:46 turtle[35292] INFO:  shell app for SDK 32.0.0 doesn't exist, downloading...
  platform: "ios"
  environment: null
  buildPhase: "setting up environment"
downloading [=                   ] 5% 307.4s
...
...
Mar 12 22:31:39 turtle[35292] INFO:  shell app extracted
  platform: "ios"
  environment: null
  buildPhase: "setting up environment"
Mar 12 22:31:39 turtle[35292] INFO:  it's all set!
  platform: "ios"
  environment: null
  buildPhase: "setting up environment"

In the meantime, you can move on to the next section.

5.2. Create Signing keys

This assumes you have an Apple Developer Account, which is a paid account.

To create your distribution certificate file, or .p12 file, you can follow this guide.

You will also need your Apple Team ID and a Provisioning Profile that you can generate through Xcode as well. This other guide covers in greater lengths what all these cerficates are for and how to obtain them.

Provisioning Profile in Xcode

Note that the provisioning profile expires in 6 days in my case, since I do not have an Apple Developer paid account.

Sadly, it is not possible to share example files.

5.3. Build IPA

Make sure that you are serving the dist directory on http://127.0.0.1:8000 as explained Run a local server. Assuming you are using bash as your shell, from the root of your project, run:

EXPO_IOS_DIST_P12_PASSWORD="<PASSWORD HERE>" \
turtle build:ios \
  --team-id YOUR_TEAM_ID \
  --dist-p12-path /path/to/your/dist/cert.p12 \
  --provisioning-profile-path /path/to/your/provisioning/profile.mobileprovision
  --public-url http://127.0.0.1:8000/ios-index.json

Note that you need the flag --public-url to point to http://127.0.0.1:8000/ios-index.json.

Once the build finishes successfully, you should get the path to your .ipa file.

6. Distribute and install

6.1. on Android

Take your .apk and share it through some Google Drive link or other medium of your choice.

If you download this .apk file through an Android device, it should offer you to install the application on the device.

Trick: if the URL is really not friendly to type, and for whatever reason you have to type it manually, use a QR Code generator (e.g. http://www.barcode-generator.org/) and your device’s camera to simplify your life!

Alternatively, if you connect an Android device to your computer, you should be able to run:

$ adb devices
emulator-5554	device

to list all your connected Android devices and emulators. (In my case, only the emulator is “connected”.)

It is then possible to install the .apk file by running:

adb -s emulator-5554 install $ @anonymous\\ExampleApplication-2404b41be7714d8ea4e754193c63164b-signed.apk
Success

Emulator app screen with example-app installed

6.2. on iOS

Caveat: I could not fully test this section, so my apologies if this does not work as intended.

Since you should have Xcode, the most promising solution is in this guide. It also mentions other ways to install the .ipa file.

That’s it for now, thank you for reading this far. You will find below the resources mentioned in this article.

If you have any questions or comments, please drop me a line on Twitter. I shall reply as soon as possible.

Stay tuned for more.

Resources

Robin Cussol

Personal blog written by Robin Cussol
I like math and I like code. Oh, and writing too.