Skip to main content

Enable offline support in your Expo app,

Experimental

The __experimental_resourceCache property introduced in this guide is an experimental feature. It is subject to change in future updates, so use it cautiously in production environments. Ensure thorough testing and stay informed through the package's changelog.

The Clerk Expo SDK provides enhanced offline support to improve reliability and user experience. This update enables your app to bootstrap offline using cached Clerk resources, ensuring quick initialization without requiring an internet connection.

It offers the following benefits:

  • Initialization of the Clerk SDK is now more resilient to network failures.
  • Faster resolution of the isLoaded property and the <ClerkLoaded> control component with only a single network fetch attempt. If the fetch fails, it gracefully falls back to cached resources.
  • Network errors are no longer muted, allowing developers to catch and handle them effectively in their .
  • The getToken() function in the useAuth() hook now supports returning cached tokens, minimizing disruptions caused by network failures.

How to enable offline support

To enable offline support in your Expo app, follow these steps:

Install the necessary peer dependencies

The expo-secure-store package is required to use the offline support feature.

npm install expo-secure-store
pnpm add expo-secure-store
yarn add expo-secure-store
bun add expo-secure-store

Use the __experimental_resourceCache property on ClerkProvider

On <ClerkProvider>, pass the resourceCache object to the __experimental_resourceCache property, as shown in the following example:

app/_layout.tsx
import { ClerkProvider } from '@clerk/expo'
import { Slot } from 'expo-router'
import { tokenCache } from '@clerk/expo/token-cache'
import { resourceCache } from '@clerk/expo/resource-cache'

// Import your Publishable Key
const publishableKey = process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY

if (!publishableKey) {
  throw new Error('Add your Clerk Publishable Key to the .env file')
}

export default function RootLayout() {
  return (
    <ClerkProvider
      publishableKey={publishableKey}
      tokenCache={tokenCache}
      __experimental_resourceCache={resourceCache}
    >
      <Slot />
    </ClerkProvider>
  )
}

How to handle network errors

When there is no internet connection, Clerk's (e.g., signIn.password()) return a network error in their error result instead of throwing it.

To handle network errors in your Expo app, use isClerkRuntimeError() to check whether the returned error is a Clerk runtime error, then check its code property for network_error. See the following example.

import { isClerkRuntimeError, useAuth, useSignIn } from '@clerk/expo'
import { type Href, useRouter } from 'expo-router'
import { Button, Text, TextInput, View } from 'react-native'
import React from 'react'

export default function SignInPage() {
  const { signIn, fetchStatus } = useSignIn()
  const { isLoaded } = useAuth()
  const router = useRouter()

  const [emailAddress, setEmailAddress] = React.useState('')
  const [password, setPassword] = React.useState('')
  const [error, setError] = React.useState<string | null>(null)

  const onSignInPress = async () => {
    if (!isLoaded) return
    setError(null)

    try {
      const { error: signInError } = await signIn.password({
        emailAddress,
        password,
      })
      if (signInError) {
        if (isClerkRuntimeError(signInError) && signInError.code === 'network_error') {
          setError('Network error. Check your connection and try again.')
          return
        }

        setError('Unable to sign in. Please try again.')
        console.error(JSON.stringify(signInError, null, 2))
        return
      }

      if (signIn.status === 'complete') {
        const { error: finalizeError } = await signIn.finalize({
          navigate: ({ session, decorateUrl }) => {
            // Handle session tasks
            // See https://clerk.com/docs/guides/development/custom-flows/authentication/session-tasks
            if (session?.currentTask) {
              console.log(session?.currentTask)
              return
            }

            // If no session tasks, navigate the signed-in user to the home page
            const url = decorateUrl('/')
            if (url.startsWith('http')) {
              window.location.href = url
            } else {
              router.replace(url as Href)
            }
          },
        })
        if (finalizeError) {
          if (isClerkRuntimeError(finalizeError) && finalizeError.code === 'network_error') {
            setError('Network error. Check your connection and try again.')
            return
          }

          setError('Unable to sign in. Please try again.')
          console.error(JSON.stringify(finalizeError, null, 2))
        }
      } else {
        setError('Sign-in is not complete. Additional verification may be required.')
      }
    } catch (err) {
      // See https://clerk.com/docs/guides/development/custom-flows/error-handling
      // for more info on error handling
      setError('Unable to sign in. Please try again.')
      console.error(JSON.stringify(err, null, 2))
    }
  }

  return (
    <View>
      <TextInput
        autoCapitalize="none"
        value={emailAddress}
        placeholder="Email address"
        onChangeText={setEmailAddress}
      />
      <TextInput
        value={password}
        placeholder="Password"
        secureTextEntry
        onChangeText={setPassword}
      />
      <Button
        title="Sign in"
        onPress={onSignInPress}
        disabled={!isLoaded || fetchStatus === 'fetching'}
      />
      {error && <Text>{error}</Text>}
    </View>
  )
}

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub