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 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.
Node.js is a platform based on Chrome's JavaScript runtime, called 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. 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 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:
$ gruntThis 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:
$ grunt watchThe built files will be in build/. See the main README 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:
// ...
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:
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:
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:
$ grunt clean
$ grunt html2js
$ grunt jshint
$ grunt karma:continuous
$ grunt concat
$ grunt ngmin:dist
$ grunt uglify
$ grunt recess
$ grunt index
$ grunt copyBut 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:
$ grunt
$ grunt defaultWe 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 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:
{
"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
$ bower installit 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, 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:
$ bower install angular-grid --save-devBower 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.
That's it! Now that you have a basic understanding of the tools involved, read through the main README 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!