There are thousands and more developers working daily on apps, regardless of their being web, desktop or mobile applications and independently of the technologies used in them. A very big number of these apps launched daily are built with AngularJS, and they can be of different sizes: very small, small, medium or large scale apps.
Keeping in mind the size and the goal that your application is trying to achieve, you do the scaling and structuring of it. How do you do that?
1. Where do you start structuring your app?
As your app size gets bigger, the need to structure them efficiently in order to make it easier to manage, maintain and work on becomes more and more pressing. There are several ways to approach the structuring, but only one real rule: Do it how you like it best! If it is easier for you to work while having all your files in one big pile, then that works too!
However, there are some very basic rules that I like to keep in mind, as advised by Google Developer Expert John Papa:
- Locating your code easily.
- Identifying your code parts quickly.
- Keeping a Flat structure for as long as it’s comfortable to work with.
- Trying to keep from repeating code parts
I find the task of locating files in a folder oftentimes tedious, especially when the size of the app starts to grow. This becomes even more important when you’re working with a whole team. After you make sure the locating of the complete files is done easily, you want to make sure to have parts of code on an easy reach, as you might need to reuse them. And the re-usability of parts or modules of code is another important factor that should be kept in mind. Not repeating yourself when writing code can save time and even make your code easily understandable. The last one to tackle is trying to keep a structure as flatter as possible. It’s rarely convenient to have to go 6 folders deep in order to locate one file. Think of navigation bars: anything deeper than 2 levels and you’re toast!
These rules would apply in structuring your app regardless of the technology you’re using, they only have to do with the way we understand what others (or even us) have written before and how can we make it easier for others to work with or maintain our code. These are also called the LIFT rules, as an acronym for the four elements above.
That is what’s important, and how do you go about reaching these objectives is entirely up to you and how you are more comfortable working.
2. The box of pencils
Let’s use an analogy to better explain the structuring of your app, since simple everyday examples make the matter easier to understand. Supposing you’re a 5 year old who has a very big box of pencils in your disposal. You can just keep the pencils mixed up in there, and search and find the one you need when you need it, regardless of their color, or type or what it’s used for. This is a solution applicable to your app; just keep all the files in one big folder. It may even work, and very well at that, with one simple catch: your app’s size. Provided your app is an extra small one with only basic features, then this is a solution that you can implement in oder to save much time and unneeded layering.
What happens when the size starts to grow?
3. Sorting your app out by type
So you can’t just throw all your pencils together in the box because you have too much. Now what? Now, the logical step would be to sort all of them out into groups, which is usually done based on type. You have a small to medium sized single page app with a considerable number of files that you want to structure in order to get the easy access and maintainability you’re aiming for. What type of files would they be?
First we would have the app.js file containing the angular module and most of the code. Then we’d have a bunch of controllers, some directives, probably also some services and filters. Moreover, we would have different HTML files for each of the views. Pretty basic, right? So how do we throw those together?
The structure below is one of the most common ones, where we sort our files by type:
structure.js
app/
controllers/
mainController.js
otherController.js
directives/
mainDirective.js
otherDirective.js
services/
userService.js
itemService.js
js/
bootstrap.js
jquery.js
app.js
views/
mainView.html
otherView.html
index.html
We have grouped up our files into two big groups: the app and the views. In the second folder, and also the smallest one we have put the HTML files for each of the views that will appear in our SPA, named in our case mainView.html, otherView.html and index.html.
In the first folder which we named app, we have placed four folders and a Javascript file. That file would be app.js, containing our angular modules and other general code, while the rest of it will be divided into other folders based on the type of file. We will place all the controllers into one directory named after it, namely mainController.js and otherController.js in our case. Then there are the directives, named mainDirective.js and itemService.js, nd after it the services. At last, we have a directory named js in which we place all the Javascript files such as the Bootstrap Javascript file, the jQuery one, and even custom Javascript files.
It’s a philosophy that works for as long as the app is not very big in size, because then you would have to look for a view and it’s corresponding controller in different places which may be in different depths and not easily located. In this case, we do the structuring based on another factor: we sort by features.
4. Sorting your app by feature
Say you’re building a blog, with a separate controller for each post. If later on you would want to make adjustments, you would have to find the respective blog directive, controller, the view, and maybe even the service in order to get a complete picture and start making the necessary edits. Once you have more than 10 controllers, views and directives, you are going to have to do a lot of scrolling in your directory tree to find the required files. In this case, we have to change our approach: an ideal AngularJS structure should be modularized into very specific functions.
An example of an app structure would look like below:
structure.js
app/
shared/
sidebar/
sidebarDirective.js
sidebarView.html
article/
articleDirective.js
articleView.html
components/
home/
homeController.js
homeService.js
homeView.html
blog/
blogController.js
blogService.js
blogView.html
app.module.js
app.routes.js
assets/
img/
css/
js/
libs/
index.html
At first glance, this structure looks more complicated and is more difficult to understand, at least for a newcomer on your team, or a beginner in Angular, which is also one of the reasons why usually tutorials follow the sorting based on type, since it’s clearer. Let’s start explaining this structure based on the one above.
The first file (or the last one, depending on how you look at the list) is index.html. This file is the one primarily handling the loading in all the libraries and Angular elements. The other one is the assets folder which is also pretty standard. It will contain all the assets needed for your app that are not related to your AngularJS code, and is organized usually according to each app.
After that we have the app folder, which will contain all the relevant code for your app in which you will find two other directories and two files. The files are app.module.js, which contains the angular module and the dependencies injected, and app.routes.js in which we place all the routes and configuration. The directories we mentioned are shared and components. In the first one we place all the partials and reusable components of our app. In the latter we place the rest of the code in mini Angular apps.
The shared folder will contain the individual features that your app will have. These features will ideally be directives that you will want to reuse on multiple pages. Features such as article posts, user comments, sliders, and others should be crafted as directives. Each component here should have it’s own subfolder that contains the directive JavaScript file and the template HTML file. In some instances, a directive may have it’s own services JavaScript file, and in the case that it does it should also go into this subfolder.
The last one is the components folder, in which we place all the actual sections of the Angular app. These includes the static views, directives and services for that specific section of the site (for example an admin users section, gallery creation section, etc). Each page should have it’s own subfolder with it’s own controller, services, and HTML files. Each of these components will resemble a mini-MVC application by having a view, controller and potentially services file of it’s own. If the component has multiple related views, it may be a good idea to further separate these files into ‘views’, ‘controllers’, ‘services’ subfolders. Each of the components can be built as a separate Angular app using the structuring philosophies we mentioned, which is why this part is oftentimes referred to as a mini Angular app.
5. Summary
By now, you should be able to understand the two options you have in structuring your Angular apps, and also modify them according to the needs of your team, the people who will later on use or/and maintain your code, or even to make it easier to work on it yourself.
