Heads up… this article is old!

For an updated version of this article, see Tutorial: Build a Basic CRUD App with Node.js on the Okta developer blog.

Update Building for mobile not web? Check out our latest tutorial Build a REST API for Your Mobile Apps Using Node.js. Also, these code examples have been updated to reflect the 3.0 release of the express-stormpath integration.

Here at Stormpath we <heart> Node.js – it’s so much fun to build with! We’ve built several libraries to help node developers achieve user management nirvana in your applications.

If you’ve built a web app before, you know that all the “user stuff” is a royal pain. Stormpath gives developers all that “user stuff” out-of-the-box so you can get on with what you really care about – your app! By the time you’re done with this tutorial (less than 15 minutes, I promise), you’ll have a fully-working Express app.

We will focus on our Express-Stormpath library to roll out a simple Express.js web application, with a complete user registration and login system, with these features:

  • Login and Registration pages
  • Password reset workflows
  • A profile page for your logged in users
  • A customizable home page
  • The ability to add other Stormpath features in our Express-Stormpath library (API authentication, SSO, social login, and more)

In this demo we will be using Express 4.0, we’ll discuss some of the great features of Express 4.0 as we go along. I will be using my Mac, the Terminal app, and Sublime Text for a text editor.

What is Stormpath?

Stormpath is an API service that allows developers to create, edit, and securely store
user accounts and user account data, and connect them with one or multiple applications. Our API enables you to:

In short: we make user account management a lot easier, more secure, and more
scalable than what you’re probably used to.

Ready to get started? Register for a free developer account!

Create your Node.js application

Got your Stormpath developer account? Great! Let’s get started.. vroom vroom

If you don’t already have Node.js on your system you should head over to Node.org and install it on your computer. In our examples we will be using a Mac, all commands you see should be entered in your Terminal (without the $ in front – that’s a symbol
to let you know that these are terminal commands)

Step one is to create a folder for this project and change into that directory:

Now that we are in the folder we will want to create a package.json file for this project. This file is used by Node.js to keep track of what libraries (aka modules) your project depends on. To create the file:

You will be asked a series of questions, for most of them you can just press enter to allow the default value to be used. Here is what I chose, I decided to call my main file server.js, I set my own description and set the license to MIT – everything else I just pressed enter on:

With that I will now have a package.json file in my folder. I can take
a look at what’s in it:

Looks good! Now let’s install the libraries we want to use. You can install them all with this command:

The save option will add this module to your dependencies in package.json. Here is what each module does:

  • Express.js is the web framework that everything else is built on.
  • Express-stormpath provides convenience features that can be tied in to the Express app, making it very easy to use Stormpath’s features in Express.
  • Csurf adds CSRF protection to our forms.
  • Cookie-Parser is used to read the cookies that are created by the Csurf library.
  • Forms is a module that will take the pain out of validating HTML forms.
  • Jade is a templating engine for writing HTML pages.
  • Xtend is a utility library that makes it easy to copy properties from one JavaScript object to another.

Gather your API Credentials and Application Href

The connection between your app and Stormpath is secured with “API Key Pair”. You will provide these keys to your web app and it will use them when it communicates with Stormpath. You can download your API key pair in our Admin Console. After you login you can download your API key pair from the home page, it will download the apiKey.properties file.

While you are in the Admin Console you want to get the href for your default Stormpath Application. In Stormpath, an Application object is used to link your web app to your user stores inside Stormpath. All new developer accounts have an app called “My Application”. Click on “Applications” in the Admin Console, then click on “My Application”.

For this demonstration we will export these settings to your environment, so please run these commands in your terminal:



Now these settings will be automatically available to our server.

Writing the application entry (server.js)

It’s time to create server.js, this will be the entry point for your server application. You can do that from Sublime Text or you can do this in the terminal:

Now open that file in Sublime Text and put the following block of code in it:

In this example we’ve enabled auto-expansion of custom data – this will come in handy later when we build the profile page.

There are many more options that can be passed, and we won’t cover all of them in this demo. Please seee the Express-Stormpath Documentation for a full list

Create your home page

Let’s get the easy stuff out of the way: your home page. Create a views directory and then create a Jade file for the home page:

Now open that file in Sublime Text and put the following in it:

This is a simple view that will prompt a new visitor to log in, or greet a registered user if they have already logged in.

With that… we’ve got something we can look at!

Run your app – It’s Aliiiive!

I kid you not: your application is ready to be used. Just run this command to start the server:

This will start your app which is now running as a web server on your computer. You can now open this link in your browser:


You should see your home page now:

Simple Node.js App Home

Go ahead, try it out! Create an account, you will be redirected back to the home page and shown your name. Then logout and login again, same thing! Pretty amazing, right??

Pro tip: use a file watcher

As we move forward we will be editing your server files. You will need to restart the server each time. You can kill the server by typing Ctrl + C in your Terminal. But I suggest using a “watcher” that will do this for you.

I really like the Nodemon tool. You can install it globally (it will always be ready for you!) with this command:

After installation, you can then run this command:

This will start your server and watch for any file changes. Nodemon will automatically restart your server if you change any files – sweet!

Create the profile page

A common feature of most sites is a “Dashboard” or “profile” page – a place where your visitor provide some essential information.

For example purposes, we’re going to build a profile page that allows you to collect a shipping address from your visitors. We will leverage Custom Data, one of the most powerful features of stormpath

To begin, let’s create a new view for this dashboard:

And a JavaScript file where the route handler will live:

Now we’ve got some copy-and-paste work to do. These two files are pretty big, so we’ll explain them after the paste.

Paste this into profile.js:

Paste this into profile.jade:

Breaking down your app

You’ve just created an Express Router. Saywha? I really like how the Express maintainers have described this:

… saywha?

In my words: Express 4.0 encourages you to break up your app into “mini apps”. This makes everything much easier to understand and maintain. This is what we’ve done with the profile.js file — we’ve created a “mini app” which handles JUST the details associated with the profile page.

Don’t believe me? Read on.

Plug in your profile page

Because we followed the Router pattern, it’s now this simple to add the profile page to your existing server.js file (put it right above the call to app.on('stormpath.ready'):

Omg. Yes. YES. You’ve just decoupled the implentation of a route from it’s addressing. Holy grail? Almost. Awesome? Most Def. (By the way, you’ve also forced authentication on this route, using Stormpath, nice!)

Restart your sever and visit /profile, you should see the form now:

Simple Node.s App Profile Page

Breaking down your app – for real

Okay, there’s a LOT more to talk about here. So let me cover the important points:

  • The profile.js file is a builder or constructor, so to speak. You have to invoke it as a method in order to get the router out of it. That’s why we have that empty () after the require('./profile') statement. Why bother? Because with this pattern you can pass in any options that may be required for this router. At the moment we don’t have any, but who knows what the future holds? Doing this give you room to use this router in multiple web apps and factor out any app-specific config.
  • We are using the forms library to create a schema for the profile form. This is a good practice because it separates the way in which we validate from the formv from the way in which the form is displayed.
  • We have a renderForm function which is responsible for creating the view model of the form — this model is passed down to the Jade layer, so that profile.jade has all the properties it needs for rendering the form. This render function ensures that our template layer doesn’t blow up with missing values
  • We are using the Csurf library to add CSRF tokens to the form as a security measure. This is done automaticaly for the default forms (login, registration, password reset), but because this is a new, custom router, we have to setup those details manually
  • We reach into the Express-Stormpath library to grab our collectFormErrors function, a handy utility for pulling validation errors out of the response we get from the forms library. Note to self: PR that in to forms library!
  • We make use of the loginRequired middleware to ensure that users are logged in before they can use this profile page

Wrapping it up

Alas, we’ve reached the end of this tutorial. You now have a web app that can reigster new users and allow them to provide you with a shipping address, pretty sweet right?

Following the profile example you now have everything you need to start building other pages in your application. As you build those pages, I’m sure you’ll want to take advantage of some other great features, such as:

Those are just a few of my favorites, but there is so much more!

Please read the Express-Stormpath Product Guide for details on how to implement all these amazing features — and don’t hesitate to reach out to us!

WE LOVE WEB APPS and we want your user management experience to be 10x better than you ever imagined.

-robert out

Like what you see? Follow @gostormpath to keep up with the latest releases.