One of the most challenging parts of setting up a new application is the backend logins and account management. If not correctly implemented and designed, handling user registrations and maintaining user accounts can be downright complicated and bug-prone. In this tutorial, we’ll walk you through setting up a user authentication workflow using SuperTokens on a ReactJS application with ExpressJS as the backend. This will include an email-password authentication with popular social providers like Google, GitHub, and Apple.
\nSuperTokens is an open-source alternative to proprietary login providers like Auth0 or AWS Cognito. You can use SuperTokens for just logging in, or just session management, or both. Here’s an illustration of the architecture of SuperTokens managed service:
\nFirst up, let’s create our working environment; for this, we will be using the most popular create-react-app command.
\nTo get this command running make sure to have Node >= 14.0.0 and npm >= 5.6 installed on your machine.\n\n
npx create-react-app my-demo-appThis will create a my-demo-app folder with all the directories and files required to build our react app. Navigate to the newly created project in the terminal and run the application using yarn start command. This will open the browser on http://localhost:3000 with a default react page.\nNow, install the SuperTokens React SDK by navigating to the my-demo-app directory and running the following command:
cd my-demo-appyarn add supertokens-auth-react\nThis SDK will provide the login UI as react components, and will also help with session management. \n\n
Next, let’s set up the SuperTokens SDK by using the init function. Navigate to App.js under the src directory and paste the following snippet:
//my-demo-app/src/App.js\n\nimport logo from \"./logo.svg\";\nimport \"./App.css\";\n\nimport React from \"react\";\n\n// Imports from SuperTokens\n\nimport SuperTokens from \"supertokens-auth-react\";\nimport ThirdPartyEmailPassword, {\n Github,\n Google,\n Apple,\n} from \"supertokens-auth-react/recipe/thirdpartyemailpassword\";\n\nimport Session from \"supertokens-auth-react/recipe/session\";\n\n// SuperTokens INIT\n\nSuperTokens.init({\n appInfo: {\n appName: \"My Demo App\",\n apiDomain: \"http://localhost:3001\",\n websiteDomain: \"http://localhost:3000\",\n },\n recipeList: [\n ThirdPartyEmailPassword.init({\n signInAndUpFeature: {\n providers: [\n Github.init(),\n Google.init(),\n Apple.init(),\n ],\n },\n }),\n Session.init(),\n ],\n});\n\n\nfunction App() {\n return (\n\t// Your App Code\n );\n}\n\nexport default App;The SuperToken init function requires two objects:
appInfo: The object that holds application details and domain configuration. At a minimum, it consists of three variables.
appName: The name of the application we are building, in our case, let’s set it to “My Demo App”.apiDomain: API domain refers to the domain address of the API server, which we will be configuring in the further sections on ExpressJS. For now, let’s set it to http://localhost:3001.websiteDomain: Domain address of the frontend - application, which is essentially our react server, so in this case, it will be http://localhost:3000.recipeList: This object lets us configure the login and session management modules.
In the recipeList object, as we can see, we had initialised three social providers inside the provider’s list, which are GitHub, Google and Apple. You can also add a custom provider which SuperTokens hasn’t implemented (see this page)
\nSession.init() provides the session management feature. This recipe manages the session tokens issued by the backend and also provides the logout functionality.
This section will guide you on setting up the frontend UI provided by SuperTokens. Since there are several pages (sign in, reset the password, email verification..), SuperTokens needs to manage routing within your frontend app. For that, we have provided integration with react-router-dom:
\nyarn add react-router-dom\nNote: In this tutorial, we will be using react-router-dom v>=6, in case if you’re using a different version, the configuration needs to be updated. Read more information here. \n\n
Integrating React Router DOM into our app requires a small boilerplate code to set up the history and navigation. For this, we provide a route configuration object for each of our routes. To do this, open the App.js file, and update the code to the following:
//my-demo-app/src/App.js\n\nimport ThirdPartyEmailPassword, {\n Github,\n Google,\n Apple,\n} from \"supertokens-auth-react/recipe/thirdpartyemailpassword\";\nimport Session from \"supertokens-auth-react/recipe/session\";\n\n// import react-router-dom components\n\nimport { Routes, BrowserRouter as Router, Route } from \"react-router-dom\";\n\n// import SuperTokens Auth routes\n\nimport SuperTokens, {\n getSuperTokensRoutesForReactRouterDom,\n} from \"supertokens-auth-react\";\n\nimport Home from \"./Home\";\n\n\nSuperTokens.init({\n\t...\n});\n\n\nfunction App() {\n return (\n <div className=\"App\">\n <Router>\n <Routes>\n {/*This renders the login UI on the /auth route*/}\n {getSuperTokensRoutesForReactRouterDom(require(\"react-router-dom\"))}\n\n <Route path=\"/\" element={<Home />} />\n\n </Routes>\n </Router>\n </div>\n );\n}Here, we added the Router configuration with a special function getSuperTokensRoutesForReactRouterDom, which configures all the auth routes provided by SuperTokens. By default, this function will catch all navigation to /auth/* and display relevant authentication UI based on the path.
Note that, here we are using a simple Home component for the /route path, hence, let’s create a new Home component inside the src folder:
touch src/Home/index.js\nexport default function Home() {\n return (\n <>\n <h1>Hello from SuperTokens</h1>\n </>\n );\n}To see the auth UI in action, run the server and navigate to http://localhost:3000/auth.
yarn start