Lab 03: The Project Layout

Lab Length: 10 minutes


Understand the folder structure for an Ionic project and where to place files.

Note: For this lab, I will be using Visual Studio Code as our editor but you can use any text editor. The install steps for Visual Studio Code are in Lab 01: Ionic Setup

Table of Contents

3.0: Opening Project in Visual Studio Code

  1. Open Visual Studio Code
  2. Click File -> Open Folder…

    VSCode File Open Folder Menu

  3. Navigate to where you create the myFirstApp folder and click Select Folder

    VSCode Select Folder

  4. Your project should now be opened in Visual Studio Code, similar to this screenshot.

    VSCode Initial Folder Opened View

3.1: Exploring Project Layout

  1. With the myFirstApp highlighted, click on the arrow next to the project name.

    VSCode Initial Folder Opened View

  2. Top level project used for structure:

     ├── hooks              extra commands to run on cordova build
     ├── platforms          iOS/Android specific builds will reside here
     ├── plugins            where cordova plugins will be installed
     ├── scss               SASS code, which will output to www/css/
     ├── www                your application code
     ├── bower.json         bower dependencies
     ├── config.xml         cordova configuration
     ├── gulpfile.js        gulp tasks
     ├── ionic.project      ionic configuration file
     └── package.json       npm & cordova platforms/plugins dependencies
  3. Expand the www folder

    VSCode WWW Folder Expanded

  4. www folder structure:

    ├── css            your stylesheet files
    ├── img            your image files
    ├── js             your javascript files
    ├── lib            vendor javascript such as Ionic and Angular
    ├── template       used to store the view html (not yet created).
    └── index.html     main file. js/css/angular/ionic references

3.2: Suggested Structure

There are two trains of thought on how to structure your project depending on the size of the project. The first option is by type and the second option is by page.

3.2.1: Structure By Type

In this structure you create directories to hold controllers, services, directives, etc. and all of the files of that type for the project are stored in the directory.

This structure works great when your project is small. However, as the project grows it can quickly become unwieldy to find the file that you are looking for. I can typically handle 8-10 files in a single directory before it becomes annoying to me to find a file.

For this workshop, we are going to use this structure.

If later on you decide to change the structure to Structure By Page, luckily it is just directory reorganizations and updating the index.html with the javascript reference. This becomes even easier if you go through the extra lab, Auto Add JS/CSS to index.html where I walk you through adding a gulp task to automate the updating of the javascript and css references in the index.html.

example layout

├── js                                  javascript files files

    ├── controllers                     all of the controllers

        ├── projects.controller.js      controller for projects page
        ├── tasks.controller.js         controller for projects page

    ├── services                        all of the services/factories

        ├──        services for projects page
        ├──           services for projects page

    ├── directives                      custom directives

        ├── projects.directives.js      directories for project page
        ├── tasks.directives.js         directories for project page

    ├── config                          configurations, constants, etc

├── templates                           html for pages

    ├── projects.html                   html for project page
    ├── tasks.html                      html for tasks page

3.2.2: Structure By Page

In this structure you create a directory for each page and that directory contains all of the page specific files for controller, services, directives, etc.

This structure works great for large parts that have lots of files. You can use it even on smaller projects but it is a bit of overkill. With this structure though you don’t have to worry about the number of files in a single directory becoming too much as each page typically have less than 5 files.

example layout

├── projects                        all of the controllers

    ├── projects.controller.js      all files for projects page
    ├── projects.html               html for project page
    ├──        services for projects page
    ├── projects.directives.js      directories for project page

├── tasks                           all files for task page

    ├── tasks.controller.js         controller for projects page
    ├── tasks.html                  html for tasks page
    ├──           services for projects page
    ├── tasks.directives.js         directories for project page

├── services                        global services/factories

    ├── user.service.js             reusable service for users

|── directives                      global directives

├── config                          global configurations

3.3 Angular Coding Style

The Angular Style Guide by John Papa is a good starting point for Angular development teams to provide consistency through good practices. This workshop will use the suggested practices in John Papa’s style guide. You are free to use any style that you would like or that your team has defined as long as it is consistent among the team/projects.

In the words of John Papa:

“If you are looking for an opinionated style guide for syntax, conventions, and structuring Angular applications, then step right in. These styles are based on my development experience with Angular, presentations, Pluralsight training courses and working in teams. The purpose of this style guide is to provide guidance on building Angular applications by showing the conventions I use and, more importantly, why I choose them.”

View the Angular Style Guide


Before we start coding up our application need to do some configuration for Visual Studio Code. In the next lab we will setup Visual Studio Code for ionic and angular snippets and Intellisense so that we can debug our application right instead Visual Studio Code.

back to top 