Bradley Braithwaite
1 import {
2 Learning,
3 JavaScript,
4 AngularJS
5 } from 'Brad on Code.com'
6 |
Check out my online course: AngularJS Unit Testing in-depth with ngMock.

MEAN Stack Tutorial Part 1 - Initial Setup & Installation

Part 1 of the MEAN Stack Tutorial.

12 Feb 2015 Free Software Tutorials by Bradley Braithwaite
mean stack tutorial

This is Part 1 of a 5 part Mean Stack Tutorial.

We’re going to make use of a MEAN stack template from meanjs.org to get up and running. In it’s own words it’s an Open-Source Full-Stack Solution For MEAN Applications. Meanjs is useful for this tutorial since it provides an app structure and has its own templates for scaffolding components.

If you don’t already have GIT installed, you will need it:

I tested this tutorial using GIT 2.2.1. If you run into any issues such as bower ECMDERR Failed to execute “git ls-remote –tags –heads you may need to update your version of GIT.

To run server side JavaScript and for the database we need to install:

  • Node.js - for the web server and running server side JavaScript.
  • MongoDB - the database.

IMPORTANT: this tutorial is only supported with Node.js version 0.12.0. Please see the following link for details of how to switch node runtime versions. If you hit any errors during the installation process, please double check the node version you are running.

The Database installation required some extra configuration:

The key part is that a folder \data\db needs to be created. The locations differ based on the platform.

Required Packages

Once Node.js and MongoDB are installed we need some packages via the NPM Package Manager. NPM is a package manager like Nuget, Macports, Ruby Gems etc. It’s possible to search fir and download many 3rd party libraries to use via NPM. NPM will already be installed as part of Node.js.

The required packages are:

  • bower - A package manager for the web. We use NPM for server side node.js modules and Bower manages front-end packages like angular, jquery etc. See the npm bower package for more info.

  • grunt-cli - This is required so that we can run Grunt tasks from the CLI. See the npm grunt-cli package for more info. Grunt is a JavaScript task runner that can be used to automate tasks such as deployment steps, unit testing, linting etc.

  • yo - This is required so that we can run Yeoman generators from the CLI. See the npm yo pacakage page for more info. Yeoman is a plugin that can be run with the ‘yo’ command to scaffold complete projects or useful parts.

  • generator-meanjs - This is the Yeoman generator for Meanjs. We will make use of this to scaffold components of our app, saving us a lot of typing. See the npm generator-meanjs package page for more info.

Here are the commands to run in the terminal to get these packages:

Windows Users: You can run these commands via Node.js Command Prompt (comes with Node install), Powershell or if you have installed Git for Windows via the Git bash emulator.

npm install -g bower
npm install -g grunt-cli
npm install -g yo
npm install -g generator-meanjs@0.1.12 

Versioning: This tutorial is based upon the branch 0.4.0 of meanjs and version of 0.1.12 the mean generator.

Creating the App Template

Navigate to your usual place for code repositories and create a new folder for the app.

mkdir NorthwindNode
cd NorthwindNode

We will start by templating the app itself using the generator-meanjs package we installed. Enter the following CLI command:

yo meanjs --skip-install

You will be presented the options:

What would you like to call your application?
How would you describe your application? 
How would you describe your application in comma seperated key words? 
What is your company/author name? 
Would you like to generate the article example CRUD module? <CHOOSE NO!>
Which AngularJS modules would you like to include?
  • Choose a name for your app.
  • You can leave default values for description, author etc.
  • Choose NO for the option ‘Would you like to generate the article example CRUD module?’.
  • You will be asked to choose what angular modules you would like. If in doubt, leave defaults and hit return.

It will take a few moments to generate the app.

Once it has completed the following folders/files are created:

  • app - all the server side code is here.
  • public - all the front-end code is here.
  • config - contains config settings such as database connections etc .
  • node_modules - this is where all 3rd party packages from NPM are stored.
  • Other files are setup/config related

Notable files:

/server.js - this is the entry point for the app in order to start the service on the server side.

/config/express.js - this initialises the Express Web Framework instance with the necessary configuration.

/gruntfile.js - the config file for the Grunt task runner.

Next we need to install the app’s dependencies via NPM:

npm install --dev
bower install

Note: You may need to run this with elevated permissions depending on your setup.

It will take a few moments for this to complete.

Errors?: be aware that a number of Windows users have hit problems at the NPM install stage of this tutorial. If you hit errors at this stage it is recommended to remove the Karma testing sections (the tests that run in the browser) from the application’s config. In order to do this, update the gruntfile.js and package.json files here. Re-try the npm install step after updating the files.

You can experiment with Grunt by running commands such as:

grunt lint
grunt test

Note that the words lint and test map to config in the gruntfile.js. An important thing to note is that there is a grunt task that automatically re-starts the web server and re-loads client side JavaScript (by refreshing the browser) whenever we save a file within the project. This is very handy as it saves a lot of time, in particular on the server side since the default behaviour with Node.js is that we would need to re-start the webserver to see changes made since the last re-start.

The Grunt setup also runs jshint each time you hit save. Jshint is a linter for javascript, so if you miss out a semi-colon or forget a closing curly brace whilst working through the tutorial it will show a warning in the terminal and tell you the type of error, the file and line number. Be warned!

You can read more about the mean.js folder structure should you wish to.

Runnning the App

To run the app we first need to start up the processes for:

  • the database
  • the web server

To start the database service open a new CLI window and run:

Mac/Linux Users:

mongod

Windows Users:

C:\mongodb\bin\mongod.exe

If all went well the final line of the output from running the mongod command will state:

[initandlisten] waiting for connections on port 27017

Next we can start the web server, in a new terminal window enter:

npm start

If the server started without error you will see:

MEAN.JS application started on port 3000

You can now browse to http://localhost:3000 to see a default page.

Experiment with the default login/register profile functionality that Mean.js provides us this out of the box, which saves us a lot of time.

You may notice the grunt command in the CLI output. To recap, Grunt is used to minify css, javascript, run linters, start the web server manage config and so on.

The command npm start actually masks running the command Grunt. Take a look at package.json in the root folder and find the section:

  "scripts": {
    "start": "grunt",
    "test": "grunt test",
    "postinstall": "bower install --config.interactive=false"
  }

The below line maps npm start to the same thing as running grunt in the CLI:

 "start": "grunt",

The next line in the section maps npm test to the command grunt test:

"test": "grunt test",

By running the following command we run some of the default tests that come with the template:

npm test

Failing tests? If you see the error ‘cannot find module socket.io-client’ in the console/powershell output, try re-installing the karma test runner (this ocassionally affects Windows users):

npm install karma

Testing the App

There are some default tests in the template. These can be run via the CLI:

npm test

Assuming that the database is still running you should see passing tests. We won’t cover tests in much detail for this tutorial but it is useful to know about the following technology for testing included with the meanjs stack:

  • Mocha - Mocha is a feature-rich JavaScript test framework running on node.js and the browser, making asynchronous testing simple. I see it used in 90% of node.js libraries and projects I’ve worked with.
  • Karma - Karma allows tests to be run in the browser. This is useful when testing front-end functionality. This was developed by the AngularJS team at Google (it was formally called Testacular) so you will likely see this in use for most Angular apps.

These topics are worthy of tutorials in their own right. For now it’s enough to know that these technologies exists and when we run npm test, tests for the server side (mocha) and front-end (karma) will be run.

Editing Files

Before we move on, if you don’t already have a text editor installed you may want to check out Sublime Text. If you use Visual Studio, I believe it is possible to work with Node.js in VS, but I’ve yet to try this out!

Next Tutorial

In the next tutorial we will start working through the server side API.

View the Full Source on Github

The full source for this project is hosted on Github. Note that this version is evolving and may differ slightly from this tutorial as new features are added for the subsequent tutorials.

https://github.com/bbraithwaite/NorthwindNode

You can find a starter version of the app, that is the same as running ‘yo meanjs’, and that has the Karma config removed for easier NPM install, here:

https://github.com/bbraithwaite/NorthwindStart

SHARE
Don't miss out on the free technical content:

Subscribe to Updates

CONNECT WITH BRADLEY

Bradley Braithwaite Software Blog Bradley Braithwaite is a software engineer who works for search engine start-ups. He is a published author at pluralsight.com. He writes about software development practices, JavaScript, AngularJS and Node.js via his website . Find out more about Brad. Find him via: