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:
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:
- Windows Users: See the MongoDB Windows installation docs.
- Mac Users: See the MongoDB OXS installation docs.
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:
