Getting Started in Mobile with Apache Cordova

Now that I’ve pretty much completed my Universal Windows App working with Azure Mobile Apps, I thought I would turn my attention to the other platforms. Sure, I could write an iOS app in the latest and greatest – Swift, then write an Android app in java. But that’s three languages I have to learn. Worse – they are all semantically different. There has to be a better way.

Well, there is. That way is to use cross-platform development techniques. There are currently three methods that I know of, and I’ve written about two of them in the past:

  1. Apache Cordova (nee PhoneGap) uses HTML and JavaScript and produces an app that runs in a WebView. Apache Cordova is “free”.
  2. Xamarin uses C# and the .NET runtime to produce native apps. Xamarin is a licensed product, although there are free and cheap tiers.
  3. Flutter is a new entry from Google and uses Dart to develop apps. The docs are very light, so use with caution here.

Eventually, you are going to choose native or cross-platform. If you choose cross-platform, then you are going to choose the language that your organization has the most comfort in. For some that will be JavaScript and for others, C#.NET. I’m going to use Apache Cordova here.

Getting Started

Apache Cordova runs on top of Node. But wait a little bit before you rush out and install the latest version of Node. Node v5.0.0 has a new version on npm that has flattened the file structure under node_modules. Apache Cordova has some built-in paths that expects the previous file structure. As a result of this, you will want to install Node v4.2.2 – the Long Term Support (LTS) edition. This comes with npm v2.14.7. DO NOT UPGRADE THE VERSION OF NPM.

Since my intent is to build iOS and Android apps, I’m going to do all my work on a Mac. My toolbar has Terminal (which is in the Applications -> Utilities folder), Visual Studio Code and Xcode on it. In addition, I’ve started up Xcode and accepted the license – this is required for some of the developer tools on the mac, like git. Quite why git requires me to accept the Apple license, I don’t know.

I also like having the git repository status in my command line prompt. There is a great package for this on Windows called posh-git. On Mac OSX, you have bash-git-prompt. To set it up, open up your Terminal and type the following:

cd ~
git clone .bash-git-prompt

You can now integrate the library into your prompt. Here is my .bashrc file:

# GitPrompt configuration

# GIT_PROMPT_FETCH_REMOTE_STATUS=0 # uncomment to avoid fetching remote status
# GIT_PROMPT_SHOW_UPSTREAM=1 # uncomment to show upstream tracking branch
# # uncomment to support older Git

source ~/.bash-git-prompt/

This will give you a nice colorful prompt with the git status.

Finally, you also need Apache Cordova:

sudo npm install -g cordova

If you are going to be developing iOS apps, then you will probably need ios-sim.

sudo npm install -g ios-sim

Other npm packages that are useful include the normal set of things for building web applications. I use tsd quite a lot to provide syntax highlighting within Visual Studio Code, gulp for building my apps, eslint for checking individual JavaScript files before check-in and mocha for running tests. Your toolchain will likely be different as the JavaScript tooling is very individual.

Other things you will need depends on what sort of applications you are building. If you are building iOS apps, you must have Xcode and the iOS SDK. If you are building Android apps, then download the Android SDK and build tools. If you are building Windows apps, then swap over to a Windows machine and download Visual Studio Community edition. It’s a good idea to go through a “getting started” type tutorial for each one just to make sure you have the tools set up properly.

One particular point – when doing the Android install, I downloaded Android Studio and opened it up to go through its quickstart. The Quick Start I found online was for Marshmallow (API version 23). Apache Cordova defaults to Lollipop (API version 22). In order to follow along, you must run ~/Library/Android/sdk/tools/android and install API version 22. In addition, download all the system images you want – you will need them later.

Getting all this ready can take some time and involves downloading gigabytes of installation files so ensure you give yourself a few hours for this step.

Building your first Cordova App

For this first app, I’m more interested in getting the toolchain working. I want to have a working Apache Cordova app that has a SASS stylesheet and is written in ES2015 and packaged with Browserify. I could do less than this, but then I’m not proving out the compilation process. I also want to build both an iOS app and an Android app and have them run in the appropriate emulator.

To start, I’m going to create a Cordova starter app:

cd ~/Documents/GitHub/quickstarts
cordova create Quickstart.Cordova

This will create a Quickstart.Cordova directory with a config.xml and some directories. The config.xml is an important file – it contains all the settings that cordova reads when producing the various apps. You will want to edit it to change the author and description, but that’s about it. Note that there is no package.json file – I’ll get to that when I integrate the toolchain.

Next step is to add a platform. I’m going to add the ios and android platforms along with a browser platform for testing purposes:

cd Quickstart.Cordova
cordova platform add browser
cordova platform add ios
cordova platform add android

I want to make sure the basics are running, so I’m following the Apache Cordova getting started guide – let’s fire it up:

cordova run browser

Here is what you get:

Screen Shot 2015-11-14 at 10.49.14 AM

This is good because I have access to all the tools I need to debug JavaScript, but it’s not a mobile app. It’s just a web app. To build and run the iOS version:

cordova build ios
cordova run ios --emulator

Your screen should blossom into the iPhone 6 simulator:

Screen Shot 2015-11-14 at 10.54.03 AM

Finally, I also want to build Android apps:

cordova build android

If you encounter errors, it’s likely you are missing some prerequisite. In general, the build process will tell you what is missing – just download and install what is missing and re-try the build or run command.

The next command is where I ran into a wall:

cordova run android --emulator

Here is what I got…

Screen Shot 2015-11-14 at 11.02.15 AM

I’m going to be waiting a long time as I don’t have an emulator set up. The iOS emulator was nicely set up for me – not so the Android emulator. To fix this, create an emulator:

~/Library/Android/sdk/tools/android avd

Click on the Create button and fill in the form:

Screen Shot 2015-11-14 at 11.23.39 AM

Remember I said you would need a system image when downloading the SDK? Well, this is where you need them. If you didn’t download one, exit out of the Virtual Device Manager, go back into the SDK Manager by running ~/Library/Android/sdk/tools/android and install a system image from the API Level 22 set. Heck – install them all!

Now you can run the same command:

cordova run android --emulator

This one takes a while to start up. Eventually, you will get the following:

Screen Shot 2015-11-14 at 11.26.07 AM

Checking in the work

All my work is in GitHub, but that means I have to be careful about what I check in. Cordova has some extra stuff. Here is my .gitignore file:


Now, you might think that ignoring platforms and plugins is a bad idea. There is an extra step here. First off, you need to save the platforms and plugins to the config.xml. Whenever you add a platform, use the –save option. If (like me the first time) you forgot to do that, do this instead:

cordova platforms save

This will save all the currently installed platforms into the config.xml file. We haven’t delved into plugins yet, but you can do the same thing:

cordova plugin save

When you install your project on a new machine, run the following to restore the platforms and plugins directory.

cordova prepare

This will download and install the platforms and plugins that you saved into the config.xml file. You can now commit your changes to GitHub with no issue. For this basic app, it should be no more than 8 files.

Want to try it for yourself? Download my quickstart repository and run the cordova prepare command on that.

Wrap Up

Well, I thought I was going to get to some code today, but this whole process ended up taking me about four hours. Most of that time was in downloading and installing the tooling for iOS and Android devices. However, take a look at what has been achieved. I’ve set up my entire Apache Cordova system and prepped it for developing in the browser, on iOS and on Android devices. I’ve also run the basic introductory app in all three environment in emulation. This gives me confidence going forward that I can develop my Quickstart for both iOS and Android with the same code base.