Using SuperTokens in a VueJS App With Your Own UI

This post will guide you on how to add authentication to a VueJS app with SuperTokens using your own UI. We will be building our own authentication forms and will be using to make those forms work. supertokens-web-js What is SuperTokens? SuperTokens is an open source project that lets you add authentication to your app quickly. It offers various authentication methods (called recipes). Alongside a prebuilt UI, it also offers a vanilla JS SDK called that you can use to build your own UI. In this tutorial we’ll learn how to use the to add authentication to a VueJS application. We’ll focus on the email password and social login flow, but you can as well. supertokens-web-js supertokens-web-js choose another auth method Architecture SuperTokens is built out of three components: Frontend SDK Backend SDK A microservice that talks to a database (called the SuperTokens Core). We’ll build our own login, signup and reset password forms. Then we’ll use the SDK in our Vue app to make these forms functional by invoking the relevant functions for each action. These functions will interact with the APIs exposed via the SuperTokens SDK that is integrated into your backend layer. supertokens-web-js For the backend we’ll use the SDK. The APIs exposed by this SDK will further talk to the SuperTokens Core to read/write information to the database. supertokens-node The SuperTokens core service can be either self hosted (and connected to your own db), or be hosted by the team behind SuperTokens (sign up on ). In the blog, we will be using a free, demo version of the core hosted on supertokens.com https://try.supertokens.com Frontend Start by creating a new Vue app: npm init vue@latest We’ll enable Vue Router and Typescript for the project. Choose yes for them in the prompt: ✔ Project name: … ... ✔ Add TypeScript? … Yes ✔ Add Vue Router for Single Page Application development? … Yes ... Scaffolding project in ./ ... Done. Once that’s done, head inside the project and install the following dependencies: npm i supertokens-node supertokens-web-js cors dotenv express npm-run-all The library will be used on the frontend to add authentication and reset password functionality to your custom UI and the library will be used on the backend to expose the auth API routes. supertokens-web-js supertokens-node Call the function supertokens-web-js init We’ll initialize the SDK in our Vue app’s root file, i.e. : supertokens-web-js /src/main.ts import ThirdPartyEmailPassword from "supertokens-web-js/recipe/thirdpartyemailpassword"; import Session from "supertokens-web-js/recipe/session"; SuperTokens.init({ appInfo: { appName: "SuperTokens Vue ThirdPartyEmailPassword Example", apiDomain: "http://localhost:3001", }, recipeList: [ThirdPartyEmailPassword.init(), Session.init()], }); In the above code, the function initializes on the frontend. We call this function in the root file of our application, so that we can use the session management feature across the entire application. It also indicates the type of authentication we want to use - in our case, it’s social login + email password ( recipe). init supertokens-web-js ThirdPartyEmailPassword Create HTML template AuthView Now we’ll start by creating the HTML template that renders the signup and signin UI. As an example, you can refer . this HTML template The template file calls the following functions to handle social login and signup/login using email and password: : This function allows users to authenticate via their Github account onGithubPressed : This function allows users to authenticate via their Google account onGooglePressed : This function is fired when the user enters their email and password to signup or login. onSubmitPressed Create AuthView state and template functions We’ll render this HTML template in an component inside which will also contain the implementations for the above functions: AuthView /src/views/AuthView.vue We’ll start by creating states to store the data for authentication such as the email, password, error messages for our template: // ... data() { return { // we allow the user to switch between sign in and sign up view isSignIn: true, // this will store the email and password entered by the user. email: "", password: "", // any generic error states error: false, errorMessage: "Something went wrong", // any error states specific to the input fields. emailError: "", passwordError: "", }; } Then we will create a function which will use the SDK. We’ll pass the email and password to this method and redirect the user to the route if authentication is successful. This function will be called from the function if the state is . signIn supertokens-web-js "/" signIn onSubmitPressed isSignIn true signIn: async function (_: Event) { const response = await ThirdPartyEmailPassword.emailPasswordSignIn({ formFields: [ { id: "email", value: this.email, }, { id: "password", value: this.password, }, ], }); if (response.status === "WRONG_CREDENTIALS_ERROR") { // the input email / password combination did not match, // so we show an appropriate error message to the user this.errorMessage = "Invalid credentials"; this.error = true; return; } if (response.status === "FIELD_ERROR") { response.formFields.forEach((item) => { if (item.id === "email") { // this means that something was wrong with the entered email. // probably that it's not a valid email (from a syntax point of view) this.emailError = item.error; } else if (item.id === "password") { this.passwordError = item.error; } }); return; } // login is successful, and we redirect the user to the home page. // Note that session cookies are added automatically and nothing needs to be // done here about them. window.location.assign("/"); } If the field in the response body is , and the is , it implies that the user entered a string that failed the email validation on the backend (most likely because it is not a valid email). So we store the error state and display the error message on the UI to the user. Here’s an example of how you can make the error message appear underneath the email field: status "FIELD_ERROR" id "email" Similarly, where we invoke the function from to handle the sign up flow. we can implement the signUp method emailPasswordSignUp supertokens-web-js For social login, we’re using Google and Github authentication providers. When the or functions are called, we call the method and pass the provider name in the parameters. We also provide a callback URL as parameter that the providers will redirect back to after the authentication process is completed. In our example, we use for Google and for GitHub. onGithubPressed onGooglePressed getAuthorisationURLWithQueryParamsAndSetState authorisationURL http://localhost:3000/auth/callback/google http://localhost:3000/auth/callback/github These URLs needs to be configured on the provider’s dashbaord as well. Here are the functions for Github and Google respectively: onGithubPressed: async function () { const authUrl = await ThirdPartyEmailPassword.getAuthorisationURLWithQueryParamsAndSetState({ providerId: "github", // This is where github should redirect the user back after login or error. // This URL goes on the github dashboard as well. authorisationURL: "http://localhost:3000/auth/callback/github", }); window.location.assign(authUrl); }, onGooglePressed: async function () { const authUrl = await ThirdPartyEmailPassword.getAuthorisationURLWithQueryParamsAndSetState({ providerId: "google", // This is where google should redirect the user back after login or error. // This URL goes on the google dashboard as well. authorisationURL: "http://localhost:3000/auth/callback/google", }); window.location.assign(authUrl); } After the user has finished authentication on the provider’s website, they are redirected to the route. Here we call the function from which consumes the authorisation code (that is sent back from the provider) to sign in the user. http://localhost:3000/auth/callback/ thirdPartySignInAndUp supertokens-web-js Here is the function that handles the above flow in the component inside file: AuthCallbackView /src/views/AuthCallbackView.vue mounted: async function () { try { const response = await ThirdPartyEmailPassword.thirdPartySignInAndUp(); if (response.status !== "OK") { // either the user did not complete the login process, or something else went wrong. return window.location.assign("/auth?error=signin"); } // sign in successful. // The session tokens are handled automatically via our SDK. window.location.assign("/"); } catch (_) { window.location.assign("/auth?error=signin"); } } Setup Routing to Show the Signup/Login forms Vue CLI already generates the initial routing for our app inside . /src/router.index.ts We’ll update this file so that the route loads the component and the route loads the component we created earlier: /auth AuthView /auth/callback/:provider AuthCallbackView import { createRouter, createWebHistory } from "vue-router"; import AuthView from "../views/AuthView.vue"; const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes: [ { path: "/auth", name: "auth", component: () => AuthView, }, { path: "/auth/callback/:provider", name: "authcallback", component: () => AuthCallbackView, } ], }); export default router; Backend Integration You can see the backend quick setup section , or even copy the code from . As a summary: in our docs on supertokens.com our example app You need to initialize the SDK and provide it the (similar to how you did on the frontend). supertokens-node recipeList Then you need to setup , and add the SuperTokens and to your app. The SuperTokens exposes all the auth related API routes (like sign in, sign up, sign out etc) to the frontend. CORS middleware errorHandler middleware Finally, you need to provide the (location) of the SuperTokens core. To get started quickly, you can provide it (this is a core that we host for demo purposes). connectionURI "https://try.supertokens.com" Once you’ve successfully setup your server, you can now try and sign up on the frontend. Session management After authentication, we’ll render a component on the page inside . First, we’ll create the HTML template at : HomeView /src/views/HomeView.vue /src/html/homeView.html SIGN OUT 🥳🎉 Login successful Your user ID is {{ `${userId}` }} CALL API ------------------------------------ View the code on GitHub Vue Demo app. Made with ❤️ using supertokens.com Then inside , we’ll check if the user is authenticated using the method exposed by the Session recipe from the SDK. /src/views/HomeView.vue doesSessionExist supertokens-web-js For authenticated users, we render a logout button with information about their session. When a user clicks this button, we call the method from which clears the user’s session. signOut supertokens-web-js For unauthenticated users, we can redirect them to the page. /auth import { defineComponent } from "vue"; import Session from "supertokens-web-js/recipe/session"; import ThirdPartyEmailPassword from "supertokens-web-js/recipe/thirdpartyemailpassword"; const apiPort = import.meta.env.VUE_APP_API_PORT || 3001; const apiDomain = import.meta.env.VUE_APP_API_URL || `http://localhost:${apiPort}`; export default defineComponent({ data() { return { // if session is false, we show a blank screen // else we render the UI session: false, userId: "", }; }, methods: { signOut: async function () { await ThirdPartyEmailPassword.signOut(); window.location.assign("/auth"); }, checkForSession: async function () { if (!(await Session.doesSessionExist())) { // since a session does not exist, we send the user to the login page. return window.location.assign("/auth"); } const userId = await Session.getUserId(); // this will render the UI this.session = true; this.userId = userId; }, callAPI: async function () { const response = await fetch(`${apiDomain}/sessionInfo`); if (response.status === 401) { // this means that the session has expired and the // user needs to relogin. window.location.assign("/auth"); return; } const json = await response.json(); window.alert("Session Information:\n" + JSON.stringify(json, null, 2)); }, }, mounted() { // this function checks if a session exists, and if not, // it will redirect to the login screen. this.checkForSession(); }, }); For the route, we’ll redirect the user to the Home page if a session already exists: /auth checkForSession: async function () { if (await Session.doesSessionExist()) { // since a session already exists, we redirect the user to the HomeView.vue component window.location.assign("/"); } }, Finally, to load the component on we’ll update the file: HomeView "/" /src/router/index.ts const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes: [ { path: "/", name: "home", component: () => HomeView, }, // ... ], }); export default router; If you now visit after authentication, you should see the following page: http://localhost:3000 Forgot Password Flow In the Sign In UI, we have a link to the forgot password page. On this page the user can enter their email and receive a password reset link in their inbox. When they visit that link, they can then enter their new password on that page to change their password. First, we’ll create the HTML template inside . that you can use. /src/html/forgotPassword.html Here is an example We’ll create a component inside file where we will render the above template: /src/views/ForgotPassword.vue In the HTML template, we conditionally render a form, based on a variable called , which is a state variable representing if a password reset token has been generated or not. This variable is set based on the token present in the query parameters of the page’s URL. In the case where the user has clicked on the forgot password button (in the sign in page), there is no token present in the query parameters of the page’s URL, hence the variable is set to . tokenPresent tokenPresent tokenPresent false Since is , we render the form where the user will enter their email to get the reset password link. When the user enters their email on this form and submits it, we call the method from and pass in their email. This function interacts with a backend API to send a password reset link on the user’s email, if that email exists in SuperTokens. tokenPresent false sendPasswordResetEmail supertokens-web-js The password reset link is like . This link has the same path as the forgot password page, however, since the URL has the query parameter, it should render the form where the user can enter their new password. http://localhost:3000/auth/reset-password?token=....&rid=thirdpartyemailpassword token When they enter their new password in the form, we call the function with the new password. This function will automatically read the token from the URL and call the SuperTokens backend API to change the user’s password. submitNewPassword In case the password reset token was consumed already or has expired, the function call will return a non status and then we can show a message on the UI to prompt the user to go back to the login screen. "OK" import ThirdPartyEmailPassword from "supertokens-web-js/recipe/thirdpartyemailpassword"; import { defineComponent } from "vue"; export default defineComponent({ data() { /** * If the URL has a token query param, it means that we should show the * "enter new password" screen, else we should ask the user for their email * to send the password reset link. */ const urlParams = new URLSearchParams(window.location.search); const token = urlParams.get("token"); return { // the email property is used for the enter email screen email: "", error: false, errorMessage: "Something Went Wrong", didSubmit: false, // if tokenPresent is true, it means that the user has clicked on the // reset password link. tokenPresent: token !== null, password: "", }; }, methods: { onSubmitClicked: async function () { if (this.tokenPresent) { // we try and change the user's password now by consuming the token try { const response = await ThirdPartyEmailPassword.submitNewPassword({ formFields: [ { id: "password", value: this.password, }, ], }); if (response.status === "FIELD_ERROR") { // this indicates that the password entered by the user // did not match the backend password validation logic. throw new Error(response.formFields[0].error); } else if (response.status === "RESET_PASSWORD_INVALID_TOKEN_ERROR") { // the password reset token was consumed already, or has expired. // in this case, the user should go back to the login screen or the // enter email screen throw new Error("Password reset token has expired, please go back to the sign in page"); } // password reset successful. window.location.assign("/auth"); } catch (e: any) { this.errorMessage = e.message; this.error = true; } } else { // the user has entered an email for whom the password reset link // will be sent. try { const response = await ThirdPartyEmailPassword.sendPasswordResetEmail({ formFields: [ { id: "email", value: this.email, }, ], }); if (response.status !== "OK") { // this means that the email validation logic failed. throw new Error(response.formFields[0].error); } // a password reset email was sent successfully. if (this.didSubmit !== true) { // we change the UI to show that the email has been sent this.didSubmit = true; } } catch (e: any) { this.errorMessage = e.message; this.error = true; } } }, }, }); If the function is successful, it means the user’s password has been successfully reset and we redirect the user back to the page so they can now login with their new password. submitNewPassword /auth To load the component on the route , we’ll make the following changes in the file: ForgotPassword /auth/reset-password /src/router/index.ts const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes: [ // ... { path: "/auth/reset-password", name: "resetPassword", component: () => ForgotPasswordView, }, ], }); Once you do that, if you now visit , you should see the following page: http://localhost:3000/auth/reset-password If you enter your email and press the “Email Me” button, you should receive a link to reset your password on the entered email: After clicking the link, you can enter your new password and hit the “Change Password” button to update your password: Supertokens Core Setup Whilst doing the backend setup, we are using as the for the core. This is a demo core instance hosted by the team of SuperTokens. You can use this for as long as you like, but when you are committed to using SuperTokens, you should switch to a or a of the core. "https://try.supertokens.com" connectionURI self hosted managed version Conclusion We used the SDK to add email password and social authentication along with the forgot password functionality to a Vue app. Useful links: supertokens-web-js Example Vue app Discord community (to ask questions) List of recipes / auth methods Written by the Folks at — hope you enjoyed! We are always available on our Discord server. Join us if you have any questions or need any help. SuperTokens Also published . here