Blank Ionic mobile project setup (1/4 steps to properly set mobile app project using Ionic framework)

Last time we introduced you briefly to the ideas why we are doing this series of articles. In a nutshell, our experiences with the frameworks around Ionic, as well as with Angular applications dictate how we build our solutions today – most notably the hybrid mobile solutions. We want to share them with you and hopefully spark some ideas which can help everyday development efforts.

Let’s start with preparing the project.

Before we get started you’ll need some tools required for building Ionic apps. First, install Node.js from theirs website.

Then, install the latest Cordova and Ionic command-line tools by executing the following command in Node console:

npm install -g cordova ionic

When having the Ionic framework prepared, we can proceed and create an Ionic project using one of ready-made app templates:

ionic start ionicStarterKit sidemenu

Running ionic serve inside ionicStarterKit will run the app in browser.

Ionic out of the box comes with a local development server which helps you work with your applications quickly and efficiently and is suitable for app development and testing. The server is ran using the mentioned Ionic serve command which will start a local development server.

Ionic also comes with a nice feature called LiveReload which on each save of changes in your application reloads your browser session to see the changes right away.

This feature is turned on by default and is set up to watch the changes on your \www directory.

Of course you can change this by specifying the watchPatterns through the equally named property in your ionic.project file located in your project root directory.

And you can disable this feature by running ionic serve --nolivereload flag.

Additional dependencies?

Once we have set up our project we can change what we have inside it. We can start by examining the default Gulp.js file the root of the project. Default Gulp file don’t contain much but we can extend this by adding additional gulp tasks we have to install first through command line.

npm install

This installs all npm modules specified in your package.json file under dependencies and devDependencies section.

It will create new folder called node modules under the root folder and download npm modules inside.

Some of the Gulp tasks which are there out of the box include:

• Gulp Watch task which watches only for SASS changes and compiles the SASS files into CSS. It’s pretty much straightforward as it does it pretty simple.
• Gulp Install This task will download Ionic framework JavaScript files and their dependencies (Angular scripts) from repository listed in bower.json file which is also present in the root of application. This way we don’t have to manually download and include all ionic scripts in the project, but only point to Ionic GitHub repository. Gulp task will take care for the rest.

As we have some extras in the lib directory, and ultimately we want to build a sound and clutter free boilerplate, before running the command, delete the lib directory in project root.

Run gulp install

This should download the latest Ionic library with its dependencies, and create new lib folder in our project root.

Manage your plugins

Now when we experienced how good of a feeling is to be deleting code (and not writing it) let’s do some more code cleanup. In plugins folder Ionic prepared some Cordova plugins but not all are necessary.

The following is our idea of what can be useful, and what not, but if you consider them useful leave them in the project, otherwise delete them not to clutter your solution.

• com.ionic.keyboard – the cordova.plugins.Keyboard object provides functions to make interacting with the keyboard easier, and fires events to indicate that the keyboard will hide/show. We’ll leave this plugin because it’s going to be used in the project for sure (e.g. we want to make sure that keyboard will not be shown on app start).
• cordova-plugin-console – plugin which replaces JavaScript console.log() function. console.log() is good enough and in the other hand angularJS contains $log module for the same purpose so we don’t really need another plugin for logging.
• cordova-plugin-device – this plugin defines a global device object, which describes the device’s hardware and software. This could be very handy in some point of development but we will remove it from this boilerplate since we’re not sure if we are going to use it.
• cordova-plugin-splashscreen – This plugin displays and hides a splash screen during application launch. You can manipulate with Splashscreen delay and auto-hide properties, or trigger it manually (it can be changed in config.xml). Since we don’t want any special behavior with splash screen, we are going to remove it. The splash screen will be shown without the plugin anyway.
• cordova-plugin-whitelist – this is very important plugin and if you don’t want to spend time wondering why your app is throwing http 404 errors when it tries to make network requests, don’t remove it from project. This plugin controls which URLs the WebView itself can be navigated to, which URLs the app is allowed to ask the system to open and which network requests (images, XHRs, etc) are allowed to be made.

More info about how to set up your app can be found here.

Just make sure you add tag in config.xml (which means – don’t block any requests).

Cordova also requires to add content secure policy meta tag in your index.html file, which can set it for now to enable all requests, inline styles and eval() method:

Later in development adjust this based on your app requirements.

Content security policy references can be found here.

So far we covered pretty much everything required for blank project setup. We’ll just take a look at some configuration settings we have to adjust.

Edit configuration

In config.xml file there is name, description and author properties. It’s not very important since this is boilerplate and every app will have unique settings, but change this if you like.

More important parameters are android-minSdkVersion (for android) and deployment-target (for iOS) tags where a minimum android SDK and iOS version are being configured.

We set it to 16 for android and 9 for iOS but this depends of your application requirements.

Also define android-targetSdkVersion property for a current android version of your app (we set to 22 which is, in time of writing this article, the latest stable version).

In summary, you’ll have to add the following tags:

And the last things to add in config.xml file are the icon and splash tags. Based on these tags, Cordova will generate required icon and splash screen images once you start building the app for mobile devices. Fortunately, Ionic took care of this task for us completely. You just have to make two main images and run ionic CLI command, and everything will be automatically generated for you. It’s not too hard and this topic is described on Ionic site in details: https://ionicframework.com/docs/cli/icon-splashscreen.html.

More tips

While in development we spend most time testing our application in the browser. By typing ionic serve in command line, ionic would start our local server with live reload feature looking for changes in the source files. However as our project uses bundled JavaScript files and Gulp Watch task to watch for changes and do minification, when we do change the files we would need to open another command line window to run Gulp Watch task at the same time.

As this is awkward, we want to avoid this and in the ideal case, make Ionic run both our server and Gulp Watch at the same time.

To run Gulp Watch while Ionic Serve is active we need to tell Ionic to combine these two commands together.

Open ionic.project file in your project root folder and add the following.

"gulpStartupTasks": [
 "watch"
],
"watchPatterns": [
 "./scss/**/*.scss",
 "./www/js/**/*.js",
 "./www/build/index.html"
]

This way you can run the app in browser and have Gulp Watch active at the same time.

In case you have LiveReload turned on, browser can still reload the page before Gulp Watch task finishes, so the changes will not be visible.

Because of that we can disable live reload by adding --nolivereload flag when starting the server.

ionic serve –nolivereload

We can go in more details about setup of the project, but these are the basic things you have to do to make a good starting point for Ionic project.

The next thing is to organize Angular code so we could make it reusable and maintainable later in development about what we’ll talk in the next post.