UPDATE: This article is no longer up-to-date. Instead, I recommend you check our new guide to bootstrapping Express.js apps.

So, you want to build an Express.js web application, eh? Well, you’re in the right place!

In this short article I’ll hold your hand, sing you a song (not literally), and walk you through creating a bare-bones Express.js web application and deploying it on Heroku with Stormpath and Yeoman.

In the next few minutes you’ll have a live website, ready to go, with user registration, login, and a simple layout.

Step 1: Get Ready!

Before we dive into the code and stuff, you’ve got to get a few things setup on your computer!

First off, you need to go and create an account with Heroku if you haven’t already. Heroku is an application hosting platform that’s really awesome! So awesome that I even wrote a book about them (true story)! But what makes them really great for our example here today is that they’re free, and easy to use.

Once you’ve got Heroku installed you then need to install their toolbelt app on your computer. This is what lets you build Heroku apps.

Next off, you need to have Node installed and working on your computer. If you don’t already have it installed, go visit the Node website and get it setup.

Lastly, you need to install a few Node packages. You can install them all by running the commands below in your terminal:

The yo package is yeoman — this is a tool we’ll be using to create an application for us.

The generator-stormpath package is the actual project that yo will install — it is what holds the actual project code and information we need to get started.

Got through all that? Whew! Good work!

Step 2: Bootstrap a Project

OK! Now that the boring stuff is over, let’s create a project!

The first thing we need to do is create a directory to hold our new project.
You can do this by running the following command in your terminal:

You should now be inside your new project directory.

At this point, you can now safely bootstrap your new project by running:

This will kick off a script that creates your project files, and asks if you’d like to deploy your new app to Heroku. When prompted, enter ‘y’ for yes. If you don’t do this, your app won’t be live 🙁

NOTE: If you don’t get asked a question about Heroku, then you didn’t follow my instructions and install Heroku like I said to earlier! Go back to Step #1!

Assuming everything worked, you should see something like this:

Tip: For a full resolution link so you can actually see what I’m typing, view this image directly.
yo-stormpath-bootstrap

Now, if you take a look at your directory, you’ll notice there are a few new files in there for you to play around with:

  • Procfile – This file tells Heroku how to run your web app.
  • index.js – This is your web app’s main file — if you open this and look at the code you’ll see some basic initialization stuff.
  • package.json – This is your app’s setup information.
  • routes/index.js – These are where you’ll place your routes. By default, there’s one route in there to give you an idea of what to do.

We’ll get into the code in the next section, but for now, go ahead and run:

In your terminal. This will open your browser automatically, and open up your brand new LIVE web app! Cool, right?

As I’m sure you’ve noticed by now, your app is running live, and lets you sign up, log in, log out, etc. Pretty good for a few seconds of work!

And of course, here are some obligatory screenshots:

Screenshot: Yo Stormpath Index Page
yo-stormpath-index

Screenshot: Yo Stormpath Registration Page
yo-stormpath-registration

Screenshot: Yo Stormpath Logged in Page
yo-stormpath-logged-in

Screenshot: Yo Stormpath Login Page
yo-stormpath-login

Step 3: CODE THINGS! GO!

So, as of this very moment in time, we’ve:

  • Installed some tools.
  • Bootstrapped a brand new Express.js web app with user accounts that is running live on Heroku.

So now that we’ve got those things out of the way, we’re free to build a real web app! This is where the real fun begins!

For thoroughness, let’s go ahead and implement a simple dashboard page on our shiny new web app.

Go ahead and open up the routes/index.js file, and add a new function call:

Be sure to place this code above the last line in the file that says module.exports = router.

This will render a nice little dashboard page for us. See the stormpath.loginRequired middleware we’re using there? That’s going to force the user to log in before allowing them to access that page — cool, huh?

You’ve also probably noticed that we’re saying req.user.givenName in our route code — that’s because Stormpath’s library automatically creates a user object called req.user once a user has been logged in — so you can easily retrieve any user params you want!

NOTE: More information on working with user objects can be found in our official docs.

Anyway — now that we’ve got that little route written, let’s also tweak our Stormpath setup so that once a user logs in, they’ll be automatically redirected to the new dashboard page we just wrote.

To do this, open up your index.js file in the root of your project and add the following line to the stormpath.init middleware:

The nextUri setting (explained in more detail here), tells Stormpath that once a user has logged in, they should be redirected to the given URL — PERFECT!

Now, let’s see if everything is working as expected!

The last line there, git push heroku master, will deploy your updates to Heroku. Once that’s finished, just run:

To open your web browser to your app page again — now take a look around! If you log into your account, you’ll see that you’ll end up on the new dashboard page! It should look something like this:

Screenshot: Yo Stormpath Dashboard Page
yo-stormpath-dashboard

BONUS: What happens if you log out of your account, then try visiting the dashboard page directly? Does it let you in? HINT: NOPE!

Step 4: READ MORE THINGS

So if you’ve gotten this far — congrats! You are awesome, amazing, and super cool. You’re probably wondering “What next?” And, that’s a great question!

If you’re hungry for more, you’ll want to check out the following links:

  • Stormpath’s Express library documentation: https://docs.stormpath.com/nodejs/express/
  • Heroku’s Node.js documentation: https://devcenter.heroku.com/categories/nodejs
  • Yeoman’s website: http://yeoman.io/

They’re all awesome tools, and I hope you enjoy them.

Lastly — if you’ve got any feedback, questions, or concerns — leave me a comment below. I’ll do my best to respond in a timely fashion.

Now GO FORTH and build some stuff!