React Installation (5 mins)

For framework specific implementation (like Next.js), please skip this section and go directly to the section with the name of your framework.

This library provides a set of modules that you can add to your React application to implement authentication.

An example implementation can be found here.

1️⃣ npm install

npm i -s supertokens-auth-react

2️⃣ Call the init function

Then in your App.js file, import SuperTokens and call the init function. Please make sure to replace all the appInfo configurations values with yours.

ReactJS

import React from 'react';

import SuperTokens from "supertokens-auth-react";
import ThirdPartyEmailPassword, {Github, Google, Facebook} from "supertokens-auth-react/recipe/thirdpartyemailpassword";
import Session from "supertokens-auth-react/recipe/session";

SuperTokens.init({
    appInfo: {
        appName: "YOUR APP NAME", // Example: "SuperTokens",
        apiDomain: "YOUR API DOMAIN", // Example: "https://api.supertokens.io",
        websiteDomain: "YOUR WEBSITE DOMAIN" // Example: "https://supertokens.io"
    },
    recipeList: [
        ThirdpartyEmailPassword.init({
            signInAndUpFeature: {
                providers: [
                    Github.init()
                    Google.init()
                    Facebook.init()
                ]
            }
        }),
        Session.init()
    ]
});


/* Your App */
class App extends React.component {
    render() {
       return (...)
    }
}

If you only want to use email and password, you do not have to pass any providers in the config. If you only want to use ThirdParty providers, you can set `disableEmailPassword` in the config to `true`. In that case you must pass at least 1 provider.

3️⃣ Setup routes

Enabling routing will allow SuperTokens to insert components in specific pages, such as for Sign-up / Sign-in page.

With react-router-dom

With custom routing

Call the getSuperTokensRoutesForReactRouterDom method from within any react-router-dom Switch component.

import React from 'react';
import {
  BrowserRouter as Router,
  Switch,
  Route,
  Link
} from "react-router-dom";

import SuperTokens, { getSuperTokensRoutesForReactRouterDom } from "supertokens-auth-react"; 
import ThirdPartyEmailPassword from "supertokens-auth-react/recipe/thirdpartyemailpassword";
import Session from "supertokens-auth-react/recipe/session";

SuperTokens.init({
    // Previously added configs
});


class App extends React.Components {
    render() {
        return (
            <Router>
                <YourNavBar/>
                <Switch>
                    {getSuperTokensRoutesForReactRouterDom()}
                    {...}
                </Switch>
                <YourFooter />
            </Router>
        );
    }
}

If you use a custom routing system in your React application, you can add SuperTokens routes via:

import React from 'react';
import SuperTokens from "supertokens-auth-react";

class App extends React.Components {
    render() {
        if (SuperTokens.canHandleRoute()) {
            return SuperTokens.getRoutingComponent()
        }
        
        return (
            (...)
        );
    }

}

4️⃣ Protect your application with the Authentication wrapper

Use ThirdPartyEmailPasswordAuth component in order to protect authenticated parts of your application:

With react-router-dom

With custom routing

import React from 'react';
import {
  BrowserRouter as Router,
  Switch,
  Route,
  Link
} from "react-router-dom";

import SuperTokens, { getSuperTokensRoutesForReactRouterDom }  from "supertokens-auth-react"; 
import ThirdPartyEmailPassword, {ThirdPartyEmailPasswordAuth} from "supertokens-auth-react/recipe/thirdpartyemailpassword";
import Session from "supertokens-auth-react/recipe/session";

SuperTokens.init({
    // Previously added configs
});


class App extends React.Components {
    render() {
        return (
            <Router>
                <YourNavBar/>
                <Switch>
                    {getSuperTokensRoutesForReactRouterDom()}

                    <Route path="/dashboard">
                        <ThirdPartyEmailPasswordAuth>
                            // Components that require to be protected by authentication
                        </ThirdPartyEmailPasswordAuth>
                    </Route>

                    // Other components without authentication
                    {...}
                </Switch>
                <YourFooter />
            </Router>
        );
    }
}

import React from 'react';
import SuperTokens from "supertokens-auth-react";
import {ThirdPartyEmailPasswordAuth} from "supertokens-auth-react/recipe/thirdpartyemailpassword";

class App extends React.Components {
    render() {
        if (SuperTokens.canHandleRoute()) {
            return SuperTokens.getRoutingComponent()
        } 
        
        return (
            <ThirdPartyEmailPasswordAuth>
                // Components that require to be protected by authentication
            </ThirdPartyEmailPasswordAuth>
        );
    }

}

5️⃣ Add axios session interceptor

This step is only applicable if you are using axios

Add the interceptor for each axios import call

ReactJS

import axios from "axios";
import Session from "supertokens-auth-react/recipe/session";
Session.addAxiosInterceptors(axios);

async function callAPI() {
    // use axios as you normally do
    let response = await axios.get(...);
}

An example of this can be found in our demo app.

Frontend setup completed 🎉🥳

If you navigate to /auth in your application, you should see the SuperTokens Sign-up / Sign-in widgets.

At this stage, you've successfully integrated your website with SuperTokens. The next section will guide you through setting up your backend.