auth0-spa-js

@auth0/auth0-spa-js is Auth0’s official client library for browser-based single-page applications. It implements the OAuth2 Authorization Code Grant with PKCE end to end — redirect or popup login, silent session renewal via a hidden iframe or dedicated web worker, and automatic access-token caching keyed by audience and scope. A single Auth0Client instance is the entry point for the whole session lifecycle: loginWithRedirect, loginWithPopup, handleRedirectCallback, getTokenSilently, and logout.

Beyond core login, the SDK bundles first-class clients for adjacent Auth0 APIs: mfa for enrolling and verifying OTP/SMS/voice/push/email factors, passkey for WebAuthn signup and login in a couple of method calls, and myaccount for letting a signed-in user manage their own authentication methods. It also supports DPoP sender-constrained tokens, refresh-token rotation, and a pluggable cache/storage layer (in-memory, localStorage, or a custom ICache implementation) so teams can tune persistence and security trade-offs for their own SPA.

What You Get

• An Auth0Client class covering the full session lifecycle: redirect/popup login, silent token renewal, logout, and token retrieval
• Bundled mfa, passkey, and myaccount API clients for factor enrollment, WebAuthn flows, and self-service account management
• Pluggable token cache and storage layers (InMemoryCache, LocalStorageCache, cookie-based session storage, or a custom ICache)
• Built-in DPoP support for sender-constrained tokens, including an Online Refresh Token mode
• Full TypeScript typings and generated API reference docs for every exported class and type
• A cross-tab lock manager so concurrent tabs don’t race on token refresh

Common Use Cases

• Adding Auth0-hosted login to a React/Vue/Angular/vanilla-JS single-page app with silent session restore on reload
• Calling a protected API from the browser with automatically cached and refreshed access tokens scoped per audience
• Enforcing step-up MFA before a sensitive action inside an already-authenticated session
• Registering and signing users in with passkeys via WebAuthn without hand-rolling the browser credential API

Under The Hood

Architecture The SDK centers on Auth0Client (src/Auth0Client.ts), a single class that orchestrates several purpose-built collaborators rather than doing everything itself: a TransactionManager tracks in-flight PKCE/login state, a CacheManager sits behind a pluggable ICache interface (InMemoryCache/LocalStorageCache) for token storage, an ILockManager (backed by browser-tabs-lock) prevents concurrent tabs from racing on silent refresh, and a dedicated web worker (src/worker/token.worker.ts) performs token exchange off the main thread when configured. Storage of session cookies is likewise abstracted (ClientStorage/CookieStorage/CookieStorageWithLegacySameSite) to smooth over browser same-site differences. Newer surface area — mfa, passkey, and myaccount — is implemented as separate API-client modules under their own directories and composed onto Auth0Client as public readonly properties, keeping each concern’s types and error classes isolated rather than folded into the core class.

Tech Stack Written in TypeScript and built with Rollup into CJS, ESM, and a CDN UMD bundle, with rollup-plugin-typescript2 and Babel presets for the TypeScript/env transform. Runtime dependencies are minimal and deliberate: @auth0/auth0-auth-js for shared OAuth/OIDC client logic, dpop for proof-of-possession tokens, browser-tabs-lock for the cross-tab lock, and es-cookie for cookie access. es-check validates the production bundle targets ES2017, and TypeDoc generates the published docs/ API reference from source comments.

Code Quality A large Jest test suite (50 .test.ts files under __tests__/, mirroring the src/ module layout for cache, mfa, passkey, dpop, and worker code) runs under ts-jest with coverage collection, jest-localstorage-mock, and fake-indexeddb, plus a separate Cypress suite for browser integration tests and a cross-browser CI workflow. Errors are modeled as typed classes per subsystem (AuthenticationError, MfaEnrollmentError, PasskeyChallengeError, etc.) rather than generic thrown strings. CI runs ESLint, CodeQL, Snyk, and an SCA scan alongside the test suite, and source files carry extensive JSDoc comments consumed by TypeDoc.

API Design The public surface favors single-call ergonomics for complex flows — passkey.signup()/passkey.login() hide the full WebAuthn credential ceremony, and createAuth0Client() returns an already-session-checked client in one awaited call. Overloaded type signatures enforce configuration invariants at compile time (e.g. refreshTokenMode: 'online' requiring useDpop: true), backed by a matching runtime check in the constructor for callers using plain JS or dynamic config. Naming is consistent across the mfa/passkey/myaccount clients, and every exported type is documented in the generated reference.