# SuperTokens + React

A demo implementation of [SuperTokens](https://supertokens.com/) with [React](https://react.dev/). Based on [Vite](https://vite.dev/).

## General Info

This project aims to demonstrate how to integrate SuperTokens into a React application. Its primary purpose is to serve as an educational tool, but it can also be used as a starting point for your own project.

## Repo Structure

### Source

```
📦src
┣ 📂assets
┃ ┣ 📂fonts
┃ ┃ ┗ 📜MenloRegular.ttf
┃ ┗ 📂images
┃   ┣ 📜arrow-right-icon.svg
┃   ┣ 📜background.png
┃   ┣ 📜blogs-icon.svg
┃   ┣ 📜celebrate-icon.svg
┃   ┣ 📜guide-icon.svg
┃   ┣ 📜separator-line.svg
┃   ┗ 📜signout-icon.svg
┣ 📂Home --> "Dashboard" component, accessible only via the logged-in state of the app
┃ ┣ 📜CallAPIView.tsx
┃ ┣ 📜Home.css
┃ ┣ 📜SuccessView.tsx
┃ ┗ 📜index.tsx
┣ 📜App.css
┣ 📜App.tsx --> Root component of the app
┗ 📜main.tsx --> Entry point of the app
```

### Config

#### Vite

Given that the project is a standard Vite project, everything available in the [Vite configuration docs](https://vite.dev/config/) is available to use here (refer to the `vite.config.ts` file). The only customization we've done is changing the port to `3000`.

#### SuperTokens

The full configuration needed for SuperTokens (the frontend part) to work is in the `src/config.tsx` file. This file will differ based on the [auth recipe](https://supertokens.com/docs/guides) you choose.

If you choose to use this as a starting point for your own project, you can further customize the options and config in the `src/config.tsx` file. Refer to our [docs](https://supertokens.com/docs) (and make sure to choose the correct recipe) for more details.

## Application Flow

The application uses [React Router](https://reactrouter.com/) for routing and consists of four main parts:

1. **Entry Point (`main.tsx`)**

    - Initializes the React application using `createRoot`
    - Renders the main `App` component within React's `StrictMode`

2. **Root Component (`App.tsx`)**

    - Initializes SuperTokens with the provided configuration (generated by the CLI)
    - Sets up the routing structure using `react-router-dom`
    - Wraps the application with necessary providers:
        - `SuperTokensWrapper`: Manages auth state and session
        - `ComponentWrapper`: Provides auth UI customization for specific auth recipes. For example, if you choose to use the `ThirdPartyPasswordless` recipe, the `ComponentWrapper` will provide the UI customization for the passwordless login flow (showing a disclaimer about the SMS delivery in demo apps).
    - Defines three main routes:
        - `/`: Public landing page - accessible regardless of auth state
        - `/auth`: Renders SuperTokens' pre-built auth UI - accessible regardless of auth state
        - `/dashboard`: Protected route requiring authentication

3. **Home Component (`/` route, `/Home/index.tsx` component)**

    - Public landing page accessible to all users
    - Provides navigation to authentication and dashboard
    - Displays basic application information and links

4. **Dashboard Component (`/dashboard` route, `/Dashboard/index.tsx` component)**
    - Protected route only accessible to authenticated users
    - Protected by `SessionAuth` component
    - Displays user information and session details
    - Provides functionality to:
        - View user ID
        - Call test API endpoints
        - Access documentation
        - Sign out

When a user visits the application, they start at the home page (`/`). They can choose to authenticate through the `/auth` route, and once authenticated, they gain access to the protected dashboard. The session state is managed throughout the application using SuperTokens' session management.

## Customizations

If you want to customize the default auth UI, you have two options:

1. Refer to the [docs](https://supertokens.com/docs/thirdpartyemailpassword/advanced-customizations/react-component-override/usage) on how to customize the pre-built UI.
2. Roll your own UI by choosing "Custom UI" in the right sidebar in the [docs](https://supertokens.com/docs/thirdpartyemailpassword/quickstart/frontend-setup).

## Additional resources

-   Custom UI Example: https://github.com/supertokens/supertokens-web-js/tree/master/examples/react/with-thirdpartyemailpassword
-   Custom UI Blog post: https://supertokens.medium.com/adding-social-login-to-your-website-with-supertokens-custom-ui-only-5fa4d7ab6402
-   Awesome SuperTokens: https://github.com/kohasummons/awesome-supertokens

## Contributing

Please refer to the [CONTRIBUTING.md](https://github.com/supertokens/create-supertokens-app/blob/master/CONTRIBUTING.md) file in the root of the [`create-supertokens-app`](https://github.com/supertokens/create-supertokens-app) repo.

## Contact us

For any questions, or support requests, please email us at team@supertokens.io, or join our [Discord](https://supertokens.io/discord) server.

## Authors

Created with :heart: by the folks at SuperTokens.io.