Creating an Ionic project

February 16, 2017, 11:20 am Categories:


Typically when creating an Ionic project from the command line you will run something like the following instruction:

ionic start app-name-here blank

Breaking this down the above command consists of:

  • Running the start command to create a new Ionic project
  • Supplying the name of the project - app-name-here
  • Selecting a blank template for the project (we'll look at alternative template choices a little later on)

This will then create a blank Ionic project in a directory named app-name-here (which will reside in the directory that you navigated to in the CLI).

All fairly simple stuff and, if you've been using the Ionic CLI for a reasonable length of time, nothing that you won't be unfamiliar with.

We can however tailor the commands that we use to create an Ionic project.


Configuration tasks are, in my humble opinion, kind of tedious and can often be easy to overlook (particularly when chasing deadlines and fixing bugs....and don't we all know how fun that part of the development cycle can be :-/)

Thankfully the Ionic CLI lends a helping hand by providing the ability to specify different configuration options.

For example, we could use the --id flag to add the package name when creating our ionic project:

ionic start app-name-here blank --id=com.yourcompanyname.appidentifier

Typically your package name will follow a reverse domain name convention in the form of: com.yourcompanyname.appidentifier.

The --id flag might appear, at first glance, as a trivial addition but its presence subsequently writes the package name to the application's config.xml file (in the widget id attribute to be exact).

The package name is then already specified when it comes to time to deploy our application to the respective online app stores - which actually makes the --id flag a pretty useful addition!


Similarly we can also specify the name for our application (which will also be written to the config.xml file) with the --appname flag like so:

ionic start app-name-here blank --appname="My awesome app"

This simply adds a human readable name for the application.

Note that the supplied value for the --appname flag is encapsulated within quotes.

DON'T forget to add these as they are required.


Interestingly we can also instruct the Ionic CLI, when creating our project, to skip the installation of node modules through the --skip-npm flag:

ionic start app-name-here blank --skip-npm

This would result in an Ionic project with NO installed npm packages which means an application we can't actually run.

Er...isn't that a little counter-productive and, well, kind of dumb?

Not really.

We might choose to spend time editing the package.json file so as to supply our own npm packages and their version numbers. Doing so would allow specific node modules to be tailored for subsequent installation to our post-created Ionic project using the npm install command.

If you do use the --skip-npm flag you'll notice a massive decrease in the amount of time it takes to create the project (from minutes to literally seconds).

This is one of those nice-to-have options but one that most developers will happily ignore.


Want to see what starter templates are available for your app?

Simply add the --list flag:

ionic start --list

This will then output the following to the command line window:

blank ................ A blank starter project for Ionic
complex-list ......... A complex list starter template
maps ................. An Ionic starter project using Google Maps and a side menu
salesforce ........... A starter project for Ionic and Salesforce
sidemenu ............. A starting project for Ionic using a side menu with navigation in the content area
tabs ................. A starting project for Ionic using a simple tabbed interface

If no template option is supplied to the CLI then, by default, a project will be created using the tabs template.


Interestingly we can also create an Ionic project that doesn't utilise the Apache Cordova framework by adding the --no-cordova flag:

ionic start app-name-here --no-cordova

This would then create a project WITHOUT the following assets:

  • config.xml file
  • hooks directory
  • platforms directory
  • plugins directory

I've never personally opted to create a project that DIDN'T use the Apache Cordova framework but I imagine that some developers might choose to do so if:

  1. They only want to build web based applications using Ionic
  2. They don't need to install those application on a mobile device
  3. OR they may want to install a hybrid application development framework other than Apache Cordova

It's not an option I can see myself ever using but it's interesting to know that it's there.

Before we round up this tutorial I want to introduce you to one more command line option for creating Ionic projects.

Ionic project wizard

The team at Ionic have introduced an interesting feature, since Ionic 2.2.1, that allows developers to create projects through a web based GUI simply by running the following from the command line:

ionic start

By omitting any of the expected options from the ionic start command the CLI will launch the following in your system browser:

The Ionic Project Wizard displayed in the system browser

This is a pretty cool addition, particularly for less experienced developers and users (where a GUI is definitely more helpful and user friendly than command line instructions), but unfortunately I couldn't get this to work (and, judging from these comments on the Ionic blog itself, I'm not the only developer to experience serious issues with this feature).

I double checked my system with the ionic info command:

Cordova CLI: 6.5.0 
Ionic CLI Version: 2.2.1
Ionic App Lib Version: 2.2.0
ios-deploy version: 1.9.0 
ios-sim version: 5.0.8 
OS: OS X El Capitan
Node Version: v7.4.0
Xcode version: Xcode 8.2.1 Build version 8C1002

Nothing out of the ordinary there or suggestive of any problems (at least none that I've been made aware of).

I even uninstalled and re-installed Ionic (as one commenter on the company's blog had suggested) but to no avail.

The utility kept timing out, losing the network connection or publishing the following error to the screen:

Error creating a project with the Ionic project wizard

Unfortunately this wasn't the case (as the directory did NOT exist) and, for now at least, renders the feature unfit for purpose and practically useless.

It's disappointing that the team at Ionic have pushed out a feature that appears to be riddled with bugs, particularly with its potential for helping lower level developers and non-IT users create applications.

If anyone knows of a solution to this (I.e. a system configuration that needs to be tweaked) please feel free to leave a comment below as this will be helpful to the thousands of other developers who visit this site every week.

In summary

Creating an Ionic project is pretty straightforward thanks to the extensive command line options available.

From choosing template options and framework versions to whether or not node modules or the cordova framework is to be installed the Ionic CLI tool provides developers with a lot of flexibility in how they approach creating their projects.

It's unfortunate therefore that the Ionic Project Wizard appears to be badly flawed (presuming, of course, that there are no issues with my system configuration which could be causing the feature to fail) as this would be massively helpful to those developers uncomfortable and/or inexperienced working with the command line.

Hopefully this will be resolved in future iterations of the Ionic framework but, until then, we have a pretty cool set of options available to use from the Ionic CLI itself.

If you enjoyed what you've read here then please sign up to my mailing list and, if you haven't done so already, take a look at my e-book: Mastering Ionic for further information about generating projects and troubleshooting Ionic errors.



Post a comment

All comments are welcome and the rules are simple - be nice and do NOT engage in trolling, spamming, abusiveness or illegal behaviour. If you fail to observe these rules you will be permanently banned from being able to comment.