integrating-clerk-expo
Integrates Clerk authentication into React Native Expo apps using @clerk/clerk-expo. Covers ClerkProvider setup, secure token caching (expo-secure-store), Expo Router/React Navigation auth guards, custom sign-in/sign-up flows (email/password + email codes), SSO/OAuth (useSSO), Sign in with Apple (useSignInWithApple), biometrics (useLocalCredentials), offline support, and production deployment allowlisting. Use when the user mentions Clerk + Expo, @clerk/clerk-expo, Expo Router auth, SSO/OAuth redirects, or deploying Clerk in a mobile app.
How do I install this agent skill?
npx skills add https://github.com/tristanmanchester/agent-skills --skill integrating-clerk-expoIs this agent skill safe to install?
- Gen Agent Trust Hubwarn
The skill provides a workflow for integrating Clerk authentication into Expo apps. It includes a Python verification script that performs local project analysis by reading source code and environment files. While these tools assist development, they involve accessing sensitive file paths and processing untrusted code, which requires oversight.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerfail
3/12 files flagged
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
Clerk authentication in Expo (React Native)
Key constraints (read first)
- Expo native apps do not support Clerk email links. Prefer email verification codes (
email_code) or other strategies. - Clerk prebuilt UI components are not supported on Expo native. Use custom flows (your own screens) plus the control components:
<ClerkLoaded>,<ClerkLoading>,<SignedIn>,<SignedOut>,<Protect>. - Default session tokens are in-memory; for native apps you almost always want a secure token cache (Expo SecureStore).
What this skill does
When implementing Clerk in an Expo app, follow these workflows to:
- Install and configure
@clerk/clerk-expoand environment keys - Wrap the app in
<ClerkProvider>with a securetokenCache - Build custom sign-in/sign-up screens (email + password, email codes)
- Protect routes/screens in Expo Router or React Navigation
- Add OAuth / Enterprise SSO flows via
useSSO()(and fix redirect/deeplink pitfalls) - Add native Sign in with Apple (iOS, native build) via
useSignInWithApple() - Add optional biometric re-auth via
useLocalCredentials() - Optionally enable experimental offline bootstrapping via
__experimental_resourceCache - Prepare for production deployment (domain + allowlisted redirect URLs)
Fast checklist (default: Expo Router)
Copy/paste and tick off:
- In Clerk Dashboard, enable Native API for the application.
- Install:
@clerk/clerk-expo - Add
.env:EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=... - Wrap the root with
<ClerkProvider tokenCache={tokenCache}> - Install SecureStore and use Clerk’s
tokenCachehelper - Create
(auth)route group withsign-in.tsx,sign-up.tsx, and an(auth)/_layout.tsxredirect guard - Add a sign-out button using
useClerk().signOut() - Protect signed-in content using
<SignedIn>/<SignedOut>/<Protect>oruseAuth()+ redirects - If using OAuth/SSO: implement
useSSO()+expo-auth-sessionredirect URL +WebBrowser.maybeCompleteAuthSession() - If iOS Apple sign-in is required: native build +
useSignInWithApple() - If you need resilience offline:
__experimental_resourceCache={resourceCache}and handlenetwork_error - Production: acquire a domain and allowlist mobile SSO redirect URLs
If you need full code examples, open:
references/QUICKSTART.mdreferences/CUSTOM_FLOWS.mdreferences/SSO_OAUTH.mdreferences/HOOKS_AND_COMPONENTS.md
Decide the routing setup
If the project uses Expo Router
Signals:
expo-routerdependency- an
app/directory with route files likeapp/_layout.tsx
➡️ Follow: Expo Router workflow (below).
If the project uses React Navigation directly (no Expo Router)
Signals:
App.tsxwithNavigationContainerand stacks- no
app/directory
➡️ Follow: React Navigation workflow (below).
Workflow A — Expo Router (recommended default)
1) Install + env key
- Install
@clerk/clerk-expo - Set
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEYin.env
2) Root layout: ClerkProvider + secure token cache
In app/_layout.tsx (or the project’s root layout), wrap your app:
import { ClerkProvider } from '@clerk/clerk-expo'
import { tokenCache } from '@clerk/clerk-expo/token-cache'
import { Slot } from 'expo-router'
export default function RootLayout() {
return (
<ClerkProvider tokenCache={tokenCache}>
<Slot />
</ClerkProvider>
)
}
Notes:
- Ensure
expo-secure-storeis installed (required by thetokenCachehelper). - Keep only the publishable key in the client.
3) Auth route group + redirect guard
Create app/(auth)/_layout.tsx that redirects signed-in users away from auth screens:
import { Redirect, Stack } from 'expo-router'
import { useAuth } from '@clerk/clerk-expo'
export default function AuthLayout() {
const { isSignedIn } = useAuth()
if (isSignedIn) return <Redirect href="/" />
return <Stack />
}
4) Build custom sign-in / sign-up screens
Use Clerk hooks (useSignIn, useSignUp) and prefer email_code verification.
See:
5) Protect signed-in routes
Options (pick one, don’t mix randomly):
- Declarative: Wrap signed-in areas with
<SignedIn>and<SignedOut>. - Gate a subtree: Use
<Protect>around content that requires auth. - Imperative: In a layout, check
useAuth()and<Redirect>to/sign-in.
See:
Workflow B — React Navigation (no Expo Router)
1) Wrap the root
Wrap your NavigationContainer (or your app root) with <ClerkProvider tokenCache={tokenCache}>.
2) Split navigation by auth state
- While
!isLoaded: render a splash/loading screen - When
isSignedIn: render your “app” stack - Else: render your “auth” stack
See:
OAuth / Enterprise SSO in Expo (useSSO)
Use useSSO() for OAuth + enterprise SSO. In native, you must provide a valid redirect URL (often via AuthSession.makeRedirectUri(...)) and ensure your redirect URLs are allowlisted for production.
See:
Sign in with Apple (iOS native build)
useSignInWithApple() is iOS-only and requires a native build (won’t work in Expo Go).
Always handle ERR_REQUEST_CANCELED.
See:
Biometrics (store local credentials)
useLocalCredentials() can store password credentials on-device and allow biometric sign-in later (Face ID / fingerprint). Only works for password-based sign-in attempts.
See:
Passkeys
Clerk supports passkeys (WebAuthn). In Expo apps, you’ll integrate passkeys through custom flows; follow Clerk’s passkeys reference for the latest supported strategies and platform constraints.
See:
Offline support (experimental)
You can enable experimental offline bootstrapping via __experimental_resourceCache. Treat as experimental; add good error handling for network_error.
See:
Validation loop (recommended)
- Run the setup verifier:
python scripts/verify_expo_clerk_setup.py .
- Start Expo with a clean cache:
npx expo start -c
- Test flows:
- fresh install → sign up → verify code → app screen
- app restart → user still signed in (token cache working)
- sign out → user returns to auth stack (token cleared)
THE EXACT PROMPT — Implement Clerk in an Expo app
Use this when delegating to another coding agent:
You are implementing Clerk authentication in a React Native Expo app.
1) Detect whether this app uses Expo Router (app/ directory) or React Navigation.
2) Install and configure @clerk/clerk-expo with EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY.
3) Wrap the root with <ClerkProvider tokenCache={tokenCache}> and ensure expo-secure-store is installed.
4) Implement custom sign-in and sign-up screens (email + password, with email verification code strategy 'email_code').
5) Protect signed-in routes appropriately for the chosen router.
6) If OAuth/SSO is requested, implement useSSO() with expo-auth-session redirectUrl and WebBrowser.maybeCompleteAuthSession().
7) Add sign-out.
8) Provide a short test plan and run scripts/verify_expo_clerk_setup.py.
Be precise and keep changes minimal. Do not use email link flows on native.
Quick search (when reading bundled references)
grep -Rni "useSSO" references/
grep -Rni "tokenCache" references/
grep -Rni "enterprise_sso" references/
grep -Rni "__experimental_resourceCache" references/
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/tristanmanchester/agent-skills/integrating-clerk-expo">View integrating-clerk-expo on skillZs</a>