Using SuperTokens with Angular and Firebase

Part II: A quick overview of SuperTokens

This post is the second of my four-part series:

• Part I: Evaluating the alternatives
• Part II (this article): A quick overview of SuperTokens
• Part III: Setting up the application
• Part IV: Integrating SuperTokens with Angular and Firebase

SuperTokens provides a decent overview on its website. Instead of regurgitating their documents word for word, I will take a look from the perspective of an Angular+Firebase developer. SuperTokens does not provide out-of-the-box support for Angular or Firebase, but they do provide helpful documentation. Also, their Discord channel is a great place to ask for help. I found the SuperTokens team more than willing to help me get my demo project off the ground when I ran into trouble. Their response was lightening fast, and they saved me loads of time.

Because SuperTokens is a relative newcomer in the field, I think their developers were sensitive to contemporary application development, and designed their system in a way to make integration quite easy. Firebase Auth on the other hand, seems to me to exist because it filled a necessary gap. The Firebase developers made a great system that fills its purpose, but its scope is quite narrow. To go out of that narrow scope requires custom development, or simply abandoning it all together.

SuperTokens achieves simplicity by partitioning their system into 3 parts: frontend, backend, and core, and providing corresponding modules that integrate with your application.

SuperTokens as a Managed Service

The frontend part is an SDK that gets imported as a library into your application code. A quick npm i -s supertokens-web-js will import the SuperTokens frontend SDK, or at least the part you need to manage authentication sessions. If you want a pre-built UI to drop into your app, there is no direct support for Angular, but they do offer a React Component, which can be embedded into Angular without much ado. In that case npm i -s supertokens-auth-react react react-dom will do the trick. I found the frontend integration to be really quite simple.

The backend integration is also quite straightforward. The process is similar to the frontend. You simply import the SuperTokens backend SDK into your server code. This SDK integrates with your backend APIs. For instance, if using an Express backend, simply npm i -s supertokens-node then initiate the code by calling Session.init(), and SuperTokens will include a number of routes to handle the various authentication processes. The magic happens when the frontend and the backend communicate with each other seamlessly. There really is not much to configure at all.

To round out the system, the SuperTokens core is the part that keeps state, and makes the system function as a whole. Because SuperTokens is open source software, you can spin up your own self-managed server for free, or simply purchase the reasonably-priced managed service, which also offers a generous free tier. I went for the simplicity of the managed service and have no regrets.

Different projects have different needs. Some projects only need to offer email+password support. Some apps want to go passwordless. Many apps want to use “social login”, a.k.a. Google, Microsoft, GitHub et al. SuperTokens has thought about authentication from the application developer’s perspective, and provides a list of “recipes”. The list of recipes include Passwordless, Email password + Social Login, Phone Password Login, Session Management, and many others. I imagine that the list will continue to grow over time.

The “recipes” are more than just figurative: they are actually baked into the code. When initializing any of the SuperTokens modules, you need to provide the recipes that you want the system to provide. Here is an example that includes the ThirdPartyEmailPassword and Session recipes.

SuperTokens.init({
  ...
  recipeList: [
    ThirdPartyEmailPassword.init({...}),
    Session.init(),
  ],
});

I highly recommend that you start with one of the prebuilt demos in the GitHub repo. There are quite a few moving parts, so although the concept and the integration is simple in principle, there are still many small technicalities that could go wrong in practice. I got off to a few false starts because I was trying to change too many things all at once. So, I took a deep breath, went back and started from one of the working demos they make available, and refactored step-by-step until I got what I wanted. This allowed me to apply incremental changes such that I could immediately fix all the small issues along the way. I love the recipe idea, but frankly I would have saved some time had I just started from the demo instead of trying to follow along with the recipe. The recipes are great, but IMO more useful for the type of iterative approach that I mention. So my advice: (1) start with the working demo, (2) make your initial design and development strategy, then (3) use the recipes to help guide your development.

Currently, SuperTokens does not provide any support for Firebase. In my case, I wanted to use Firebase Functions as my backend, and be able to share authentication sessions with Firestore. Although there is no direct support, and therefore no automatic integration, it is possible to integrate without too much difficulty. This will be the topic of my next post.

Next: Setting up the application