Chapter 2. Setting Up Our Development Environment
One of the initial challenges in developing with the Ionic Framework is the installation and setup of the several tools that Ionic requires. In this chapter, we will walk you through the process of installing all the necessary components and configurations for developing Ionic applications. The installation process can be broken down into to two main parts: the base Ionic installation, and the platform-specific SDK installations. The base installation will cover just the tools that you need to generate your first Ionic application and preview it in your browser. If you want to dive right in and start developing with Ionic, then this is all you will need to do. The second portion of the installation is about setting up your native development environment(s). Even though we are building our apps with web technologies, we will still need to have the native development environments installed on our computers. This will give us access to the emulators, as well as the ability to deploy and test the applications on our devices, and eventually submit them to the app stores.
Throughout this book, we will be using the command line to use the Ionic CLI. On macOS, we will be using the Terminal application. We recommend adding either a shortcut on the desktop or adding it to your Dock. If you are developing on a PC, I personally recommend using Git Bash (which can be installed when we install Git) instead of the default command prompt. Its command syntax is the same as in macOS, so following along with the code samples should be easier.
Installing the Ionic Framework
This section we will get the essential Ionic development environment set up, then generate our first Ionic application and preview it in our browser. You may be wondering why we want to preview our application in a browser. Remember, we are writing our application with web technologies, so it makes sense to target a browser as our first “platform.” We can leverage browser debugging tools and iterate through our development more quickly. My personal development cycle is to try to stay away from testing on a mobile device until I need to.
There are four components we need to install; in the following table, you can see the software we need to get started along with their corresponding URLs.
| Tool | URL |
|---|---|
| Node.js | nodejs.org |
| Git | git-scm.com |
| Ionic | ionicframework.com |
| Apache Cordova | cordova.apache.org |
Installing Node.js
The foundation for Ionic is built atop Node.js (often referred to simply as Node). Node is a platform that enables you to run JavaScript outside the browser. This has enabled developers to create applications and solutions that are written in JavaScript and can be run almost anywhere. Both the Ionic and Cordova CLIs are written using Node. Because of this requirement, we need this framework installed first.
To install Node, go to Node website and download the installer for your development platform. If you already have Node 6.X installed, you can skip this step. You will want to use the 6.X version of Node. If you have an additional need to use a later version of Node, you might want to look at Node Version Manager to allow you to easily switch between node versions.
Once Node has been installed, open the Terminal and enter node -v. This command tells Node to report back the currently installed version:
$ node -v $ v6.9.2
If you encounter an issue with the installation, review the documentation.
You should also make sure that NPM—a package manager for node modules is up to date (note: NPM actually does not stand for “node package manager”). When you install Node.js this is automatically done for you. But if you want to check which version of npm you installed:
$ npm -v $ 3.10.9
If you need to update your installation of NPM, the command is:
$ npm install npm -g
With Node and NPM successfully installed, we will now install Git.
Installing Git
While you are free to choose any version control solution (Perforce, SourceSafe, or Git), the Ionic CLI leverages Git for the management of templates. In addition, I have found that for Windows users, using Git Bash makes it easier to follow along with the examples in this book.
Go to http://git-scm.com, and click the Download button. Go ahead and open the package file and follow the default installation.
Once the installation is complete, launch the Terminal window and verify it.
In Terminal, type git --version and press Enter:
$ git --version $ git version 2.8.4 (Apple Git-73)
With Git now installed on our system, we can install the Apache Cordova CLI.
Installing the Apache Cordova CLI
Although we can install both Cordova and Ionic at the same time, I recommend installing each one individually in case there is an issue during the installation process.
The installation of Cordova CLI uses the Node package manager (NPM) to perform the installation. To install it, open either your Terminal window or Git Bash, and enter the following command:
$ npm install -g cordova
Depending on your internet connection, this can take a while. For macOS users, you may encounter an issue with permissions during the installation. There are two options: rerun the npm command, but preface it with the sudo command. This will allow the node modules to run as the root user. Alternatively, you can configure your system to solve this permission problem:
$ cordova -v $ 6.4.0
With these tools in place, we can finally install the Ionic CLI on to our system.
Installing Ionic CLI
Just like the installation of the Cordova CLI, the Ionic CLI is also installed via NPM. In your Terminal window, enter the following command:
$ npm install -g ionic
This install will also take some time to complete. Once the Ionic CLI has completed its installation, we will again check it by issuing the ionic –v command in our terminal:
$ ionic -v $ 2.1.18
Now we have our base installation in place for Ionic development. However, we eventually will want to test our applications either in a device emulator or on an actual device. We will take a look at the installation of these tools shortly. But first, let’s set up a sample app and see how to preview it in our browser.
Starting a New Ionic Project
The Ionic CLI provides an easy command to enable you to set up an Ionic project: ionic start. This CLI command will generate a basic Ionic application in the active directory. The Ionic Framework can scaffold this project via a collection of starter templates. These can come from a named template, a GitHub repo, a Codepen, or even a local directory. The named templates are blank, sidemenu, and tabs. We will explore those later in this book. For now, run the following command to create an Ionic project:
$ ionic start testApp --v2
Since we did not define a starter template, the Ionic CLI will default to the tabs template. The CLI will now begin the process of downloading the template and configuring the various components. It may ask you if you wish to create an Ionic.io account. For now, we can ignore this, but we will be exploring the Ionic services later in this book. Once the process is completed, we need to change the working directory to the testApp directory that the CLI generated:
$ cd testApp
Let’s take a quick look at the elements that were installed in this directory.
Ionic Project Folder Structure
The project directory contains quite a number of files and additional directories. Let’s take a moment to understand each item and its role:
| src | This directory will contain the actual application code that we will be developing. In earlier versions of Ionic v2, this was the app directory. |
| hooks | This directory contains scripts that are used by Cordova during the build process. |
| node_modules | Ionic now uses npm as its module management system. The supporting libraries can be found here. |
| resources | The default icons and splash screens for both iOS and Android are included. |
| platforms | This directory contains the specific build elements for each installed build platform. |
| plugins | This directory contains Cordova plugins. |
| www | This directory contains the index.html that will bootstrap our Ionic application with the transpiled output from the app directory. |
| .gitignore | A default gitignore file is generated. |
| config.xml | Used by Cordova to define various app-specific elements. |
| ionic.config.json | Used by the Ionic CLI to define various settings when executing commands. |
| package.json | A list of all the npm packages that have been installed for the project. |
| tsconfig.json | The tsconfig.json file specifies the root files and the compiler options required to compile the project. |
| tslint.json | TypeScript linter rules. |
This is the standard structure of any Ionic 2 project. As we add platforms and plugins, additional subdirectories and files will be created.
Hidden Files
Any file starting with a dot on macOS will not be visible in Finder.
Changes from Ionic 1 to Ionic 2
If you have used Ionic 1, there are a number of changes that you might want to be aware of. First, Ionic is no longer using Bower for its package management. Instead, this is now handled through node modules. But the biggest difference is instead of writing your app directly within the www directory, your development is now done in the src directory.
We will explore the various elements in the project folder in a later chapter. For now, let’s just test previewing our application in a browser and ensure that we have a working development environment. For more information on migrating from Ionic 1 to Ionic 2, see Appendix A.
Previewing in the browser
One of the advantages of building hybrid applications is that much of the development and testing can be done locally in the browser. In a traditional native application workflow, you would have to compile your application, then either run it in the emulator or go through the process of installing it on a device. The Ionic CLI has a built-in command to run the application locally in a browser. With the working directory still the one that was created by the ionic start command, enter the following command: ionic serve. This will start a simple web server, open your browser, and load the application for us. It will also listen to changes and auto-refresh the browser whenever a file is saved.
Setting the Port Address
In most cases, ionic serve will prompt you to choose an IP address. You should usually just select the local host choice. If port 8100 is in use, you can select an alternate port by passing in the --p flag followed by the port number you wish to use.
We should now see the starter tab Ionic application running in our browser. The Ionic tab template contains several screens, and we can navigate through them and explore some of the various components in the Ionic Framework (Figure 2-1).
Figure 2-1. Our Ionic tabs sample application
Since you are viewing your Ionic app in a browser, you can use all the developer tools that you normally use.
Browser Options
While you are free to use whichever browser you are comfortable with, I recommend sticking with Google Chrome. Although this is not exactly the same browser that your content will run in on your mobile devices, it is similar, and you will have fewer issues between the desktop testing and the mobile versions.
Platform Tools Installations
While we have a working development environment, eventually we will need to continue our development in emulators, and finally on-device. To do this we will need to install the native application platform tools. This section will be a bit more complex than the previous installation and specific to each platform we need to install. Thankfully, this is a one-time process; so give yourself time to complete this section.
Currently, Ionic officially supports iOS, Android, and Windows Universal.
iOS
If you plan to develop for iOS, you will need to use Xcode for both emulation and distribution of your app. Xcode is only available for Mac. While there are some solutions that sidestep the need for a Macintosh (PhoneGap Build and Ionic Package), I recommend having at least an entry-level Mac computer available for development.
To install Xcode, simply open the App Store and search for “Xcode”. The download is quite large (well over 3 GB), so make sure you have a good internet connection and disk space for installation.
Android
Unlike iOS, development for Android can be done on Windows, Mac, and Linux systems. Installation of the Android SDK can be done either via Android Studio or via the standalone SDK tools. If you want a complete IDE for Android, then download Android Studio, but we only need the SDK for our development. To download either option, go to the Android Developer website. Personally, we prefer to have the full IDE installed instead of just the SDK.
Installing the Android Studio or SDK will require the installation of the Java Development Kit as well. These additional installation instructions can be viewed on the Android Studio page.
Windows Universal
If you wish to build Windows Universal applications, you will have to do this on a Windows machine. Download and install Visual Studio 2015 Community Edition.
During the installation, select “Tools for Cross Platform Development” as well as the SDK for Windows Universal Apps.
Setting Emulators
With the base mobile SDKs installed, we can continue the installation process. For both iOS and Android development, we need to set up the appropriate device emulators. These emulators will allow you to run a virtual mobile device on your computer. We can use them to test our application quickly on various versions of an OS or device type without needing a physical device. They are slower to work with than directly testing in your browser but can enable the ability to test device specific features, such as working with the Contact database.
Emulators require some additional installation and configuration. Let’s look at the steps for each platform.
iOS
Technically, the iOS emulator is a simulator as it does not actually run the native OS, but rather simulates its execution. To install our iOS simulators, launch Xcode, then choose Preferences from the Xcode menu. In the Downloads tab, you will find a list of available simulators that can be installed. Please note that each simulator is over 1 GB is size, so make sure you have the disk space and internet connection for the download and installation. We typically only have the last two releases installed on our development machine.
Once this installation is complete, we also need to install the Command Line Tools for Xcode. From the Xcode menu, select Open Developer Tool, then the More Developer Tools option. Then locate the Command Line Tools for Xcode for your version of Xcode and download and install it.
The last piece to work with iOS simulator is to install the ios-sim node module. Open a terminal window and enter the following command:
$ npm install -g ios-sim
You might need to issue this command with sudo depending on your configuration.
The ios-sim tool is a command-line utility that launches an iOS application in Simulator.
Now we will be able to run our Ionic apps in the iOS simulator. We will look at this in just a bit.
Android
Before we can configure our Android emulator, we need to install and set up the SDK packages. If you are using the SDK only, run the following from the command line:
$ android sdk
This will launch the standalone SDK manager. This tool will allow you to download the platform files for any version of Android. Like, iOS we recommend only downloading the last two releases packages and tools.
You need to choose the following items:
Android Platform SDK for your targeted version of Android
Android Platform-Tools
Android SDK build-tools version 19.1.0 or higher
Android Support Repository (found under “Extras”)
If you are using Android Studio, from the welcome screen, select Configure, then choose SDK Manager. Then install the same components as the standalone option.
With the SDKs installed, along with the corresponding platform tools, we can now configure the Android emulator. While we can create and configure our virtual android devices within Android Studio, you need to have an active project to do this. Rather, I suggest just using the command line to configure your virtual devices:
$ android avd
This will open the Android Virtual Device (AVD) Manager. Once it has launched, select the Device Definitions tab to choose a known device configuration. Select the Nexus 5 definition, then click the Create AVD button. A new window will open with a variety of configurations and additional details that you can set for your virtual device—screen size, which version of Android to run, etc. Once you are satisfied with your device, click OK to finish the process. You can have as many virtual devices as you would like.
Android Emulators
The Android emulators are known to be slow to launch and use. This process has improved greatly in recent releases of the default emulator. However, you might want to look at an alternate solution from Genymotion for your virtual Android needs.
Setting Up Your Devices
At some point, you will have to actually test your application on your mobile devices. Each platform has a different set of requirements for this.
iOS
While anyone can test their iOS app in the iOS simulator for free, you must be a paid member of the iOS Developer Program in order to test on a device. In the past, provisioning your iOS device for development was a complex process. Thankfully recent changes to Xcode have simplified this process.
First, directly connect your iOS device to your Mac. This process can not work via a wireless connection. Next, we need to create a temporary Xcode project. In Xcode, select New→Project from the File menu. The New Project assistant will open, then select the Single View Application choice. On the next screen, enter Demo as the Project Name, then click Next. The settings aren’t important because we are going to delete this project once we have configured the device. Select a location for the project, then click Create.
Xcode will now display the configuration window for our project. We now need to set the active scheme to our device. This is set via the Scheme control near the top-left of the Xcode window.
With your device unlocked and displaying its Home Screen, select it from the Scheme dropdown. You should have a warning that there is No Signing Identity Found. Instead of letting Xcode fix this issue, we should manually address it.
In the General settings, in the Identity panel, select your team’s name (which is probably just your name) from the drop-down list.
If you do not see your team’s name listed, you will need to add your team’s account to Xcode. To do this, select Add Account in the drop-down list. The Accounts preferences window will now open. Enter your Apple ID and password that is associated with your iOS Developer Program account, and click Add.
Once Xcode has finished logging you in and refreshing its list, close the Accounts window. Select your newly added team from the Team drop-down list.
Xcode will now display a new warning about No Matching Provisioning Profiles Found. Click the Fix Issue option and Xcode will resolve this issue.
In order to configure the provisioning profile, Xcode will need some additional information and permissions. You can just answer the question with the defaults.
Let’s validate that everything is configured correctly. Click the Run button, located in the top-left of the Xcode window, making sure that you have your iOS device selected as the target. After a few moments, this test app should launch on your device!
Now, to integrate this into our command-line tool chain, we need to install another node tool, ios-deploy. From the command line, enter the following command:
$ npm install -g ios-deploy
Installation on El Capitan
If you are running macOS 10.11 El Capitan, you may need to add the --unsafe-perm=true flag when running npm install or else it will fail. For more information on this issue see GitHub.
For additional assistance, refer to Apple’s documentation.
Android
Setting up an Android device is almost the complete opposite from setting up an iOS device. The first step is to enable developer mode on your device. Since each Android device’s user interface can vary, these are the general instructions:
- Open the Settings and scroll to the About Phone item.
- There should be a Build Number—you must tap it seven times to enable the developer mode. As you get closer to seven taps, the device should notify you how many taps are left.
- Once this is complete, you can go back to the Settings list and you’ll see a new Developer Options item.
If you encounter an issue enabling Developer Mode on your device, review the device’s user guide. Next, we need to enable USB debugging in order to deploy our apps. In the Developer Options screen, locate the USB debugging option and enable it.
Your Android device is now ready for development. You may be prompted with a dialog to confirm the pairing when you connect the device to the computer for the first time.
Adding Mobile Platforms
Although the Ionic CLI will scaffold much of our application, we might need to add in the target mobile platforms. In order to view our app in either the emulator or on-device, the corresponding platform must be installed. Open your terminal window, and make sure that your working directory is your Ionic project directory. The Ionic CLI command is ionic platform add [platform name] .
To add the project files for Android:
$ ionic platform add android
To add the project files for iOS:
$ ionic platform add ios
To add the project files for Windows:
$ ionic platform add windows
By default, the iOS platform is added if you are running on a Mac, so you rarely need to install that platform manually. This command will generate all the needed files for each specific platform.
Previewing on Emulator
With a mobile platform added to our Ionic project, we can now verify that we can preview our app in the platform emulator. To run our app in an emulator, use the following command:
$ ionic emulate [platform]
The Ionic CLI will begin building your app for use on that platform’s emulator. You will see a lot of output in the terminal as it goes through the process. Once it is finished, the emulator will automatically launch and run your application.
If you need to target a specific emulated device, append the command to include the –target switch. For example, if I wanted to emulate an iPad Air, I would use:
$ ionic emulate ios --target="iPad-Air"
For a list of iOS device types, use:
$ ios-sim showdevicetypes
For a list of Android devices, you will need to refer to the AVD Manager for the device names.
Once you already have the emulator up and running, you can run the emulate command again without closing the emulator. This is faster than exiting the emulator and relaunching it every time you change files because the emulator doesn’t have to reboot the OS each time.
The Ionic CLI has another very powerful feature that allows you to reload the app instantly using the live reload flag, --livereload. This feature was a huge timesaver when working with emulators during our Ionic 1 development workflows. However, recent device security changes have currently disabled it, and it is not clear if a solution will be found.
You can also output the console logs to Terminal so you can read them more easily (see the Ionic blog post about this feature):
$ ionic emulate ios -l -c $ ionic emulate android -l -c
Previewing on Device
Although the emulators do a fine job, eventually you will need to install your application on a physical device. The Ionic CLI makes it extremely easy to do so with the run command. In your terminal, enter ionic run platform.
The Ionic CLI will then begin the process of compiling the app for installation on your device. When it is finished, it will automatically install the app on the connected device. Be aware that each installation will overwrite the existing installation of the app.
For iOS deployment, you will also need the ios-deploy node module installed; otherwise, you will have to manually perform the installation via Xcode:
$ ionic run ios -l -c
If you are developing for Android on a Windows machine, you might need to download and install the appropriate USB driver for your device. Check the Android Studio website to see if one is needed for your device. No additional drivers should be needed for macOS to deploy to an Android device:
$ ionic run android -l -c
If a device is not found, the Ionic CLI will then deploy your app to an emulator/simulator for that platform.