Over the course of this series, we’ll be making a blog – the quintessential learning project – using Angular.js, Express.js, Browserify, UserApp and Orchestrate.

To start, let’s explore the cornerstones of the JavaScript package ecosystem: NPM and Bower.

Dependencies

To follow along, you’ll need to install a few things:

  • Node.js, the infamous JavaScript platform
  • Bower, a tool for managing client-side dependencies
  • Karma, a testing framework for client-side code built by the Angular.js team

Install Node.js using the binaries on its website. Once you’ve got it, install Bower and Karma like this:

sudo npm install -g bower karma-cli

This gives you command-line access to the bower and karma commands, which we’ll use to install browser dependencies and run our browser tests.

Project Skeleton

Before we write any code, let’s discuss our project’s file structure. JavaScript projects are relatively unopinionated about where files should go (unlike, say, Rails), so it’s best to make choices that make sense to you. I suggest the following structure based on projects I’ve written, maintained, observed, and admired. It separates our concerns between the server and the client, and between the implementation and its tests:

bin/
    'bin' stores any executables, primarily the thing that actually starts and runs our website.
client/
    'client' will store our client-side JavaScript code.
server/
    'server' will store our server-side JavaScript code.
public/
    'public' contains our public assets, like our CSS and JavaScript.
test/
    client/
        Our browser-side tests.
    server/
        Our server-side tests.
views/
    HTML templates
readme.md
    Explains the what, why, and how of our project.

Do this to generate those files and folders:

mkdir orc-blog && cd $_
mkdir bin client server public test views
touch readme.md

This project architecture separates client and server code, and provides straightforward access to other resources, like our HTML templates, which both our server and client code will interact with.

Server Dependencies

NPM is the Node.js ecosystem’s package manager, and a shining gem of one, too. To start, we’ll get NPM to create a package.json file which describes our project and its dependencies:

npm init

This asks you questions about your project, like its name, description, author, license, etc., and use those to generate a package.json file. Once it’s been created, we can save our dependencies into it:

npm install --save express jade orchestrate body-parser cookie-parser express-validator static-favicon browserify jshint

This installs our dependencies into node_modules/ and saves their details to package.json.

Browser Dependencies

Bower, like NPM, is a package manager, but for the client-side JavaScript ecosystem. To start, run bower init. Like npm init, this will ask you a few questions about your project, and generate a bower.json file that will store dependency data.

When Bower installs dependencies, by default it puts them in a folder called bower_components, but because we want to expose these components for our templates to use as scripts and stylesheets, we want them until the public directory.

To change where Bower installs dependencies, create a file called .bowerrc and put this in it:

{
    "directory": "public/bower_components"
}

Now, when you install dependencies, they’ll go under the public/bower_components. Let’s try it:

bower install -S bootswatch angular userapp userapp-angular restangular

Note that some of those dependencies, like userapp, are JavaScript dependencies, while others like bootswatch, contain CSS. Bower’s ecosystem contains everything frontends need, from JavaScript to CSS and even HTML templates. You can explore what packages are in the Bower ecosystem here.

NPM Scripts

package.json can also be used to run scripts, like the ones we’ll use to compile our client code and launch our server. When you ran npm init, the resultant package.json had this block in it:

"scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
},

That scripts block details scripts that you can run using npm run [script]. The ‘test’ scripts runs with npm test, which, in this case, does this:

[email protected] test /Users/[user]/code/test
echo "Error: no test specified" && exit 1

Error: no test specified
npm ERR! Test failed.  See above for more details.
npm ERR! not ok code 0

Exactly as advertised, it prints “Error: no test specified” and exits with a failure status, so NPM knows to make a fuss.

We’ll revisit the ‘test’ script later, but for now, let’s write a ‘jshint’ script. jshint is a JavaScript code quality tool that detects inelegant or problematic JavaScript, so it’s handy for enforcing stylistic standards (such as semicolons) and catching errors before they cause problems. We already installed jshint when we installed the rest of our server dependencies, so our script in package.json looks like this:

"scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "jshint": "./node_modules/.bin/jshint bin client server test"
},

Now running npm run jshint prints this:

[email protected] jshint /Users/[user]/code/orc-blog
jshint bin client server test

Cool! It searched every file in the bin, client, server, and test folders for JavaScript files, and examined those files for JavaScript errors. Since there are no JavaScript files in any of those folders, then there can’t be any JavaScript errors in them. Wahoo!

Notice how the jshint script used an executable in ./node_modules/.bin. Whenever a dependency has an executable, like jshint, it will be installed in that folder. This lets us use executables like jshint in a more isolated manner than asking our users to install them globally.

Next Up

In the next part of this series, we will tackle writing the API that talks to Orchestrate, authorizes users, validates objects, and exposes it all to the client.

Happy coding!