@atzentis/auth-expo

React Native/Expo auth screens and components for auth.atzentis.com. Provides 18 ready-to-use native screens, biometric authentication, secure token storage via expo-secure-store, and first-class expo-router integration.

Features

• 18 native screens — complete auth, settings, and organization flows for React Native
• Biometric authentication — FaceID/TouchID via expo-local-authentication
• Secure storage — tokens stored in the device keychain via expo-secure-store
• expo-router integration — AuthView maps route strings to screens; useAuthRedirect wraps router.replace
• Session-based conditional rendering — AuthGate and ProtectedScreen with role/permission guards
• TanStack Query — 5 mutation hooks and 2 query hooks backed by the same cache as @atzentis/auth-react
• React 19 patterns — uses React.use(Context) and <Context value={}> provider syntax

Installation

npx expo install @atzentis/auth-expo @atzentis/auth-sdk

Then install the required peer dependencies:

npx expo install \
  better-auth \
  @better-auth/expo \
  expo-secure-store \
  expo-local-authentication \
  expo-localization \
  expo-router \
  expo-application \
  expo-device \
  expo-haptics

And install the JS peer dependencies:

npm install @tanstack/react-query react-hook-form @hookform/resolvers

Peer Dependencies

| Package | Version | Required | | --- | --- | --- | | better-auth | >= 1.2.0 | Yes | | @better-auth/expo | >= 1.2.0 | Yes | | expo-secure-store | >= 14.0.0 | Yes | | expo-localization | >= 16.0.0 | Yes | | expo-router | >= 4.0.0 | Yes | | expo-application | >= 6.0.0 | Yes | | expo-device | >= 7.0.0 | Yes | | react-native | >= 0.76.0 | Yes | | @tanstack/react-query | >= 5.0.0 | Yes | | react-hook-form | >= 7.45.0 | Yes | | @hookform/resolvers | >= 3.3.0 | Yes | | lucide-react-native | >= 0.400.0 | Yes | | @expo/ui | >= 0.6.0 | Optional | | expo-local-authentication | >= 15.0.0 | Optional | | expo-haptics | >= 14.0.0 | Optional | | react-native-reanimated | >= 3.0.0 | Optional |

Quick Start

Wrap your auth flow with AuthProvider and render screens via AuthView:

import { AuthProvider, AuthView } from "@atzentis/auth-expo";

export default function AuthScreen() {
  return (
    <AuthProvider baseUrl="https://auth.atzentis.com">
      <AuthView initialRoute="login" />
    </AuthProvider>
  );
}

For settings or organization screens, render them directly:

import { AuthProvider, ChangePasswordScreen } from "@atzentis/auth-expo";

export default function ChangePasswordPage() {
  return (
    <AuthProvider baseUrl="https://auth.atzentis.com">
      <ChangePasswordScreen />
    </AuthProvider>
  );
}

Screens

Auth Screens

| Screen | Description | | --- | --- | | LoginScreen | Email/password login with optional biometric sign-in | | SignupScreen | New account registration | | PhoneLoginScreen | Two-step phone number + OTP verification | | MagicLinkScreen | Multi-step passwordless magic link flow | | TwoFactorScreen | TOTP code entry with backup code fallback | | ForgotPasswordScreen | Email input with timed cooldown for resend | | ResetPasswordScreen | Token-based new password form | | EmailVerificationScreen | Auto-verify via deep link or manual OTP entry |

Use AuthView to render any auth screen by route name:

import { AuthView } from "@atzentis/auth-expo";

// Renders the LoginScreen
<AuthView initialRoute="login" />

// Renders the SignupScreen
<AuthView initialRoute="signup" />

// Supported routes: "login" | "signup" | "phone-login" | "magic-link"
//   "two-factor" | "forgot-password" | "reset-password" | "email-verification"

Settings Screens

| Screen | Description | | --- | --- | | ChangePasswordScreen | Update account password | | ChangeEmailScreen | Update email address with verification | | UpdateNameScreen | Update display name | | UpdateUsernameScreen | Update username | | UpdateAvatarScreen | Upload or select a profile avatar | | SessionsScreen | View and revoke active sessions | | DeleteAccountScreen | Multi-step account deletion with confirmation | | TwoFactorSettingsScreen | Enable, verify, or disable two-factor authentication |

Organization Screens

| Screen | Description | | --- | --- | | OrganizationSwitcherScreen | List organizations and switch the active one | | OrganizationMembersScreen | View members, update roles, and remove members |

Components

| Component | Description | | --- | --- | | AuthGate | Renders children only when a session exists; renders a fallback otherwise | | ProtectedScreen | RBAC guard — accepts role and permission props with a fallback | | OAuthButton | Native OAuth provider button (google, apple, github) | | FormInput | Styled text input for use inside auth forms | | FormPasswordInput | Password input with show/hide toggle | | SubmitButton | Loading-aware submit button | | ErrorFeedback | Accessible error message display | | SuccessFeedback | Accessible success message display | | AuthContainer | KeyboardAvoidingView layout wrapper for auth screens |

Hooks

| Hook | Purpose | | --- | --- | | useAuthClient() | Access the underlying Better Auth client instance | | useAuthLocalization() | Access the active localization strings | | useBiometric() | Check biometric availability and trigger authentication | | useAuthRedirect() | Programmatic navigation using expo-router's router.replace |

Mutation Hooks

| Hook | Purpose | | --- | --- | | useLogin() | Sign in with email and password | | useSignup() | Create a new account | | useLogout() | Sign out the current session | | useRequestPasswordReset() | Request a password reset email | | useResetPassword() | Submit a new password using a reset token |

Query Hooks

| Hook | Purpose | | --- | --- | | useUser() | Fetch the current user profile | | useSession() | Fetch the current session |

AuthProvider Props

| Prop | Type | Description | | --- | --- | --- | | baseUrl | string | Required. The auth.atzentis.com URL | | initialUser | User | Optional. Pre-hydrated user for SSR | | onSessionExpired | () => void | Called when the session expires | | onTokenRefreshed | (session: Session) => void | Called after a successful token refresh | | onNewDeviceAlert | (alert: LoginAlert) => void | Called when a new device login is detected |

Localization

All screens and components read from the shared @atzentis/auth-locales package. Override strings by passing a localization prop to AuthProvider:

<AuthProvider
  baseUrl="https://auth.atzentis.com"
  localization={{
    loginScreen: {
      title: "Welcome back",
      submitButton: "Continue",
    },
  }}
>

Related Packages

• @atzentis/auth-sdk — Core TypeScript client (required)
• @atzentis/auth-react — React hooks and components for web

License

MIT — see LICENSE for details.