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!

Prerequisites

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:

$ mkdir stormpath-test 1 2 $ mkdir stormpath - test

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

$ cd stormpath-test $ git init 1 2 3 $ cd stormpath - test $ git init

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

$ heroku create 1 2 $ heroku create

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:

$ heroku addons:create stormpath 1 2 $ heroku addons : create stormpath

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:

$ npm init 1 2 $ npm init

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:

$ npm install express express-stormpath --save 1 2 $ npm install express express - stormpath -- save

The above command will install both:

Express (the web framework) and

Express-Stormpath (the Stormpath Express library)

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:

// Import required modules. var express = require('express'); var stormpath = require('express-stormpath'); // Initialize our Express app. var app = express(); // Configure Stormpath. app.use(stormpath.init(app, { application: { href: process.env.STORMPATH_APPLICATION_HREF }, website: true, web: { login: { nextUri: '/dashboard' } } })); // Generate a simple home page. app.get('/', function(req, res) { res.send("Hey there! Thanks for visting the site! Be sure to <a href='/login'>login</a>!"); }); // Generate a simple dashboard page. app.get('/dashboard', stormpath.loginRequired, function(req, res) { res.send('Hi: ' + req.user.email + '. Logout <form action="/logout" method="POST"><button type="submit">Logout</button></form>'); }); // Listen for incoming requests and serve them. app.listen(process.env.PORT || 3000); 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 // Import required modules. var express = require ( 'express' ) ; var stormpath = require ( 'express-stormpath' ) ; // Initialize our Express app. var app = express ( ) ; // Configure Stormpath. app . use ( stormpath . init ( app , { application : { href : process . env . STORMPATH_APPLICATION_HREF } , website : true , web : { login : { nextUri : '/dashboard' } } } ) ) ; // Generate a simple home page. app . get ( '/' , function ( req , res ) { res . send ( "Hey there! Thanks for visting the site! Be sure to <a href='/login'>login</a>!" ) ; } ) ; // Generate a simple dashboard page. app . get ( '/dashboard' , stormpath . loginRequired , function ( req , res ) { res . send ( 'Hi: ' + req . user . email + '. Logout <form action="/logout" method="POST"><button type="submit">Logout</button></form>' ) ; } ) ; // Listen for incoming requests and serve them. app . listen ( process . env . PORT | | 3000 ) ;

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:

// Import required modules. var express = require('express'); var stormpath = require('express-stormpath'); 1 2 3 4 // Import required modules. var express = require ( 'express' ) ; var stormpath = require ( 'express-stormpath' ) ;

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

// Initialize our Express app. var app = express(); 1 2 3 // Initialize our Express app. var app = express ( ) ;

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

// Configure Stormpath. app.use(stormpath.init(app, { application: { href: process.env.STORMPATH_APPLICATION_HREF }, website: true, web: { login: { nextUri: '/dashboard' } } })); 1 2 3 4 5 6 7 8 9 10 11 12 13 // Configure Stormpath. app . use ( stormpath . init ( app , { application : { href : process . env . STORMPATH_APPLICATION_HREF } , website : true , web : { login : { nextUri : '/dashboard' } } } ) ) ;

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.

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:

// Generate a simple home page. app.get('/', function(req, res) { res.send("Hey there! Thanks for visting the site! Be sure to <a href='/login'>login</a>!"); }); // Generate a simple dashboard page. app.get('/dashboard', stormpath.loginRequired, function(req, res) { res.send('Hi: ' + req.user.email + '. Logout <form action="/logout" method="POST"><button type="submit">Logout</button></form>'); }); 1 2 3 4 5 6 7 8 9 10 // Generate a simple home page. app . get ( '/' , function ( req , res ) { res . send ( "Hey there! Thanks for visting the site! Be sure to <a href='/login'>login</a>!" ) ; } ) ; // Generate a simple dashboard page. app . get ( '/dashboard' , stormpath . loginRequired , function ( req , res ) { res . send ( 'Hi: ' + req . user . email + '. Logout <form action="/logout" method="POST"><button type="submit">Logout</button></form>' ) ; } ) ;

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.

middleware helper. This means that users can’t access the 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

– the user’s first name req.user.surname – the user’s last name

– the user’s last name req.user.middleName – the user’s middle name

– the user’s middle name req.user.email – the user’s 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:

// Listen for incoming requests and serve them. app.listen(process.env.PORT || 3000); 1 2 3 // Listen for incoming requests and serve them. app . listen ( process . env . PORT | | 3000 ) ;

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:

web: node index.js 1 2 web : node index . js

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:

node_modules 1 2 node_modules

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

Lastly, you’ll want to run:

$ git add . $ git commit -m "First commit!" 1 2 3 $ git add . $ git commit - m "First commit!"

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:

$ git push heroku master 1 2 $ git push heroku master

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

Once this process has finished, simply run:

$ heroku open 1 2 $ heroku open

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:

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

$ heroku logs --tail 1 2 $ heroku logs -- tail

In the command line.

Recap

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: