SuperTokens Node Enhancers

A simple set of utilities used for making the supertokens-node package more compatible with SSR frameworks.

Philosophy: Why Custom SuperTokens Utilities?

Currently, the supertokens-node package really only works well in settings that support middleware, like express. However, a middleware-based approach is highly incompatible with the emerging SSR frameworks today. This package aims to bridge the gap between supertokens-node and various SSR frameworks by creating utilities that enable SuperTokens to be used in a flexible, more robust way. In fact, this approach is so flexible that it will enable you to get SuperTokens working with popular SSR frameworks like Svelte Kit and SolidStart.

The approach laid out here attempts to make SuperTokens more flexible by only requiring request headers as inputs (and occasionally the request method) and only returning response headers and cookies as outputs. This gives the end developer vastly greater options to choose from (especially in Svelte Kit and SolidStart).

The downside of this approach is that it requires knowledge of supertokens-node internals. However, the SuperTokens team plans to simplify their tools to mimic the flexibility pursued/attained by this package. This package is only a temporary stand-in until the team finishes this work. Until then, I will keep this package up-to-date so that everything works correctly.

For more details on why I chose the approach and object structures that I did, see the following:

• ITenthusiasm/remix-supertokens#5

How It Works

The approach is simple: Whenever a SuperTokens function (e.g., Session.getSession) would require you to pass a request object, replace the request object with an instance of SuperTokensData.Input. You can pass any data that the function needs into the constructor of SuperTokensData.Input. (Usually this will only be the reqest headers. Occasionally, you might need the request method due to a limitation of the internals of supertokens-node.)

Similarly, whenever a SuperTokens function (e.g., Session.getSession) would require you to pass a response object, replace the response object with an instance of SuperTokensData.Output. When you're done calling all of the necessary SuperTokens functions/methods, the responseHeaders property of SuperTokensData.Output will be correctly updated with everything needed to make sure that the auth in your app behaves correctly. Just be sure to include these response headers (and cookies) in the final response that you send back to the client.

"I Don't Want to Have to Write Code..."

Although this approach requires slightly more effort (i.e., you can't rely on the more concise app.use(middleware()) and app.use(errorHandler()) to get SuperTokens working anymore), it gives you greater clarity into what your app is doing; and it gives you greater control to make sure your app is doing exactly what you want. More importantly, you will have to do this anyway if you aren't using something like a Node adapter for an SSR framework.

Disclaimer

WARNING: This implementation relies on knowledge of SuperTokens internals. Although it is unlikely that SuperTokens would alter the supertokens-node codebase in such a way that this code would break, the danger is still there. This is only intended to be a temporary solution until the SuperTokens team supports something like this approach natively in supertokens-node. Nonetheless, it's the best that we've got right now for various SSR frameworks. And I will keep this package up to date as best as I can until better alternatives appear.