# 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
┣ 📂Dashboard --> Protected route component, only accessible to authenticated users
┃ ┗ 📜index.tsx
┣ 📂Home --> Public landing page component, accessible regardless of auth state
┃ ┗ 📜index.tsx
┣ 📜App.css
┣ 📜App.tsx --> Root component of the app
┣ 📜config.tsx --> SuperTokens configuration
┣ 📜vite-env.d.ts
┗ 📜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
   - Serves as the entry point for new users

4. **Dashboard Component (`/dashboard` route, `/Dashboard/index.tsx` component)**
   - Protected route only accessible to authenticated users
   - Protected by `SessionAuth` component
   - Displays user information and provides authenticated functionality

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.