@ttoss/react-auth-core

Provider-agnostic authentication components and abstractions for React applications with screen-based flow management.

Installation

pnpm add @ttoss/react-auth-core

Quickstart

import {
  AuthProvider,
  Auth,
  useAuth,
  useAuthScreen,
} from '@ttoss/react-auth-core';

// 1. Wrap your app with AuthProvider
function App() {
  return (
    <AuthProvider signOut={async () => await myAuthService.signOut()}>
      <AuthenticatedApp />
    </AuthProvider>
  );
}

// 2. Create auth flow with handlers
function LoginPage() {
  const { screen, setScreen } = useAuthScreen();

  return (
    <Auth
      screen={screen}
      setScreen={setScreen}
      onSignIn={async ({ email, password }) => {
        await myAuthService.signIn(email, password);
      }}
      onSignUp={async ({ email, password }) => {
        await myAuthService.signUp(email, password);
        setScreen({ value: 'confirmSignUpCheckEmail' });
      }}
    />
  );
}

// 3. Use authentication state
function AuthenticatedApp() {
  const { isAuthenticated, user, signOut } = useAuth();

  if (!isAuthenticated) {
    return <LoginPage />;
  }

  return (
    <div>
      <p>Welcome, {user?.email}</p>
      <button onClick={signOut}>Sign Out</button>
    </div>
  );
}

Features

• Screen-based flows: Manages authentication through distinct screens (signIn, signUp, forgotPassword, etc.)
• Provider agnostic: Works with any authentication service - you provide the handlers
• Type-safe: Full TypeScript support with comprehensive type definitions
• UI components: Pre-built forms and layouts for common authentication flows
• Error handling: Built-in error boundaries and proper error management

Core Concepts

Authentication Screens

Provider Pattern

The package uses React Context to manage authentication state across your application. You provide the authentication logic, and the components handle the UI and flow management.

API Reference

AuthProvider

Wraps your application to provide authentication context.

<AuthProvider
  getAuthData={() => Promise<AuthData>} // Optional: fetch initial auth state
  signOut={() => Promise<void>} // Required: sign out handler
>
  {children}
</AuthProvider>

useAuth Hook

Access authentication state and actions.

const {
  isAuthenticated, // boolean
  user, // AuthUser | null
  tokens, // AuthTokens | null
  signOut, // () => Promise<void>
  setAuthData, // Update auth state manually
} = useAuth();

Auth Component

Main authentication flow component.

With External Screen State Management

<Auth
  screen={screen} // Current screen state
  setScreen={setScreen} // Screen navigation function
  onSignIn={handleSignIn} // Sign in handler
  onSignUp={handleSignUp} // Sign up handler (optional)
  onForgotPassword={handleForgotPassword} // Forgot password handler (optional)
  passwordMinimumLength={8} // Password validation (optional)
  logo={<MyLogo />} // Custom logo (optional)
  layout={{
    // Layout configuration (optional)
    fullScreen: true,
    sideContent: <BrandingContent />,
    sideContentPosition: 'left',
  }}
/>

With Internal Screen State Management

You can also let the Auth component manage its own screen state by using the initialScreen prop instead of screen/setScreen:

<Auth
  initialScreen={{ value: 'signUp' }} // Start on sign up screen (optional)
  onSignIn={handleSignIn}
  onSignUp={handleSignUp}
  onForgotPassword={handleForgotPassword}
/>

This is useful when you don't need to control the screen state externally. The initialScreen prop accepts any valid AuthScreen value:

• { value: 'signIn' } - Sign in screen (default)
• { value: 'signUp' } - Sign up screen
• { value: 'forgotPassword' } - Forgot password screen
• { value: 'confirmSignUpCheckEmail' } - Email confirmation reminder
• { value: 'confirmSignUpWithCode', context: { email: string } } - Code confirmation with email context
• { value: 'confirmResetPassword', context: { email: string } } - Password reset with email context

AuthSocialSignIn Component

Renders one "Continue with …" button per federated identity provider. Auth renders it on the sign-in and sign-up screens when both socialProviders and onSocialSignIn are given — the component is exported for standalone use too.

<Auth
  onSignIn={onSignIn}
  socialProviders={['Google', 'Facebook']}
  onSocialSignIn={({ provider }) => {
    return startFederatedSignIn(provider);
  }}
/>

onSocialSignIn receives { provider } and is expected to hand off to the identity provider — this package is provider-agnostic and performs no redirect of its own. For Cognito, use @ttoss/react-auth-cognito, which wires it to Amplify's signInWithRedirect.

useAuthScreen Hook

Manages authentication screen state and transitions.

const { screen, setScreen } = useAuthScreen({
  value: 'signIn', // Initial screen (optional, defaults to 'signIn')
});

TypeScript Types

Key type definitions for implementing authentication handlers:

type AuthUser = {
  id: string;
  email: string;
  emailVerified?: boolean;
};

type AuthTokens = {
  accessToken: string;
  refreshToken?: string;
  idToken?: string;
  expiresIn?: number;
  expiresAt?: number;
};

type OnSignIn = (params: { email: string; password: string }) => Promise<void>;
type OnSignUp = (params: { email: string; password: string }) => Promise<void>;
type OnForgotPassword = (params: { email: string }) => Promise<void>;