# The Tools Used in `ngBoilerplate` ## Introduction `ngBoilerplate` is standards-based, so it uses all the usual tools to manage and develop client-side code. If you've developed modern, highly-organized JavaScript projects before, you are probably already familiar with at least most of these tools. What follows is a simple description of the tools of which this project makes use and how they fit in to the `ngBoilerplate` picture. ## Git [Git](http://git-scm.com/) is a distributed version control system. `ngBoilerplate` uses git to manage its codebase. While in theory you don't have to use Git once you download `ngBoilerplate`, this project makes the assumption that you do. If you're on GitHub, I assume you already have a basic understanding of Git, which is all you need to make effective use of this project. You just need to be able to commit and push and junk - nothing funky. If you're not familiar with it, check out the documentation linked to above. GitHub also has a great [help section](https://help.github.com/). ## Node.js & NPM [Node.js](http://nodejs.org) is a platform based on Chrome's JavaScript runtime, called [V8](http://code.google.com/p/v8/). It allows you to develop all kinds of software using the JavaScript you already know and love. A great feature of Node.js is its wide variety of existing libraries and tools. As the developer community is absolutely massive and incredibly active, Node.js has a basic package manager called NPM that you can use to install Node.js-based software and libraries from the command line. While `ngBoilerplate` makes heavy use of Node.js behind the scenes, you as the application developer don't need to really think about it much. Most of the interaction with Node.js will occur through Grunt (see next section), so you really only need to know how get the initial setup working. `package.json` is an NPM package description file written in JSON. It contains basic metadata about your application, like its name, version, and dependencies. By default, several packages are required for the build process to work; so when you first start with `ngBoilerplate` you have to tell NPM to install the packages; this is covered in detail in the [main README](README.md). Some of the required packages are Grunt build tasks (see below), while others are command-line tools either we (or the build system) need, like Karma, Grunt, and Bower. Don't worry about knowing Node.js in order to use `ngBoilerplate`; Grunt is where the magic happens. ## Grunt.js [Grunt](http://gruntjs.com) is a JavaScript task runner that runs on top of Node.js. Most importantly, Grunt brings us automation. There are lots of steps that go into taking our manageable codebase and making it into a production-ready website; we must gather, lint, test, annotate, and copy files about. Instead of doing all of that manually, we write (and use others') Grunt tasks to do things for us. When we want to build our site, we can just type: ```sh $ grunt ``` This will do everything needed and place our built code inside a folder called `bin/`. Even more magical, we can tell Grunt to watch for file changes we make so it can re-build our site on-the-fly: ```sh $ grunt watch ``` The built files will be in `build/`. See the main [README](README.md) for more info. The next time we change a source file, Grunt will re-build the changed parts of the site. If you have a Live Reload plugin installed in your browser, it will even auto-refresh your browser for you. You lazy bum. Grunt is controlled through `Gruntfile.js`. This file is heavily documented in the source, so I will only provide a high-altitude overview here. Also note that unless you need to modify the build process, you don't need to know anything else from this section. The two commands above really are all you need to know to get started with `ngBoilerplate`. But for those curious or looking to go a little more advanced, here's what you'll find. First, we tell Grunt which tasks we might want to use: ```js // ... grunt.loadNpmTasks('grunt-recess'); grunt.loadNpmTasks('grunt-contrib-clean'); grunt.loadNpmTasks('grunt-contrib-copy'); grunt.loadNpmTasks('grunt-contrib-jshint'); // ... ``` Each of these tasks must already be installed. Remember the dependencies from `package.json` that NPM installed for us? Well, this is where they get used! Then we get the opportunity to tell the tasks to behave like we want by defining a configuration object. While we can (and do) define all sorts of custom configuration values that we reference later on, tasks look for configuration properties of their own name. For example, the `clean` task just takes an array of files to delete when the task runs: ```js clean: [ '<%= build_dir %>', '<%= compile_dir %>' ], ``` In Grunt, the `<%= varName %>` is a way of re-using configuration variables. In the `build.config.js`, we defined what `build_dir` meant: ```js build_dir: 'build', ``` When the clean task runs, it will delete the `build/` folder entirely so that when our new build runs, we don't encounter any problems with stale or old files. Most tasks, however, have considerably more complicated configuration requirements, but I've tried to document what each one is doing and what the configuration properties mean. If I was vague or ambiguous or just plain unclear, please file an issue and I'll get it fixed. Boom - problem solved. After our configuration is complete, we can define some of our own tasks. For example, we could do the build by running all of the separate tasks that we installed from NPM and configured as above: ```sh $ grunt clean $ grunt html2js $ grunt jshint $ grunt karma:continuous $ grunt concat $ grunt ngmin:dist $ grunt uglify $ grunt recess $ grunt index $ grunt copy ``` But how automated is that? So instead we define a composite task that executes all that for us. The commands above make up the `default` tasks, which can be run by typing *either* of these commands: ```js $ grunt $ grunt default ``` We also define the `watch` task discussed earlier. This is covered in more detail in the main (README)[README.md]. Grunt is the engine behind `ngBoilerplate`. It's the magic that makes it move. Just getting started, you won't need to alter `Gruntfile.js` at all, but as you get into more advanced application development, you will probably need to add more tasks and change some steps around to make this build your own. Hopefully, this readme and the documentation within `Gruntfile.js` (as well as of course the documentation at gruntjs.com) will set you on the right path. ## Bower [Bower](bower.io) is a package manager for the web. It's similar in many respects to NPM, though it is significantly simpler and only contains code for web projects, like Twitter Bootstrap and its AngularJS counterpart Angular Bootstrap. Bower allows us to say that our app depends in some way on these other libraries so that we can manage all of them in one simple place. `ngBoilerplate` comes with a `bower.json` file that looks something like this: ```js { "name": "ng-boilerplate", "version": "0.2.0-SNAPSHOT", "devDependencies": { "angular": "~1.0.7", "angular-mocks": "~1.0.7", "bootstrap": "~2.3.2", "angular-bootstrap": "~0.3.0", "angular-ui-router": "~0.0.1", "angular-ui-utils": "~0.0.3" }, "dependencies": {} } ``` This file is fairly self-explanatory; it gives the package name and version (duplicated from `package.json`, but this is unavoidable) as well as a list of dependencies our application needs in order to work. If we simply call ```sh $ bower install ``` it will read these three dependencies and install them into the `vendor/` folder (along with any dependencies they have) so that we can use them in our app. If we want to add a new package like AngularUI's [ngGrid](http://angular-ui.github.io/ng-grid/), then we can tell Bower to install that from the web, place it into the `vendor/` folder for us to use, and then add it as a dependency to `bower.json`: ```js $ bower install angular-grid --save-dev ``` Bower can also update all of our packages for us at a later date, though that and its many other awesome features are beyond the scope of this simple overview. One last thing to note is that packages installed with Bower are not standardized, so we cannot automatically add them to the build process; anything installed with Bower (or placed in the `vendor/` directory manually) *must* be added to your `build.config.js` file manually; look for the Bower libs included in `ngBoilerplate` by default in there to see what I mean. ## Where to Go From Here That's it! Now that you have a basic understanding of the tools involved, read through the [main README](README.md) to dive another level deeper and apply what you've learned for great good. I promise it will all make sense it short order. Happy programming!