Beginner's Guide to Setting Up an Ionic project the Right Way

Introduction

Ionic is a cross-platform mobile application development framework built on top of AngularJS.

The framework provides components and tools that allow you to build cross-platform apps that will looks and feel very similar to native apps.

Convinced? Let's Begin.

Setting Up The Environment

Before starting, please make sure you have a stable internet connection so that node installs all the modules needed.

First, create a directory to download the app source code in,
then run:

• npm install -g ionic
• npm install -g cordova

This will install the ionic and Cordova CLI globally on your system. We need Cordova because the Ionic CLI is built on top of Cordova.

Next,

• cd into your folder
• ionic start TestApp blank

The last argument used in the above command is the app template we want to use; it varies from an app with tabs, one with a side menu, even one with geolocation (google maps).

After the start command is done and the folder has been created, cd into your TestApp folder and run npm install.
This will install all node modules specified in the package.json (more about this later)

Exploring The Project Structure

When you cd TestApp, you will see many new folders that you might and might not be familiar with.
Let's make a quick runthrough of what each one is for:

• README.md: A simple readme file used by the code-base
• config.xml: The Cordova config file that specifies the app name, version, and preferences. (See Config)
• hooks: Cordova hooks folder which allows you to execute javascript code during the multiple phases of building your app
  (See Hooks)
• platforms: Platform folder which holds the native added platform project files (Android or iOS).
  (See Platforms)
• plugins: Folder generated and used by Cordova to store the installed plugins.
  (See Plugins)
• bower.json: File used by Bower package manager that holds a reference to our installed packages and where we can add packages to our application.
  (See Bower)
• gulpfile.js: Task Configuration file used by Gulp Task Runner; Here you can define tasks such as copying js to another folder, minifying CSS and JS, and many more.
  (See Gulp)
• package.json: Definition file used by npm (another package manager) where we define packages to install and can specify scripts to run. (See Node)
• www: Folder where all the HTML, JavaScript and CSS of your application is stored and ran. (Generated by the Ionic App Starter)
• scss: Folder where the SASS files which get compiled at runtime are stored. (See Sass)

To check that everything is working fine, run ionic serve in your CLI and it should open a new tab/browser window with the URL http://localhost:8100. This URL is the default server URL and port that Ionic uses to run its application server on.

Project Terraforming

Now that we have the basics set up, let's change a couple of things to make the project and its structure more development-friendly.

Modifying The Folder Structure

The Ionic starter project provides the basics to develop any type of application we want. Yet, any developer worth his salt knows the project structure is one of the most important building blocks of a project development.

Folder by Feature Structure

An Angular project can have many different folder structures, the most recommended one is the Folder By Feature

This structure consists of creating a folder for every main "feature" of our app.
For example, if want to create a Login page, we'll create a folder login and inside we'll create our login.html, login.controller.js and login.scss.

We'll be adapting this folder structure throughout this guide, if you prefer trying out another structure, feel free to experiment with the AngularJS Folder Structures.

We'll start with a single login page, so let's create the files for that:

• cd TestApp
• mkdir app
• cd app/
• mkdir login
• cd login
• touch login.html login.controller.js login.scss

We need to move the index.html from the www/ folder to our app folder and clean up the project folders,
so let's do the following;

• Copy index.html to the app/ folder.
• Create main.js in app/ to define the angular main module and its dependancies (sub-modules).
• Delete lib folder inside the www/.
• Delete .bowerrc that defined the download path for the bower files. (See Bower Configuration)
• Run bower install to install ionic all its' dependancies.
• makedir temp to hold the vendor files and inside it mkdir js and mkdir css

Task Runner and Customisation

Gulp

The main piece that the Ionic starter project is missing is the gulp tasks.
For the convenience of this tutorial, I already prepared the gulpfile.js that holds all the tasks we will need to have clean and optimised code.

Visit this Gist and copy the contents of the gulpfile.js inside the one you have in your project replacing any code there.

Before we can start using the gulpfile, we need to install a few new dependancies used to concatenate, optimise, and minimise our code, as well as fix some file paths with the initial Ionic files.

First, in your terminal, run the following:

• npm install --save-dev gulp-uglify
• npm install --save-dev main-bower-files

Second, open bower.json file with that same text editor and change devDependencies to dependencies. This is an important step to do because the gulp library that concatenates the bower files works on libraries declared as dependencies.

Final Touches

Open scss/ionic.app.scss with your favourite text editor and replace the icons path and import path with the following:

// The path for our ionicons font files, relative to the built CSS in www/css
$ionicons-font-path: "bower_components/ionic/fonts" !default;
//Include all of Ionic
@import 'bower_components/ionic/scss/ionic';

Lastly, make sure your app/index.html file and app/main.js file look like the ones in the Gist.

Conclusion

Now we've setup all that we need to have a decent project structure good build automation, we can finally run gulp watch and ionic serve from our Terminal (in that order) and see the magic happen!

A window/tab will be opened with a header bar containing "Ionic Blank Starter"
From here, you can start building your app and dive into the glorious realm of Ionic and AngularJS development!