<commit_before># [ngBoilerplate](http://joshdmiller.github.com/ng-boilerplate) [![Build Status](https://travis-ci.org/joshdmiller/ng-boilerplate.png?branch=master)](https://travis-ci.org/joshdmiller/ng-boilerplate)

An opinionated kickstarter for [AngularJS](http://angularjs.org) projects.

***

## Quick Start

Install Node.js and then:

```sh
$ git clone git://github.com/joshdmiller/ng-boilerplate
$ cd ng-boilerplate
$ sudo npm -g install grunt-cli testacular
$ npm install
$ grunt watch
```

Happy hacking!

## Purpose

`ngBoilerplate` is designed to make life easy by providing a basic framework
with which to kickstart AngularJS projects. It contains a best-practice
directory structure to ensure code reusability and maximum scalability.
ngBoilerplate also comes prepackaged with the most popular design frameworks
around: [Twitter Bootstrap](http://getbootstrap.com), [UI
Bootstrap](http://angular-ui.github.com/bootstrap), [Font
Awesome](http://fortawesome.github.com/Font-Awesome), and
[LESS](http://lesscss.org).  Lastly, it contains a sophisticated Grunt-based
build system to ensure maximum productivity.  All you have to do is clone it and
start coding!

## Philosophy

The principal goal of `ngBoilerplate` is to set projects up for long-term
success.  So `ngBoilerplate` tries to follow best practices everywhere it can.
These are:

- Properly orchestated modules to encourage drag-and-drop component re-use.
- Tests exist alongside the component they are testing, no separate `test`
  directory required. The build process should be sophisticated enough to handle
  this.
- Speaking of which, the build system should work automagically, without
  involvement from the developer. It should do what needs to be done, while
  staying out of the way.  Components should end up tested, linted, compiled,
  and minified, ready for use in a production environment.
- Integration with popular tools (Bower only for now, hopefully others in the
  future).
- *Engourages* test-driven development. It's the only way to code.
- A directory structure that is cogent, meaningful to new team members, and
  supporting of the above points.
- Well-documented, to show new developers *why* things are set up the way they
  are.
- It should be responsive to evidence. Community feedback is therefore crucial
  to the success of `ngBoilerplate`.

But `ngBoilerplate` 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`](http://github.com/angular-app/angular-app), which does just
that - and does it well.

## Learn

### Overall Directory Structure

At a high level, the structure looks roughly like this:

```
ng-boilerplate/
  |- build/
  |- src/
  |  |- app/
  |  |  |- <app logic>
  |  |- assets/
  |  |  |- <static files>
  |  |- components/
  |  |  |- <reusable code & external libs>
  |  |- less/
  |  |  |- main.less
  |- testacular/
  |- vendor/
  |  |- angular/
  |  |- twitter-bootstrap/
  |- Gruntfile.js
  |- module.prefix
  |- module.suffix
  |- package.json
```


What follows is a brief description of each entry, but all directories contain
their own `README.md` file with additional documentation, so browse around to
learn more.

- `build/` - custom scripts for Grunt
- `src/` - our application sources
- `testacular` - test configuration
- `vendor` - files needed to make everything happen, but *not* libraries our
  application uses.
- `Gruntfile.js` - our build script; see "The Build System" below.
- `module.prefix` and `module.suffix` - our compiled application script is
  wrapped in these, which by default are used to place the application inside a
  self-executing anonymous function to ensure no clashes with other libraries.
- `package.json` - metadata about the app, used by NPM and our build script.

### Detailed Installation

`ngBoilerplate` uses [Grunt](http://gruntjs.org) as its build system, so
[Node.js](http://nodejs.org) is required. Also, Grunt by default no longer comes
with a command-line utility and Testacular must end up in your global path for
the build system to find it, so they must be installed independently. Once you
have Node.js installed, you can simply use `npm` to make it all happen:

```sh
$ npm -g install grunt-cli testacular
```

If you're on Linux (like I am) then throw `sudo` in the front of that command.
If you're on Windows, you're on your own.  Next, you can either clone this
repository using Git, download it as a zip file from GitHub, or merge the branch
into your existing repository. Assuming you're starting from scratch, simply
clone this repository using git:

```sh
$ git clone git://github.com/joshdmiller/ng-boilerplate my-project-name<commit_msg>docs(README.md): git clone needs to be recursive<commit_after># [ngBoilerplate](http://joshdmiller.github.com/ng-boilerplate) [![Build Status](https://travis-ci.org/joshdmiller/ng-boilerplate.png?branch=master)](https://travis-ci.org/joshdmiller/ng-boilerplate)

An opinionated kickstarter for [AngularJS](http://angularjs.org) projects.

***

## Quick Start

Install Node.js and then:

```sh
$ git clone --recursive git://github.com/joshdmiller/ng-boilerplate
$ cd ng-boilerplate
$ sudo npm -g install grunt-cli testacular
$ npm install
$ grunt watch
```

Happy hacking!

## Purpose

`ngBoilerplate` is designed to make life easy by providing a basic framework
with which to kickstart AngularJS projects. It contains a best-practice
directory structure to ensure code reusability and maximum scalability.
ngBoilerplate also comes prepackaged with the most popular design frameworks
around: [Twitter Bootstrap](http://getbootstrap.com), [UI
Bootstrap](http://angular-ui.github.com/bootstrap), [Font
Awesome](http://fortawesome.github.com/Font-Awesome), and
[LESS](http://lesscss.org).  Lastly, it contains a sophisticated Grunt-based
build system to ensure maximum productivity.  All you have to do is clone it and
start coding!

## Philosophy

The principal goal of `ngBoilerplate` is to set projects up for long-term
success.  So `ngBoilerplate` tries to follow best practices everywhere it can.
These are:

- Properly orchestated modules to encourage drag-and-drop component re-use.
- Tests exist alongside the component they are testing, no separate `test`
  directory required. The build process should be sophisticated enough to handle
  this.
- Speaking of which, the build system should work automagically, without
  involvement from the developer. It should do what needs to be done, while
  staying out of the way.  Components should end up tested, linted, compiled,
  and minified, ready for use in a production environment.
- Integration with popular tools (Bower only for now, hopefully others in the
  future).
- *Engourages* test-driven development. It's the only way to code.
- A directory structure that is cogent, meaningful to new team members, and
  supporting of the above points.
- Well-documented, to show new developers *why* things are set up the way they
  are.
- It should be responsive to evidence. Community feedback is therefore crucial
  to the success of `ngBoilerplate`.

But `ngBoilerplate` 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`](http://github.com/angular-app/angular-app), which does just
that - and does it well.

## Learn

### Overall Directory Structure

At a high level, the structure looks roughly like this:

```
ng-boilerplate/
  |- build/
  |- src/
  |  |- app/
  |  |  |- <app logic>
  |  |- assets/
  |  |  |- <static files>
  |  |- components/
  |  |  |- <reusable code & external libs>
  |  |- less/
  |  |  |- main.less
  |- testacular/
  |- vendor/
  |  |- angular/
  |  |- twitter-bootstrap/
  |- Gruntfile.js
  |- module.prefix
  |- module.suffix
  |- package.json
```


What follows is a brief description of each entry, but all directories contain
their own `README.md` file with additional documentation, so browse around to
learn more.

- `build/` - custom scripts for Grunt
- `src/` - our application sources
- `testacular` - test configuration
- `vendor` - files needed to make everything happen, but *not* libraries our
  application uses.
- `Gruntfile.js` - our build script; see "The Build System" below.
- `module.prefix` and `module.suffix` - our compiled application script is
  wrapped in these, which by default are used to place the application inside a
  self-executing anonymous function to ensure no clashes with other libraries.
- `package.json` - metadata about the app, used by NPM and our build script.

### Detailed Installation

`ngBoilerplate` uses [Grunt](http://gruntjs.org) as its build system, so
[Node.js](http://nodejs.org) is required. Also, Grunt by default no longer comes
with a command-line utility and Testacular must end up in your global path for
the build system to find it, so they must be installed independently. Once you
have Node.js installed, you can simply use `npm` to make it all happen:

```sh
$ npm -g install grunt-cli testacular
```

If you're on Linux (like I am) then throw `sudo` in the front of that command.
If you're on Windows, you're on your own.  Next, you can either clone this
repository using Git, download it as a zip file from GitHub, or merge the branch
into your existing repository. Assuming you're starting from scratch, simply
clone this repository using git:

```sh
$ git clone --recursive git://github.com/joshdmiller/ng-boilerplate my-project-name
{'fraction_non_alphanumeric': 0.09006242963872685, 'fraction_numerical': 0.0, 'mean_word_length': 3.9959100204498976, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2507985', 'n_tokens_mistral': 2910, 'n_tokens_neox': 2732, 'n_words': 1223}