Quick Left

This is a blog

GIFs, tech and stuff.

Getting started with Express in Node

In this article, we'll show you how to create a basic Node.js application using the Express framework and deploy it to both Heroku and Nodejitsu.

Note: If you like this post, are a software developer, and looking to make a move to beautiful Boulder, you should consider working with Quick Left. Apply today.

Prerequisites

In order to follow along, you'll need the following:

  • Node and NPM (Node Package Manager)
    • If you are on OSX and using Homebrew, you can install Node via brew install node.
    • Otherwise, installers and downloads are available here
    • If you'd prefer a more managed approach, nvm is a rvm-esque bash script that manages Node installations, allowing you to easily have multiple versions of Node simultaneously.
  • Git
    • If you are on OSX and using Homebrew, you can install Git via brew install git
    • Otherwise, installers and downloads are available here

Verify your setup. You should see something like the following. Versions don't need to be an exact match.

If you prefer to just read along, the reference app is available at the following locations.

The Express Framework

Express

Express is a minimal Node.js web application framework, inspired by Sinatra.

Out of the box, Express provides features such as routing, templating/view rendering (via Consolidate.js), dynamic CSS support (via less | stylus), middleware (via Connect), session management, logging, application settings, and a command line interface (CLI).

Install Express

npm install -g express // global install

Create an app

Express comes with a command line interface (CLI), aptly named express.

express -h // show usage

Let's use it to create an app. To keep things simple, we'll give our app a name and otherwise just use the default options.

express express-skeleton

As you can see from the previous console output, the next steps are to install dependencies and then run the app. Let's do just that.

cd express-skeleton && npm install

That last command downloaded and installed all of our application's dependencies into a new ./node_modules folder. Now let's start the app with the following command.

node app

Try it out

View the app via curl or in a web browser, then Ctrl-C to stop the server.
curl http://localhost:3000 or open http://localhost:3000

Initialize a git repo and commit your project

Let's capture the initial state of the app by adding it to source control. Commit early and commit often...

git init
git add .
git commit -m "Initial commit"

(Optional) Create a new Github repo and commit your app there too.

Wait, what was in there?

Ok, we are off to a good start, but what do we really have? Let's look at what Express gave us in a bit more detail. It is important to note that it is not essential that you stick to the default structure provided by the Express CLI. It was simply provided as a starting point.

Open your new app's directory in your favorite editor, file explorer, or just list out the files in a terminal. (_.git and node_modules directories excluded_)
find . -print | grep -v .git | grep -v node_modules

./app.js

Primary application file. It is where your application is defined and configured and is the entry point to your app. Note that it also includes routing definitions, though only one at present.
app.get('/', routes.index);

./package.json

Package descriptor file. It contains application metadata and identifies application dependencies. Check out the resources section for more information on package.json.

./public
./public/images
./public/javascripts
./public/stylesheets
./public/stylesheets/style.css

The public/* directories and files should hopefully be self explanatory. They are simply the locations for you to store your application's public assets, such as CSS, JS, images, etc.

./routes
./routes/index.js

The routes directory contains the application's routers/controllers, though there is only one at present. It is the handler for the route defined in app.js with app.get('/', routes.index);. For a small app, you can simply add more routes in this file. If you need a greater separation of concerns, have a look at the following alternate example routing implementations.

./views
./views/index.jade
./views/layout.jade

The views directory contains the primary view files for your application. These may include pages, partials, layouts, etc.

Express utilizes Consolidate.js and thus offers many choices in the way of template engines like Jade, Haml, Handlebars, EJS, and plenty of others. Jade, a high performance template engine heavily influenced by Haml, is the default.

You'll note that Express starts us off with a layout and an index file, layout.jade and index.jade, respectively.

These files are tied together via the use of the 'block' and 'extends' keywords. The layout defines a block called content. The index then extends the layout and overrides the content block providing its own content. The net result is the index content rendered inside of the layout. Be sure to check out the Jade documentation for further information.

It is the aforementioned router (_./routes/index.js_) however that determines which page to render. Note the render call within, which takes the form of app.render(view, [options], callback) to render the index page, passing in the title, "Express".

res.render('index', { title: 'Express' });

Those are all of the files in our app - pretty simple so far...

You should now have a working skeleton Node/Express app, though admittedly a bit light on features. For the purpose of this article, let's just assume that your app has reached MVP (_Minimum Viable Product_) and you want to publish it for the world to see. Below, I will walk you through deploying your app to both Heroku and Nodejitsu, cloud based platform providers. Choose your preference and scroll to that section below.

Host your app with Heroku

Heroku is the leading open language cloud application platform and supports Ruby, Java, Python, Clojure, Scala, Node.js. and custom language buildpacks.

Signup for an account if you don't already have one.

Install the Heroku toolbelt

Heroku CLI usage

heroku

Login via the Heroku CLI

heroku login

Create a Procfile

Heroku uses a Procfile to determine which processes to run, so let's create one in our project root and tell it how to run our app. We want it to use node to execute app.js, just like we did above.

echo "web: node app > Procfile"

Start the app

You can now start your app with Foreman, which is installed via the Heroku toolbelt. Note that Foreman will start the app on port 5000, unless otherwise specified.

foreman start

Try it out

View the app via curl or in a web browser, then Ctrl-C to stop the server.
curl http://localhost:5000 or open http://localhost:5000

Commit the Procfile

git add Procfile
git commit -m "Added Procfile"

Specify the Node/NPM versions that your application is known to work with.

Heroku defaults to Node.js 0.4.7 and NPM 1.0.106, which may not be current enough for your app. Just add the following snippet to your package.json file, change the versions to suit your needs. Check here for more information.

Commit your changes

git add package.json
git commit -m "Updated Node/NPM version requirements"

Create a Heroku app

heroku create or give it a name heroku create express-skeleton

Deploy the app

git push heroku master

Set the NODE_ENV variable

Express operates differently based on environment mode, which defaults to development. For the hosted app, we'll set it to 'production'.
heroku config:add NODE_ENV=production
heroku restart

Try it out

View the app via curl or in a web browser.
curl http://express-skeleton.herokuapp.com or open http://express-skeleton.herokuapp.com

Host your app with Nodejitsu

Nodejitsu is a platform as a service provider, specializing in Node.js clouds. If you have worked with Heroku, this should seem familiar to you. It is in public beta at present, but looks very promising.

Install Jitsu CLI

npm install jitsu -g // global install

Jitsu CLI usage

jitsu

Signup for a free account, if you don't already have one

jitsu signup
Then just follow the prompts. You'll be asked for a username, email, password.

Update your startup script

In order for the upcoming deployment step to complete properly, I had to first update package.json and add the .js extension to my startup script.
"start": "node app.js"

Be sure to commit your change once complete.

git add package.json
git commit -m "Added .js extension to start script."

Deploy your app

jitsu deploy
Then just follow the prompts. You'll be asked for the subdomain that you wish to use for your app. eg) express-skeleton.jit.su Your subdomain will also be added to your package.json file. Be sure to commit the update once complete.

git add package.json
git commit -m "Added subdomain"

NOTE: You can use the Nodejitsu web interface to deploy (and monitor) an app as well.

Set the NODE_ENV variable

As mentioned previously, Express operates differently based on environment mode, which defaults to development. For the hosted app, we'll set it to 'production'.
jitsu env set NODE_ENV production
jitsu apps restart

Try it out

View the app via curl or in a web browser.
curl http://express-skeleton.jit.su or open http://express-skeleton.jit.su

Wrapping up

Ok great, we have created a skeleton Node.js app using the Express framework and have deployed it to Heroku and/or Nodejitsu.

I would of course now encourage you to explore more details around the Express framework. Be sure to check out the Express wiki and project examples. The wiki describes modules that may be used to extend Express, template engines, and alternate frameworks that build upon Express.

If Express feels a bit light on features to you, for example if you are a Ruby developer and generally prefer Rails to Sinatra, then you may wish to have a look at some of the Rails inspired frameworks built with Express, such as Locomotive, RailwayJS, or Tower.js.

Thanks for reading - see you next time!

Resources

Node.js

package.json

Express

Heroku

Nodejitsu