Building Ionic apps

In this tutorial you'll find detailed instructions for how to set up an Ionic project in Nevercode

Ionic is a complete open-source SDK for hybrid mobile app development. Built on top of AngularJS and Apache Cordova, Ionic provides tools and services for developing hybrid mobile apps using Web technologies like CSS, HTML5, and Sass. Apps can be built with these Web technologies and then distributed through native app stores to be installed on devices by leveraging Cordova1.

What this guide covers

This tutorial guides you through setting up your Ionic project in Nevercode.

The tutorial covers how to:

Ionic Project Structure

To identify a project as Ionic, Nevercode looks for a "signature" comprised of 2 components. Note that for Ionic 2 both these steps are generated automatically, when you start a new project with ionic start command. If projects are created with older Ionic versions, you'd need to provide one extra step.

  • Cordova namespace must be correctly specified in the config.xml file in the root folder of your project. Here's what this looks like :
    <widget id="com.your.project" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">

  • the presence of the ionic.project or ionic.config.json file in the root folder of you project. This file is not created immediately after a new Ionic one project is started from the CLI. You could add it manually, but even though it’s tiny and simple, why not let Ionic do it for you: just run ionic serve from your project’s folder. This will open a browser window in which you can see your shiny new app, but more importantly it will create the ionic.project file. Don't forget to add it to source control and commit.

If your project began its life as Ionic, and you've run ionic serve, then everything should be in place. However, users who are converting their existing projects to Ionic (we usually see this with Cordova and PhoneGap projects) need to take extra care to ensure that all these elements of the Ionic "signature" are present and committed to source control before adding their project to Nevercode.

First steps

All you need to setup your project in Nevercode is a web browser. Nevercode doesn’t require any kind of additional software from your side and you don’t even have to write any tedious configuration files full of technical boilerplate. We’ll scan your repository and from what you have there our builders find everything they need. You’ll just have to confirm what configuration you want to build

The first time you log in to Nevercode you’ll be presented with an empty dashboard that encourages you to “Add an app to get started!” Let’s get going by clicking on “add new app”.

That's how your dashboard looks like after you've signed up.

That's how your dashboard looks like after you've signed up.

Clicking the add new app card on the dashboard will open a new project creation flow that asks for your Git repository URL and authentication type for the repository. You can read more about setting up your Git repository from Specify Git repository.

Select configuration

As soon as you submit a repository, either public or private, Nevercode takes a first look at it by listing the branches in this repository. The next step for you is to select the branch you want Nevercode to scan for projects from. To do this you just have to select a branch from the dropdown. If you've chosen the branch, you can hit the green "select branch" button to proceed. (Note that you can change the branch later.)

Clicking on the "select branch" makes Nevercode to scan the repository from specified branch. This includes cloning the repository, looking for projects from it and searching for the configurations.

All these actions can be monitored at the same time from your browser via the live log window as seen below.

We're scanning your repo, looking for apps to build.

We're scanning your repo, looking for apps to build.

When the scanning completes you'll be presented with two options: project and configuration.

The Project selection here means a directory in your repository where your Ionic configuration file config.xml is stored. In the configuration selection you can select whether Nevercode should build either debug or release version of your application.

Configuring your project.

Configuring your project.

Specify which platforms to build

As with Cordova, we currently support Ionic builds for Android and iOS. Nevercode will default to building your project for both, unless your repository includes the platforms/platforms.json or package.json file with specified cordovaPlatforms or platforms field, otherwise Nevercode will build your project for both Android and iOS.

Note that Ionic adds the platforms folder to .gitignore upon new project setup. If you’d like to include platforms.json in version control, make the following changes to your .gitignore:

- platforms/
+ platforms/*
+ !platforms/platforms.json

Be sure to add the asterisk to the existing platforms/ line!

You can read more about iOS provisioning profiles and developer certificates from the corresponding tutorials for iOS apps.

Once these steps are complete and you click ‘Save’, Nevercode will automatically run the first build of your Ionic project.

What commands does Nevercode run to build my Ionic project?

For the sake of debugging your builds, it may be helpful for you to know what happens under the hood when Nevercode builds your Ionic project. The following commands are executed:

  1. ionic platform rm <platform>
  2. ionic platform add <platform>
  3. ionic build <platform> --<target> --device

If your project has multiple platforms, commands 1-3 will be executed once for each platform. In the 3rd command, <target> represents either debug or release, as per your build settings.

Testing

You can enable testing of your Ionic apps via a custom test step. Please take a look at our in-depth documentation for testing hybrid applications to see how you can set that up.

Publishing

Build distribution is an integral part of app development life cycle. Nevercode supports publishing your build artefacts to several distribution channels such as:

If you'd like to generate a release build of your project for publishing to the Apple App Store, there are a few additional steps you need to take. These are detailed in Ionic documentation.

Build versioning

To make your build version management easy, Nevercode exports two environment variables that you can use in your build scripts. You can read more about it from Incrementing Ionic app version.

Troubleshooting

Nevercode does not find my Ionic project or it detects it as a native application instead

Important!

Once Nevercode has incorrectly detected the repository with a given platform (be it Android, iOS or Cordova or Ionic), additional rescans will not change the platform.

To try again you must delete the existing project and add it from scratch.

The most likely cause is that your application does not meet the three requirements specified above in the Ionic Project Structure section. You are probably making use of the npm, bower and gulp toolchain to template your project which can throw Nevercode off, because in that case the necessary files for proper detection are not in place when scanning the project.

The easiest way to fix this issue is to add a custom build step (a post-clone script, NC_POST_CLONE_SCRIPT) which installs the necessary dependencies and performs the extra tasks which are required for initializing your project.

Here is an example of a post-clone script which initializes an Ionic project.

#!/bin/sh
set -e
npm install
bower install
gulp

Building Ionic apps

In this tutorial you'll find detailed instructions for how to set up an Ionic project in Nevercode