The Elevator Pitch For the lazy and impatient.

ng-boilerplate is an opinionated kickstarter for web development projects. It's an attempt to create a simple starter for new web sites and apps: just download it and start coding. The goal is to have everything you need to get started out of the box; of course it has slick styles and icons, but it also has a best practice directory structure to ensure maximum code reuse. And it's all tied together with a robust build system chock-full of some time-saving goodness.


Because my team and I make web apps, and last year AngularJS became our client-side framework of choice. We start websites the same way every time: create a directory structure, copy and ever-so-slightly tweak some config files from an older project, and yada yada, etc., and so on and so forth. Why are we repeating ourselves? We wanted a starting point; a set of best practices that we could identify our projects as embodying and a set of time-saving wonderfulness, because time is money.

There are other similar projects out there, but none of them suited our needs. Some are awesome but were just too much, existing more as reference implementations, when we really just wanted a kickstarter. Others were just too little, with puny build systems and unscalable architectures. So we designed ng-boilerplate to be just right.

What ng-boilerplate Is Not

This is not an example of an AngularJS app. This is a kickstarter. If you're looking for an example of what a complete, non-trivial AngularJS app that does something real looks like, complete with a REST backend and authentication and authorization, then take a look at angular-app, which does just that, and does it well.

So What's Included? I'll try to be more specific than "awesomeness".

This section is just a quick introduction to all the junk that comes pre-packaged with ng-boilerplate. For information on how to use it, see the project page at GitHub.

The high-altitude view is that the base project includes Twitter Bootstrap styles to quickly produce slick-looking responsive web sites and apps. It also includes UI Bootstrap, a collection of native AngularJS directives based on the aforementioned templates and styles. It also includes Font Awesome, a wicked-cool collection of font-based icons that work swimmingly with all manner of web projects; in fact, all images on the site are actually font- based icons from Font Awesome. Neat! Lastly, this also includes Angular Placeholders, a set of pure AngularJS directives to do client-side placeholder images and text to make mocking user interfaces super easy.

And, of course, ng-boilerplate is built on AngularJS, by the far the best JavaScript framework out there! But if you don't know that already, then how did you get here? Well, no matter - just drink the Kool Aid. Do it. You know you want to.

Twitter Bootstrap

You already know about this, right? If not, hop on over and check it out; it's pretty sweet. Anyway, all that wonderful stylistic goodness comes built in. The LESS files are available for you to import in your main stylesheet as needed - no excess, no waste. There is also a dedicated place to override variables and mixins to suit your specific needs, so updating to the latest version of Bootstrap is as simple as:

$ cd vendor/twitter-bootstrap
$ git pull origin master

Boom! And victory is ours.

UI Bootstrap

What's better than Bootstrap styles? Bootstrap directives! The fantastic UI Bootstrap library contains a set of native AngularJS directives that are endlessly extensible. You get the tabs, the tooltips, the accordions. You get your carousel, your modals, your pagination. And more. How about a quick demo?

Oh, and don't include jQuery; you don't need it. This is better. Don't be one of those people. *

* Yes, there are exceptions.

Font Awesome

Font Awesome has earned its label. It's a set of open (!) icons that come distributed as a font (!) for super-easy, lightweight use. Font Awesome works really well with Twitter Bootstrap, and so fits right in here.

There is not a single image on this site. All of the little images and icons are drawn through Font Awesome! All it takes is a little class:

<i class="fa fa-flag"></i>

And you get one of these: . Neat!


Angular Placeholders is a simple library for mocking up text and images. You can automatically throw around some "lorem ipsum" text:

<p ph-txt="3s"></p>

Which gives you this:



Even more exciting, you can also create placeholder images, entirely client-side! For example, this:

<img ph-img="50x50" />
<img ph-img="50x50" class="img-polaroid" />
<img ph-img="50x50" class="img-rounded" />
<img ph-img="50x50" class="img-circle" />

Gives you this:

Which is awesome.

The Roadmap Really? What more could you want?

This is a project that is not broad in scope, so there's not really much of a wish list here. But I would like to see a couple of things:

I'd like it to be a little simpler. I want this to be a universal starting point. If someone is starting a new AngularJS project, she should be able to clone, merge, or download its source and immediately start doing what she needs without renaming a bunch of files and methods or deleting spare parts ... like this page. This works for a first release, but I just think there is a little too much here right now.

I'd also like to see a simple generator. Nothing like Yeoman, as there already is one of those, but just something that says "I want Bootstrap but not Font Awesome and my app is called 'coolApp'. Gimme." Perhaps a custom download builder like UI Bootstrap has. Like that. Then again, perhaps some Yeoman generators wouldn't be out of line. I don't know. What do you think?

Naturally, I am open to all manner of ideas and suggestions. See the "Can I Help?" section below.

The Tactical To Do List

There isn't much of a demonstration of UI Bootstrap. I don't want to pollute the code with a demo for demo's sake, but I feel we should showcase it in some way.

ng-boilerplate should include end-to-end tests. This should happen soon. I just haven't had the time.

Lastly, this site should be prettier, but I'm no web designer. Throw me a bone here, people!

Can I Help?

Yes, please!

This is an opinionated kickstarter, but the opinions are fluid and evidence-based. Don't like the way I did something? Think you know of a better way? Have an idea to make this more useful? Let me know! You can contact me through all the usual channels or you can open an issue on the GitHub page. If you're feeling ambitious, you can even submit a pull request - how thoughtful of you!

So join the team! We're good people.