Larger Angular apps can be difficult to setup due to the many moving parts involved. Various Angular seed apps exist that provide some of the boilerplate code involved, to help you develop your app more quickly. However, what most add in removing the boilerplate you need to write, they take away in adding unneeded complexity, or simply don’t follow best practice coding conventions. So I created my own Angular seed app – the Untangled Angular Seed – which I’ve just made available on GitHub.
What you want from a good Angular Seed app
When writing even a moderately large Angular app, you’ll want to do many things. In particular:
- you’ll create many files, but you don’t want to include each one in a separate script tag
- you’ll want to concatenate your app files into one large file, but debug the individual source files, not one giant concatenated monster
- you’ll want your library files to be concatenated into a separate large file, so you don’t need to rebuild them every time your app code changes
- you’ll want an easy way to serve your files without having to install Apache
- you’ll want to test your files easily, without having to configure Karma, and without having to add each new file explicitly to karma.conf.js
- you’ll want to ensure your app is written according to best practice, with a proper folder structure and everything else the legendary John Papa recommends
- you’ll want your directives’ partials to be compiled into one module automatically, so you can use templateUrl without thinking
- you’ll want your directives’ partials to be available to your tests, rather than relying on mock partials served through
- you’ll want all the dependencies that Angular and Karma need to be installed for you, so you don’t need to hunt them down
- you’ll want bower to install your production libraries (i.e. Angular) and npm to install your development libraries (build tools, testing tools, and all the rest)
- you’ll want to install it all with a single command on the terminal
- …and run it with a single command, too
- you won’t want the HTML to be too fussy, as you’re more interested in the bootstrapping an Angular app than writing perfect production-ready HTML
- you’ll quite like Bootstrap, Lodash and jQuery to be installed as well, to speed the development process up.
That’s quite a list, but unfortunately, it’s what’s required of a modern AngularJS app.
Fortunately, the build tools that now exist can automate much of this for us. They’re not easy to configure, though, and there are so many different tools that do similar things, it can be hard to know which one you should use.
That’s why seed apps can be so useful – they provide the build tools for you, already configured, and ensure they work with Angular to create your app as simply as possible.
Why I created my own Angular seed
An Angular seed app should aim for three things:
- Integrate with Angular to ensure Angular’s specific requirements (e.g. modularising directive partials, and setting up the test runner) are automated
- Be written using best practice guidelines
Every Angular app I’ve used, though, will give you two of these things. To me, that wasn’t good enough, and it stopped me using the seed apps. It’s frustrating installing a seed app, only to find it doesn’t use the component folder hierarchy, or it assigns your Angular module to a global variable, or it doesn’t compile your directive partials.
So I set out to resolve this by creating my own Angular Seed App that achieves all three of these aims, and does so in a way that the HTML gets out of your way, letting you focus on your app code’s design.
This, then, is the Untangled Angular Seed.
The Untangled Seed App features a minimal HTML scaffolding page with just enough HTML for your app to work (in HTML5 mode, no less, so all the routes work without the pesky
!# messing up your URLs).
The folder structure is based on the recommended component-based structure used by John Papa in his excellent AngularJS style guide. As such, there are no controller folders, directive folders, service folders, etc.; rather, folders are for individual components, and everything pertaining to a component (controllers, services, directives, even partials and tests) goes into its folder.
Also based on John’s style guide is the app code itself, with
controllerAs used to namespace the controllers, controllers defined according to their routes rather than the use of the
ng-controller directive, modules defined in IIFEs rather than assigned to global variables,
templateUrl used in directives in order to separate presentation (directive partials) from logic, and super-thin controllers.
The Build System
The app is built using Gulp, with plugins to minify and concatenate the code, provide source maps out of the box so you can debug your source files rather than the concatenated code, and modularise your directives’ partials so that they can be injected into your app and tests.
All the minified third-party library files are concatenated for you separately from the app’s files, so you don’t need to worry about polluting your app code with someone else’s library code. It also means whenever you make a change to your code, the unmodified library files aren’t rebuilt.
All of this is taken care of for you by gulp, with a clean
Installing the App
Full details for installing the app can be found on the Untangled-Angular-Seed repo in GitHub.
In a nutshell, though, clone the repo to a local directory of your choice, and install all its dependencies using:
This install all the dependencies the app and its libraries need, either via
Running the App
The app must first be built in order to minify and concatenate both the app code and the libraries. You do this as follows:
Once built, you run the code using:
Once run, just browse to
localhost:8080 and there is your Angular Seed App ready for you to start developing! It even runs a live reload watcher, so any change you make in your app code is automatically rebuilt and reloaded.
Need More Help?
Full Details of installing, running and using the app can be found in the GitHub repo, and also in the About page of the app itself. If you have any questions about it, any issues you’ve found, or any suggestions for improving it, just raise them on GitHub.