MEAN Boilerplate

MEAN Boilerplate is a template/starter project for apps that want to use the MEAN stack: MongoDB, Express, AngularJS, and Node.js. This project uses Grunt to automate the build and development process. Including continuous automatic linting with JSHint and unit tests with Nodeunit for the backend and Karma with Jasmine for the front-end. The AngularJS front-end uses Bower to manage third party packages.

The intent of this project is to make it simple and easy to start a MEAN project. Just clone, install packages, and go.

Quick Start

Firstly, you need Node.js and MongoDB installed.

If you don't have Grunt then you will need to install it:

$ npm install -g grunt-cli

If you don't have Bower then you will also need to install it:

$ npm install -g bower

Now inside a Terminal, go to the project directory and install the packages with npm:

$ npm install

This will install all the dependencies enumerated into the package.json file.

Once that's done, go into the public directory and run Bower:

$ bower install

This will install all the front-end packages in the lib folder.

Usage

First start MongoDB in a separate Terminal:

$ mongod

Then go to the project root and run Grunt:

$ grunt

$ grunt default

This will run the default Grunt task. The default task will run JSHint, Nodeunit, Karma, and build the index file for the front-end based on the index.tpl.html file. It will then continously watch for file changes and run JSHint and the unit tests after each change.

Any changes to the back-end code will also result in an automatic restart of the server.

All you need to do is make changes, save, watch the console output, and then try out your changes. No need to rebuild or restart the server manually!

Project Structure

mean-boilerplate/
  |- api/             (back-end controllers)
  |- build/           (where builds are placed)
  |- node_modules/    (packages installed by npm)
  |- public/          (the AngularJS front-end)
    |- app            (the main AngularJS app files)
    |- assets         (assets like images)
    |- css            (CSS files)
    |- lib            (third party libraries installed by Bower)
    |- partials       (AngularJS partials/views)
  |- routes/          (routing files)
  |- server/          (Express application)
  |- tests/           (unit tests)
    |- api            (back-end tests)
    |- public         (front-end tests)

The directory structure inside these directories can generally be anything you want. The front-end expects all folders except the partials folder. Views and partials can be placed in the app folder if you prefer. The general structure is taken directly from the angular-seed project.

The api folder comes with TestController.js that simply demonstrates a controller to handle actions. The routes folder has two files for back-end and front-end routing. The front-end routing file (public.js) only passes routes to the front-end. Explicit front-end routing is handled by AngularJS in the normal way.

The server.js files sets the /public directory to serve static files so that root (/) goes to the front-end. It then sets the back-end routes in routes/api.js to /api/*. Followed lastly by setting up any additional or unhandled routes to the front-end.

Making a Build

There is another Grunt task called build. This task will do a clean of any existing builds, runs JSHint, Nodeunit, Karma, copies files to the builds folder, concats application JavaScript, concats application CSS, minifies the application JavaScript, and creates the appropriate index.html file for the front-end.

This is all placed in the build folder and can be deployed. You can always test this build manually by going to project root and running:

$ node build/server/server.js

You can then go to http://localhost:3000 to see your front-end or http://localhost:3000/api to hit your back-end.

Tools Used

This project relies heavily on existing tools and projects by the open source community. Obviously there is use of Node.js, MongoDB, Express, AngularJS, Grunt, and Bower.

On top of that is Nodeunit for back-end tests, Karma with Jasmine for front-end tests via the Grunt tasks grunt-contrib-nodeunit and grunt-karma respectively.

Watching for file changes is made possible by grunt-contrib-watch. Automatic Node.js server restarts on file changes made possible by nodemon via the Grunt task grunt-nodemon. Concurrent running of Watch and nodemon made possible by grunt-concurrent. File concatenation is made possible by grunt-contrib-concat. Various other mundane and thankless tasks by grunt-contrib-copy, grunt-contrib-clean, and grunt-contrib-uglify.

JavaScript linting is made possible by JSHint via the Grunt task grunt-contrib-jshint.