supertokens-auth-react

supertokens-auth-react is the official React SDK for SuperTokens, an open-source authentication platform. It ships prebuilt, themeable UI for email/password, passwordless, and social/enterprise (thirdparty) login, plus session management, email verification, multi-factor authentication, multi-tenancy, and role-based access control — all wired into a single SuperTokens.init() call.

Each auth flow is implemented as an independently configurable “recipe,” and every recipe exposes component-override hooks and a useSessionContext()/useClaimValue() API so teams can start with the prebuilt screens and progressively swap in custom UI without changing the underlying session logic.

What You Get

• Prebuilt, styleable UI screens for email/password, passwordless, and social/enterprise (thirdparty) login and signup
• Session management via useSessionContext()/useClaimValue() hooks, with automatic token refresh handled by the underlying supertokens-web-js layer
• Multi-factor authentication (TOTP, recovery codes), multi-tenancy, user roles, WebAuthn/passkeys, and OAuth2 provider recipes, each independently configurable
• A component-override system for replacing individual pieces of the prebuilt UI without forking the library
• First-class Next.js support (middleware and SSR helpers under a dedicated nextjs subpackage)

Common Use Cases

• Adding a full login/signup flow to a new React or Next.js app without building auth screens from scratch
• Migrating off a third-party auth SaaS while keeping a similar prebuilt-UI developer experience
• Adding multi-factor authentication or passwordless login to an existing SuperTokens-backed app
• Building a multi-tenant SaaS product that needs per-tenant login configuration and role-based access

Under The Hood

Architecture — supertokens-auth-react organizes functionality into isolated “recipes” (lib/ts/recipe/emailpassword, session, thirdparty, passwordless, multifactorauth, multitenancy, oauth2provider, totp, userroles, webauthn), each implementing a shared RecipeModule/BaseRecipeModule interface (lib/ts/recipe/recipeModule) so recipes can be mixed and matched via a single top-level SuperTokens.init() call in superTokens.tsx, which normalizes app info, registers recipes into recipeList, and merges plugin-supplied component overrides into componentOverrides. A pluginRouteHandlers array and PluginRouteHandler type let plugins register their own routes, and the library composes with the lower-level supertokens-web-js package for cookie/window handling and post-init callbacks rather than reimplementing session/network primitives itself.

Tech Stack — Written almost entirely in TypeScript (56% of the codebase, with a 41% JavaScript build layer), compiled via Rollup (rollup.config.mjs) into a dual CJS/ESM build under lib/build, and distributed with hand-maintained type declarations (index.d.ts plus per-recipe index.d.ts). It depends on supertokens-web-js (peer dependency, ^0.16.0) for core session/network logic, and pulls in intl-tel-input for phone-number input, react-qr-code for TOTP-style QR flows, and @simplewebauthn/types for WebAuthn typings. React itself is a peer dependency (>=16.8.0) rather than bundled, keeping the SDK framework-version-agnostic, and a dedicated lib/ts/nextjs subpackage adds Next.js-specific middleware/SSR helpers.

Code Quality — The repo runs both fast unit tests (test/unit, Jest + ts-jest + jsdom, covering hooks like useSessionContext, claim-value calculations, and version-compatibility checks) and full end-to-end tests (test/end-to-end, Mocha + Puppeteer/Percy) against dozens of real example apps under examples/with-*. ESLint (with a custom eslint-plugin-supertokens-auth-react) and a pretty-quick/Prettier pre-commit pass keep style consistent, and ts-prune plus a size-limit budget (72kb) guard against dead exports and bundle bloat — though the top-level README itself is minimal and defers most technical detail to the hosted docs site.

API Design — Integration is a single SuperTokens.init({ appInfo, recipeList: [...] }) call, after which each recipe (e.g. EmailPassword.init(), Session.init()) is configured independently and its prebuilt UI is dropped in via <SuperTokensWrapper> — a low-boilerplate path to a fully working, styleable auth flow. Every recipe exposes a componentOverrides map for swapping individual UI pieces and a useSessionContext()/useClaimValue() hook pair for reading session state in application code, so teams can start with the prebuilt screens and progressively eject into custom UI without switching APIs.