Update 2/29/16: These code examples have been updated to reflect the 3.0 release of the express-stormpath integration.

Today we’re going to be building a simple web app with Express.js, Stormpath, and Heroku.

The app we’re going to build is really basic. It will:

  • Have a simple home page which links to a login / registration page.
  • It will allow users to create a new account.
  • It will allow users to log into an existing account.
  • It will have a simple dashboard page that just displays a user’s account information.
  • It will have a logout page that logs the user out of their account.
  • It will run live online.

And that’s it!

Want to watch a video instead of reading this article? If so, you can just watch our YouTube video instead of continuing!


Before getting started, you’ll need to sign up for Heroku. If you aren’t already familiar with them — Heroku is an application platform that lets you easily deploy web apps.

It won’t cost you any money — through this article we’ll be deploying our web application live using Heroku’s free tier =)

The rest of this article assumes you already have a Heroku account, and the Heroku CLI tool.

We’ll also be using Stormpath in this article (that’s us!). Stormpath is a service which stores your user accounts securely, and makes user registration / login / logout / a bunch of other stuff much simpler. Stormpath will handle all user accounts in this sample application, greatly reducing the amount of code we need to write.

Creating a Project

To begin, let’s create a new project!

Open up your terminal, go into a directory you like, then create a new project directory:

Next, you’ll want to go into your new project directory and initialize it as a Git repository:

Now that we’ve created our project directory, let’s go ahead and create a new Heroku app:

The above command will create a new application on Heroku (this is where we’ll eventually deploy our project live).

Lastly, we need to provision the Stormpath Heroku addon. This is totally free, and can be installed by running:

Initializing our Node App

Since we’ll be writing our web app using Express.js, the Node.js web framework, we now need to properly initialize our Node web app!

To do this, you’ll need to first initialize a Node module:

This will prompt you to answer several questions: just fill them in with any filler information you’d like.

Once you’re done with this — you’ll have a new file named package.json in your directory — this holds your Node module’s information.

Since you now have a base package.json file to work with, let’s go ahead and install all of the required Node modules we’ll be using in our project:

The above command will install both:

It will also modify your package.json and add those two libraries as dependencies. This will later be used by Heroku to install and provision your web app.

Writing the App

Now that we’ve got our Node module setup, and our Heroku app created, let’s actually write our Express.js code!

Create a new file named index.js and insert the following code:

The above code is commented for clarity, but let’s quickly recap what is happening here.

Firstly, at the top of the file we’re importing the two libraries we need to make this application work: express and express-stormpath:

Next, we’re creating an Express application object — this is the base of all Express.js web applications:

After that, we’re initializing the Stormpath library and telling Express how to use it:

This code is going to do a few things for us:

  • It provides built in registration, login, and logout pages.
  • It handles all user sessions securely.
  • It stores all users in a Stormpath application (that’s what the URL is for).
  • Once a user logs in, it will redirect the user to the /dashboard page automatically.
  • All of this happens magically behind the scenes.

In the next two code blocks we’re writing some Express routes which render a home page (/) and a dashboard page (/dashboard) for users:

The first route is simply linking users to the login page.

The second route is a bit special — it is:

  • Using the stormpath.loginRequired middleware helper. This means that users can’t access the /dashboard page without logging in first.
  • Using the user’s account (req.user) to welcome the user by printing their email.

Stormpath automatically provides you with a special object, req.user, inside of all your Express.js route code once a user has logged in.

You can use this to access a user’s information:

  • req.user.givenName – the user’s first name
  • req.user.surname – the user’s last name
  • req.user.middleName – the user’s middle name
  • req.user.email – the user’s email
  • and much more!

Lastly, we’re telling our Express application to run a web server and accept all incoming user requests:

NOTE: When running web apps on Heroku, you’ll be assign a random port number to run on. This is why we’re listening on a port specified via an environment variable.

Final Touches

Now that we’ve written our Express.js app, let’s make some final touches before deploying our site live, and testing it out!

Firstly, let’s create a new file called Procfile, with the following contents:

This Procfile tells Heroku how to run our web app. When we deploy our application live, Heroku will get a copy of our code, then simply run node index.js to start our webserver.

We’ll also create a .gitignore file and add the following contents:

This ensures that we won’t accidentally store our node modules in our Git repository.

Lastly, you’ll want to run:

This will commit your project into Git.

We’re now ready to deploy our app!

Deploying our App

To deploy the app to Heroku, all we need to do is push our Git code to Heroku:

This will send our code to Heroku, and automatically start up our new web app!

Once this process has finished, simply run:

And Heroku will open your browser and show you your brand new web application — live! If you share this URL with someone else, they’ll be able to view it just fine.

Testing our App

Feel free to click around and explore the web app!

As you can see, you should now be able to easily create new user accounts, log in, and log out of the web app.

If things worked properly, you should be able to do the following:

Stormpath Heroku Express Demo

If you run into any errors, you can view your Heroku logs by running:

In the command line.


In just a few minutes, using Express.js, Stormpath, and Heroku, we were able to build and deploy a basic Node.js website that:

  • Lets users create new accounts.
  • Renders a basic dashboard page.
  • Lets users log into their accounts.
  • Lets users log out of their accounts.

Not bad, right?!

If you found this useful, please be sure to checkout our official Stormpath Express Documentation! It covers lots more things like:

  • Customizing the built-in login / registration pages.
  • Customizing the way user authentication and authorization works.
  • Using social login with Facebook and Google.
  • Securing a REST API with Stormapth.
  • etc.