{ "componentChunkName": "component---src-pages-blog-markdown-remark-fields-slug-js", "path": "/blog/how-to-use-supertokens-custom-ui-with-vuejs", "result": {"data":{"markdownRemark":{"html":"

In this guide, you will learn how to add an Email + Password Authentication to a Vue.js application using SuperTokens. We’ll build a simple web application where users can sign up with their email and password, relying on SuperTokens for authentication.

\n

Our demo app will use the Email-Password recipe for authentication and a custom authentication user interface (UI) tailored for our users.

\n

\"Vue

\n

Prerequisites

\n

Before you begin, you need:

\n\n

What is SuperTokens

\n

SuperTokens is an open source project that lets you add authentication to your app quickly. It offers various authentication methods (called recipes).

\n

Alongside a prebuilt UI, it also offers a vanilla JS SDK called supertokens-web-js that you can use to build your own UI. In this tutorial we’ll learn how to use the supertokens-web-js to add authentication to a VueJS application. We’ll focus on the email password and social login flow, but you can choose another auth method as well.

\n

Architecture

\n

SuperTokens is built out of three components:

\n\n

We’ll build our own login, signup forms. Then we’ll use the supertokens-web-js 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 our backend layer.

\n

For the backend we’ll use the supertokens-node SDK. The APIs exposed by this SDK will further talk to the SuperTokens Core to read/write information to the database.

\n

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 supertokens.com).

\n

Project Setup

\n

To reduce the scope of this guide, you will be starting with a repository that already has a few things set up for you:

\n\n

To get started, clone the starter branch from the repository with the following command:

\n\n \n \n \n \n
git clone --branch starter https://github.com/kohasummons/supertokens-vue\ncd supertokens-vue
\n

Your project directory structure will look like the tree below with that setup. The ... indicates omitted files to keep the tree concise.

\n\n \n \n \n \n
├── backend\n│   ├── ...\n│   ├── app.js\n└── frontend\n    ├── ...\n    ├── src\n    │   ├── App.vue\n    │   ├── components\n    │   │   ├── HelloWorld.vue\n    │   │   ├── TheButton.vue\n    │   ├── main.ts\n    │   ├── router\n    │   │   └── index.ts\n    │   └── views\n    │       ├── AboutView.vue\n    │       ├── AuthView.vue\n    │       ├── HomeView.vue\n    │       └── UserView.vue
\n
    \n
  • The backend folder holds the Express.js code for the APIs
    • \n
  • The Frontend folder contains code for the Vue.js application
    • \n
\n

Frontend

\n

Change into the Frontend directory and install the superTokens-web-js dependency

\n\n \n \n \n \n
cd frontend/\nnpm i -s supertokens-web-js
\n

Initializing SuperTokens

\n

Open main.ts and initialize SuperTokens

\n", // I use here\n        apiBasePath: "/auth",\n        appName: "replace with your app name",\n    },\n\n    recipeList: [\n        Session.init(),\n        EmailPassword.init(),\n    ],\n});`, `68034451696198110000`)\"\n >\n \n \n \n \n
import SuperTokens from 'supertokens-web-js';\nimport Session from 'supertokens-web-js/recipe/session';\nimport EmailPassword from 'supertokens-web-js/recipe/emailpassword'\n\n// Several lines of code are omitted here.\n\nSuperTokens.init({\n    appInfo: {\n        apiDomain: \"<YOUR_API_DOMAIN>\", // I use <http://localhost:5175> here\n        apiBasePath: \"/auth\",\n        appName: \"replace with your app name\",\n    },\n\n    recipeList: [\n        Session.init(),\n        EmailPassword.init(),\n    ],\n});
\n

In this code snippet, we set up session management network interceptors across the entire application. Our front end will now automatically save and attach session tokens to each request made to our API and auto-refresh sessions.

\n

This setup also specifies the type of authentication we want to use—in this case, the EmailPassword recipe. Additional recipes can be added to the recipeList array depending on the project’s needs.

\n

The appInfo object allows us to customize our SuperTokens instance for the application, and it needs to be specified both on the frontend and backend. Some of the options it provides include:

\n
    \n
  1. appName: The name of your application
    2. \n
  2. apiDomain: The API Domain URL of your backend
    3. \n
  3. apiBasePath: The base path for the API
    4. \n
\n

Add SignIn and SignUp to your application

\n

Great! Let’s add the ability for our users to sign up via our custom UI. Head to AuthView.vue and update with the following code:

\n\nimport { signIn, signUp } from "supertokens-web-js/recipe/emailpassword";\n// Several lines of code are omitted here.\n\nconst onSignUp = async () => {\n    try {\n        let response = await signUp({\n            formFields: [{\n                id: "email",\n                value: email.value\n            }, {\n                id: "password",\n                value: password.value\n            }]\n        })\n\n       // handle potential errors\n        if (response.status === "FIELD_ERROR") {\n            // one of the input formFields failed validaiton\n            response.formFields.forEach(formField => {\n                if (formField.id === "email") {\n                    // Email validation failed\n                    window.alert(formField.error)\n                } else if (formField.id === "password") {\n                    // Password validation failed.\n                    // Maybe it didn't match the password strength\n                    window.alert(formField.error)\n                }\n            })\n        } else if (response.status === "SIGN_UP_NOT_ALLOWED") {\n            // the reason string is a user friendly message\n            // about what went wrong.\n            window.alert(response.reason)\n        } else {\n            // sign up successful.\n            // navigate to the '/user' page\n            router.push({ name: 'user' })\n        }\n    } catch (err: any) {\n        if (err.isSuperTokensGeneralError === true) {\n            // this may be a custom error message sent from the API by you.\n            window.alert(err.message);\n        } else {\n            window.alert("Oops! Something went wrong.");\n        }\n    }\n}\n`, `76087063527781580000`)\"\n >\n \n \n \n \n
<script setup lang=\"ts\">\nimport { signIn, signUp } from \"supertokens-web-js/recipe/emailpassword\";\n// Several lines of code are omitted here.\n\nconst onSignUp = async () => {\n    try {\n        let response = await signUp({\n            formFields: [{\n                id: \"email\",\n                value: email.value\n            }, {\n                id: \"password\",\n                value: password.value\n            }]\n        })\n\n       // handle potential errors\n        if (response.status === \"FIELD_ERROR\") {\n            // one of the input formFields failed validaiton\n            response.formFields.forEach(formField => {\n                if (formField.id === \"email\") {\n                    // Email validation failed\n                    window.alert(formField.error)\n                } else if (formField.id === \"password\") {\n                    // Password validation failed.\n                    // Maybe it didn't match the password strength\n                    window.alert(formField.error)\n                }\n            })\n        } else if (response.status === \"SIGN_UP_NOT_ALLOWED\") {\n            // the reason string is a user friendly message\n            // about what went wrong.\n            window.alert(response.reason)\n        } else {\n            // sign up successful.\n            // navigate to the '/user' page\n            router.push({ name: 'user' })\n        }\n    } catch (err: any) {\n        if (err.isSuperTokensGeneralError === true) {\n            // this may be a custom error message sent from the API by you.\n            window.alert(err.message);\n        } else {\n            window.alert(\"Oops! Something went wrong.\");\n        }\n    }\n}\n</script>
\n

The onSignUp function calls the signIn method from supertokens-web-js SDK which receives the email and password. If authentication is successful, we redirect the user to the \"/user\" route.

\n

Next, let’s handle the SignIn action. Update the AuthView.vue with the following code:

\n\n// Several lines of code are omitted here.\n\nconst onSignIn = async () => {\n    if (!email.value || !password.value) return\n\n    try {\n        let response = await signIn({\n            formFields: [{\n                id: "email",\n                value: email.value\n            }, {\n                id: "password",\n                value: password.value\n            }]\n        })\n\n        if (response.status === "FIELD_ERROR") {\n            response.formFields.forEach(formField => {\n                if (formField.id === "email") {\n                    // Email validation failed\n                    // (for example, incorrect email syntax).\n                    window.alert(formField.error)\n                }\n            })\n        } else if (response.status === "WRONG_CREDENTIALS_ERROR") {\n            window.alert("Email password combination is incorrect.")\n        } else if (response.status === "SIGN_IN_NOT_ALLOWED") {\n            //The reason string is a user-friendly message\n            // about what went wrong.\n            window.alert(response.reason)\n        } else {\n            //sign-in successful.\n            // navigate to the "/user" page\n            router.push({ name: 'user' })\n        }\n    } catch (err: any) {\n        if (err.isSuperTokensGeneralError === true) {\n            // this may be a custom error message\n            // sent from your API.\n            window.alert(err.message);\n        } else {\n            window.alert("Oops! Something went wrong.");\n        }\n    }\n}\n`, `22599438821196550000`)\"\n >\n \n \n \n \n
<script setup lang=\"ts\">\n// Several lines of code are omitted here.\n\nconst onSignIn = async () => {\n    if (!email.value || !password.value) return\n\n    try {\n        let response = await signIn({\n            formFields: [{\n                id: \"email\",\n                value: email.value\n            }, {\n                id: \"password\",\n                value: password.value\n            }]\n        })\n\n        if (response.status === \"FIELD_ERROR\") {\n            response.formFields.forEach(formField => {\n                if (formField.id === \"email\") {\n                    // Email validation failed\n                    // (for example, incorrect email syntax).\n                    window.alert(formField.error)\n                }\n            })\n        } else if (response.status === \"WRONG_CREDENTIALS_ERROR\") {\n            window.alert(\"Email password combination is incorrect.\")\n        } else if (response.status === \"SIGN_IN_NOT_ALLOWED\") {\n            //The reason string is a user-friendly message\n            // about what went wrong.\n            window.alert(response.reason)\n        } else {\n            //sign-in successful.\n            // navigate to the \"/user\" page\n            router.push({ name: 'user' })\n        }\n    } catch (err: any) {\n        if (err.isSuperTokensGeneralError === true) {\n            // this may be a custom error message\n            // sent from your API.\n            window.alert(err.message);\n        } else {\n            window.alert(\"Oops! Something went wrong.\");\n        }\n    }\n}\n</script>
\n

The SignIn function works similarly to the SignUp function we implemented earlier. We pass the email and password to the SignIn function, check for and handle any errors, and then automatically navigate the user if the action is successful.

\n

Add SignOut to your application

\n

Users who sign in to your application will also need a way to sign out. Let’s add a SignOut functionality to the user page.

\n

Open Userview.vue and update with the following code:

\n\n \n \n \n \n
//Several lines of code are omitted here\nimport Session from \"supertokens-web-js/recipe/session\";\n\nasync function onSignOut() {\n    await Session.signOut();\n    router.push({ name: 'auth' });\n}
\n

Backend

\n

While your front end is fully integrated with SuperTokens, it isn’t doing anything yet. That’s because the front end will never directly talk to the SuperTokens core. Any request from the front end will be sent to the APIs exposed on your backend via the supertokens-node SDK, which will then talk to the SuperTokens core. Let’s get our backend up and running.

\n

For a quick backend setup, check out the backend quick setup section in SuperTokens docs.

\n

Change into the Backend directory and install supertokens-node dependency

\n\n \n \n \n \n
cd backend\nnpm i -s supertokens-node
\n

Open app.js and update with the following code

\n\\`,\n        apiKey: \\`\\`,\n    },\n\n    appInfo: {\n        // learn more: \n        appName: "replace with your app name",\n        apiDomain: "", // I use here\n        websiteDomain: "",// I use here\n        apiBasePath: "/auth",\n        websiteBasePath: "/auth",\n    },\n\n    recipeList: [\n        EmailPassword.init(), // initializes signin / sign up features\n        Session.init(), // initializes session features\n    ]\n});`, `468252811946756600`)\"\n >\n \n \n \n \n
import supertokens from \"supertokens-node\";\nimport Session from \"supertokens-node/recipe/session/index.js\";\nimport EmailPassword from \"supertokens-node/recipe/emailpassword/index.js\";\nimport { verifySession } from \"supertokens-node/recipe/session/framework/express/index.js\";\nimport { middleware, errorHandler } from 'supertokens-node/framework/express/index.js';\n\nsupertokens.init({\n    framework: \"express\",\n    supertokens: {\n        // These are the connection details of\n        // the app you created on supertokens.com\n        connectionURI: `<replace with your URI>`,\n        apiKey: `<replace with your apiKey>`,\n    },\n\n    appInfo: {\n        // learn more: <https://supertokens.com/docs/session/appinfo>\n        appName: \"replace with your app name\",\n        apiDomain: \"<YOUR_API_DOMAIN>\", // I use <http://localhost:5175> here\n        websiteDomain: \"<YOUR_WEBSITE_DOMAIN>\",// I use <http://localhost:5173> here\n        apiBasePath: \"/auth\",\n        websiteBasePath: \"/auth\",\n    },\n\n    recipeList: [\n        EmailPassword.init(), // initializes signin / sign up features\n        Session.init(), // initializes session features\n    ]\n});
\n

This will initialize the supertokens-node SDK and allow us to customize our authentication flow.\nOnce again, the recipeList array configures the type of authentication we prefer, similar to how you did on the front end. The appInfo object also behaves like it was on the front end.

\n

Next, let’s setup CORS and the SuperTokens middleware and errorHandler:

\n",\n    allowedHeaders: ["content-type", ...supertokens.getAllCORSHeaders()],\n    credentials: true\n}))\n\n// Add the middleware BEFORE all your routes.\napp.use(middleware());\n\n// you can add any other route here.\n\n\napp.use(errorHandler());`, `58301201847426660000`)\"\n >\n \n \n \n \n
// several lines have been omitted\n\n// Add `cors` middleware BEFORE the SuperTokens middleware\napp.use(cors({\n    origin: \"<YOUR_WEBSITE_DOMAIN>\",\n    allowedHeaders: [\"content-type\", ...supertokens.getAllCORSHeaders()],\n    credentials: true\n}))\n\n// Add the middleware BEFORE all your routes.\napp.use(middleware());\n\n// you can add any other route here.\n\n\napp.use(errorHandler());
\n

This middleware exposes all the auth-related API routes (like sign-in and sign-up) to the front end…

\n
    \n
  • POST /auth/signup: For signing up a user with email & password
    • \n
  • POST /auth/signin: For signing in a user with email & password
    • \n
\n

Set up your SuperTokens Core Instance

\n

There are two ways to set up your core instance:

\n
    \n
  1. \n

    Self-Hosting the Core Instance:\nSelf-hosting allows you to use all the open-source features of SuperTokens for free, regardless of “scale”. Everything is managed within your infrastructure, giving you full control over the deployment.

    \n
    2. \n
  2. \n

    Using the SuperTokens Managed Service:\nWith this option, SuperTokens takes care of scalability, reliability, and updates on your behalf, significantly reducing your DevOps workload. It offers the same features as the self-hosted version but with the added convenience of on-demand management and infrastructure support.

    \n
    3. \n
\n

For the scope of this tutorial, we’ll spin a SuperTokens managed service instance.

\n

Create a user account on Supertokens\n\n \n \n \n \n

\n

After the deployment is complete, the dashboard will look similar to this\n\n \n \n \n \n

\n

Testing it out

\n

Now, we can test everything out.

\n

With both the frontend and backend servers running, open your application URL in the browser. Navigate to the Auth page and sign up or sign in.

\n

You’ll be redirected to the User page if the sign-in or sign-up is successful.

\n

\"Testing\"

\n

The User page in our demo displays some metadata about the user. That is a little task for you to implement. Look through the docs and give it a shot. Useful Resource: Getting User Info

\n

Protecting your Frontend Routes

\n

You can keep unauthenticated users away from certain page routes using navigation guards.

\n

To protect the User Page route, navigate to the router directory and update index.ts with the following code:

\n {\n  if (to.name === 'user' && !(await Session.doesSessionExist())) {\n\t  next({ name: 'auth' })\n  }\n    else {\n\t    next();\n    }\n})`, `70322030232477270000`)\"\n >\n \n \n \n \n
import Session from 'supertokens-web-js/recipe/session';\n\n// several omitted lines of code\n\nrouter.beforeEach(async (to, from, next) => {\n  if (to.name === 'user' && !(await Session.doesSessionExist())) {\n\t  next({ name: 'auth' })\n  }\n    else {\n\t    next();\n    }\n})
\n

The router.beforeEach function runs before every route is resolved. We’ve added logic to check if a user session exists. If it does, it navigates to the user page; otherwise, it redirects to the auth page, prompting users to sign in.

\n

Conclusion

\n

With this tutorial, you’ve successfully implemented Email + Password authentication using supertokens-web-js SDK in a Vue.js application and a Custom UI.

\n

You’ve learned how to set up SuperTokens on both the frontend and backend, create a SuperTokens managed service, and protect your frontend routes using navigation guards in combination with SuperTokens.

\n

Useful links:

\n","frontmatter":{"date":"October 07, 2024","title":"How to use SuperTokens in a VueJS app with your own UI","cover":"vue-custom-ui.png","author":"Joshua Omobola","description":"Learn how to integrate supertokens-web-js SDK into your VueJS application."},"fields":{"slug":"/how-to-use-supertokens-custom-ui-with-vuejs/"}},"site":{"siteMetadata":{"title":"SuperTokens Blog"}}},"pageContext":{"id":"16a9de13-d379-5466-ba96-da941fe25048","fields__slug":"/how-to-use-supertokens-custom-ui-with-vuejs/","__params":{"fields__slug":"how-to-use-supertokens-custom-ui-with-vuejs"}}}, "staticQueryHashes": []}