Whenever I start a project with a new tool or framework I spend a lot of time seeking out its best practices, especially with regards to code organisation. I want to make sure that the habits I adopt early in the project won’t come back to bite me later on as the project grows to avoid refactoring swathes of code.

So when I started looking into Angular.js, I did the same thing. As it’s a Google-backed project and is one of the more popular Javascript libraries of its ilk in the development community I expected to find it easy to discover how to scale an Angular application – after all, there should be plenty of people who have developed large projects with it.

However, as I went through the tutorial and searched for example projects it became apparent that this would be harder than I expected. Even to my beginner’s eye, it was obvious the code in the tutorial would not scale – it creates single files for each ’type’ (controllers, services etc.) in the application and each one is referenced individually in the HTML file.

I knew that even a modest application with more than a few pages would likely require several of each type and that organising each one into a separate file would make maintenance much simpler. By doing this, referencing them manually in the HTML quickly becomes unfeasible as you have lots of script tags to maintain and reduced client performance when loading the application.

And yet I could not find a project template which addressed these concerns and made it simple to start building:

• angular-seed, the official project bootstrap, has the same problems
• angular-app is a step in the right direction but lacks documentation on how it works rather than just how to run it and would need lots of work to get a new project up and running
• Whilst more what I was looking for, I found AngularFun very complicated and if you’re not writing your project in CoffeeScript then you won’t be able to use all the components in the build script.

Finally, I came across Radian. It provides an interactive generator for Angular projects, loads modules with RequireJS, sets up a CSS preprocessor if you want; in short, does everything I was looking for.

It’s not perfect – its documentation was a bit lacking and setting it up required a little bit of tinkering – but otherwise I’m very pleased with the results. I’ve already contributed to the documentation which will hopefully improve the experience for other people wanting to use it.

I can understand why the Angular tutorial avoids the complexity of build tools and script loaders – it’s not straightforward to explain itself – but for anything other than a very simple application its own complexity necessitates using ancillary tools to manage it. Surely it wouldn’t be too hard to provide a build script and explain it iteratively through the tutorial?

This process highlighted to me just how important it is to provide users with tools to get started quickly and remain productive as their projects scale. Django does this well by bundling a project generator with the framework and the default structure is fairly scalable. Sites such as Django best practices are an excellent complement.

Hopefully as Angular matures and more people document their experiences of using it in larger projects it will become easier for newcomers to start building scalable applications. Tools like Radian will fill the gaps in the meantime.