Beginner's Guide to Setting Up an Ionic project the Right Way
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,
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.
cdinto 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
This will install all node modules specified in the package.json (more about this later)
Exploring The Project Structure
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)
- platforms: Platform folder which holds the native added platform project files (Android or iOS).
- plugins: Folder generated and used by Cordova to store the installed 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.
- 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.
- package.json: Definition file used by npm (another package manager) where we define packages to install and can specify scripts to run. (See Node)
- 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.
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:
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)
bower installto install ionic all its' dependancies.
makedir tempto hold the vendor files and inside it
Task Runner and Customisation
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
dependencies. This is an important step to do because the gulp library that concatenates the bower files works on libraries declared as
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.
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!