A template project for a MEAN.JS style web application
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
app
config
public
test
.bowerrc
.gitignore
.jshintrc
Gruntfile.js
README.md
bower.json
karma.conf.js
package.json
protractor-conf.js
server.js

README.md

meanjs-template

Template project for a MEAN.JS application, with some changes:

  • Remove the example controllers, routes, and only supply minimal single page
  • Provide a solution for continuous integration (Jenkins) testing
  • Implement a production build solution for minimizing and combining assets
  • Include a unique ID in each log entry within a request cycle (greatly helps in debugging)
  • Show Git revision within HTML page source, and version assets
  • Use Sass
  • And some other minor things which we've found useful...

Documentation

Running the Project

To run the application, some initial setup is required:

Install Node

Since this is a Node.js project, please make sure Node is installed on the machine. A recommended install method is to use nvm which installs Node into your home directory.

Install Dependencies

Once Node is installed, from this project's root directory run the following command to install the project dependencies:

$ npm install

This will install both the server side dependencies (via npm) and client side dependencies (via bower).

MongoDB

This application requires a running instance of MongoDB. By default, the application is configured to look for this running instance on the local machine, but can be configured to point to a remote instance (see the configuration section for more information.)

If you need to install MongoDB, you can do so from the MongoDB downloads page. For help on the installation process and starting up MongoDB, please consult the installation instructions.

Start the App

** Note that because this project uses git-rev-sync to show the Git revision, the app will fail to start without a Git history available. ** For more information on how to solve this, please see the Problems section.

This project is configured to load separate configuration based on the environment where it is run (for example, development vs production). The environment is specified via the NODE_ENV environment variable. If no environment is specified, it will default to development.

To start the application (in development mode), execute the following command:

$ npm start

This script will call grunt specifying the development environment. If you wish you specify an environment, use grunt directly and include the NODE_ENV environment variable. For example, to start the project in test environment, execute the following command:

$ NODE_ENV=test grunt

The current available environments include:

  • development
  • test
  • production

Production

In production mode the application is setup to use minified assets on the client side (along with template caching via Angular). Grunt is used to do this via the grunt build task. To execute this build task, run the following command:

$ npm run build

To start the server in the production environment, execute the following command:

$ npm run production

This command does not use grunt, and therefore does not use nodemon to monitor for file system changes. This was done to allow a separate "production" process to monitor the state of the server.

Configuration

Most all of the app's configuration is held within the cofig/env/all.js file. Some of these values can be specified via environment variables. Below is a list of those variables:

  • Node Server
    • PORT : The port for the node application server, defaults to 3000 in all environments, except test, which defaults the port to 3001
  • Mongo
    • MONGO_PROTOCOL : The protocol for the mongodb connection, defaults to mongodb://
    • MONGO_HOST : Hostname for mongodb, defaults to localhost
    • MONGO_PORT : Port for mongodb, defaults to 27017
    • MONGO_DATABASE : The database to use for mongodb, defaults to meanjs-template

Tests

There are tests for both the server side code and the client side code. The server side and client side unit tests are written using Jasmine, but the client side unit tests run using Karma. There are also end to end tests for the client which use Protractor.

Setup

Project dependencies are required for tests as well, so please make sure the dependencies are installed.

Run All Tests

To run all the tests, execute the following command:

$ npm test

Grunt is used to bundle all the test execution into one command. For more information on how this is done, please see the Gruntfile.js file -- specifically the test task.

Run Tests for Continuous Integration

In a continuous integration environment (such as Jenkins), the tests have been configured to use only Firefox for a browser, and generate test reports in an XML format that resembles JUnit. To run the tests in continuous integration mode, execute the following:

$ npm run ci

For more information on running Firefox without a GUI, see: http://stackoverflow.com/a/16311264.

Additional Test Run Actions

To run the server side tests in a "watch" mode (re-runs the tests after each change):

$ npm run test-server-watch

To run the client side karma unit tests in a "watch" mode:

$ npm run test-client-watch

To run the protractor tests:

$ npm run protractor

Problems

Starting the app, or running the Protractor tests results in the error:

RangeError: Maximum call stack size exceeded

Since this project uses the git-rev-sync to establish a Git revision history, if one is not available, it will look in a parent directory recursively. This can cause this error. To avoid this, initialize the Git repo on this project and issue a commit:

$ git init; git add .; git commit


If there are any other problems, please open an issue.