Integration
Implement @kit/auth native flows in a custom Expo app using the apps/mobile architecture.
What It Does
This guide describes the integration contract used by apps/mobile:
- native auth configuration (
auth.config.ts), - route-level providers and guards,
- and ready-to-use auth screens from
@kit/auth/native.
When To Use
- Porting kit auth into another Expo application.
- Rebuilding auth routes while keeping
@kit/authdefaults.
Prerequisites
@kit/authinstalled in the app workspace.- Supabase auth providers configured.
- Expo router app structure available.
How To Use
Create auth config.
import { parseAuthConfig } from '@kit/auth/config'; import { envs } from '~/envs'; const urls = { exit: '/', dashboard: '/', callback: '/auth/callback', signIn: '/auth/sign-in', signUp: '/auth/sign-up', forgottenPassword: '/auth/forgotten-password', verifyMfa: '/auth/verify', contactPage: `${envs().EXPO_PUBLIC_MARKETING_URL}/en/contact`, privacyPolicy: `${envs().EXPO_PUBLIC_MARKETING_URL}/en/privacy-policy`, termsOfUse: `${envs().EXPO_PUBLIC_MARKETING_URL}/en/terms-of-use`, } satisfies Record<string, string>; export const authConfig = parseAuthConfig({ environment: 'native', urls, // whether to display the terms checkbox during sign-up displayTermsCheckbox: true, // NB: Enable the providers below in the Supabase Console // in your production project providers: { password: true, oAuth: ['google'], }, passwordRequirements: { minLength: 3, maxLength: 99, specialChars: false, numbers: false, uppercase: false, }, });
AuthConfig
| Prop | Type | Default |
|---|---|---|
environment* | "www" | "native" | |
providers* | { password: boolean; oAuth:... | |
urls* | { exit: string; dashboard:... | |
displayTermsCheckbox | boolean | |
passwordRequirements | { minLength: number;... |
Protect app routes in layout.
import React from 'react'; import { AuthProvider, AuthProviderSignedIn, AuthProviderSignedOut } from '@kit/auth/native/ui/auth-provider'; import { Redirect } from 'expo-router'; export default function Layout({ children }: React.PropsWithChildren) { return ( <AuthProvider> <AuthProviderSignedIn> <YourApp /> </AuthProviderSignedIn> <AuthProviderSignedOut> <Redirect href={'/auth/welcome'} /> </AuthProviderSignedOut> </AuthProvider> ); }
Mount kit auth screens under /app/auth.
_layout.tsx
welcome.tsx
Kit screen entrypoints used by apps/mobile:
@kit/auth/native/screens/auth-layout-screens@kit/auth/native/screens/auth-screens@kit/auth/native/screens/with-auth-config
Filter API
Auth integration in mobile depends on filter initialization for package translations.
| Filter | Parameters | Return | Registered By (package file) | Initialized In (app entrypoint) | Environment |
|---|---|---|---|---|---|
get_translations | { language: string; namespace: string } | Record<string, string> | null | kit/auth/src/native/filters/use-filters/use-translation-filters.tsx | apps/mobile/hooks/use-filters.ts (useAuthFilters) | client |
Init Checklist
- Keep
useAuthFilters()inapps/mobile/hooks/use-filters.ts. - Keep
applyAsyncFilter('get_translations', ...)inapps/mobile/config/i18n.config.ts.
MCP Context
capability: auth_mobile_integration entrypoints: - apps/mobile/app/(app)/_layout.tsx - apps/mobile/app/auth/(auth)/[path]/index.tsx - apps/mobile/config/auth.config.ts - apps/mobile/hooks/use-filters.ts - apps/mobile/config/i18n.config.ts - kit/auth/src/native/filters/use-filters/use-translation-filters.tsx inputs: - auth_config_object - expo_router_paths outputs: - guarded_native_auth_routes constraints: - urls in auth config must match real expo router routes - signed-out state must redirect to auth welcome path side_effects: - redirects users between auth and app stacks
Agent Recipe
- Define auth config with
parseAuthConfig({ environment: 'native' }). - Wrap secured stack in
AuthProviderwith signed-in/signed-out branches. - Mount
@kit/auth/nativescreens inapp/authpath tree.
Troubleshooting
- If auth screens render blank, verify
app/auth/(auth)/[path]/index.tsxusesAuthScreens. - If redirects break, verify URL keys in auth config match route files.
- If protected routes load before session restore, verify top-level provider ordering.
Related
Authentication
Configure native authentication flows for apps/mobile using @kit/auth and Supabase Auth.
Retrieve User
Fetch and provide authenticated DB user data in native app flows.
How is this guide?
Last updated on 3/27/2026