Require a minimum app version

You can set a minimum version for each native app in the Clerk Dashboard, for example, when you release a security fix or change an API that older builds depend on. When a user opens a build below that minimum, Clerk rejects most of the app's requests and the SDK covers it with an update screen. The screen has a button that opens your app's page on the App Store or Google Play, depending on the platform. The user stays signed in and can continue where they left off after updating.

Install expo-application

The update screen requires @clerk/expo 4.15.0 or later and expo-application⁠, which Clerk uses to read your app's version and its iOS bundle ID or Android package name. Install the package:

npx expo install expo-application

How minimum versions work

In development and release builds with expo-application installed, the Clerk SDK sends your app's version and bundle ID or package name with each request. Clerk compares that version with the minimum set for the app.

Set a minimum version

Minimum versions are set per instance, so set them separately for your development and production instances.

1. In the Clerk Dashboard, navigate to the Native applications⁠ page.
2. Select the iOS or Android tab.
3. To add an app, select Add iOS app or Add Android app. To change an existing app, on the right side of the app's row, select the menu icon (...) and select Edit.
4. Enable Minimum app version.
5. Enter the oldest version that users can keep. For iOS, enter up to three dot-separated numbers, such as 4.2.1. For Android, enter a versionCode, such as 42.
6. Enter the App Store URL or Play Store URL that users open to update the app.
7. Select Add application or Update application.

When the app returns to the foreground, the SDK checks whether its version still meets the minimum, at most once every 30 seconds. If the version is too old, the update screen appears.

To remove a minimum, edit the app, disable Minimum app version, and select Update application. Lowering or removing a minimum lets users on newly allowed versions continue once the SDK checks the change.

What users see

<ClerkProvider> shows an update screen over your app automatically on iOS and Android, in a modal that users can't dismiss until they update.

The update screen shows your app's name and installed version. On iOS, it also shows the minimum version and a Go to App Store button. On Android, the button says Go to Google Play, or Update app if the URL isn't a Google Play link. It uses the logo from your application's Settings⁠ and includes an email link if you've set a Support email there.

Show your own update screen

To show your own screen instead of Clerk's update screen, read the app's status with the useAppVersionSupport() hook, which updates when the status changes. The following example defines a custom <UpdateGate> component that shows an update screen while the app's version is unsupported:

import { useAppVersionSupport } from '@clerk/expo'
import type { ReactNode } from 'react'
import { Button, Linking, Text, View } from 'react-native'

export function UpdateGate({ children }: { children: ReactNode }) {
  const { isSupported, updateUrl } = useAppVersionSupport()

  if (isSupported) {
    return children
  }

  return (
    <View>
      <Text>Update required</Text>
      {updateUrl && <Button title="Update" onPress={() => Linking.openURL(updateUrl)} />}
    </View>
  )
}

In your root layout, set updateRequiredViewEnabled={false} on <ClerkProvider> and wrap <Slot /> in <UpdateGate>:

import { ClerkProvider } from '@clerk/expo'
import { tokenCache } from '@clerk/expo/token-cache'
import { Slot } from 'expo-router'
import { UpdateGate } from '../components/update-gate'

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}
      updateRequiredViewEnabled={false}
    >
      <UpdateGate>
        <Slot />
      </UpdateGate>
    </ClerkProvider>
  )
}

Test a minimum version

Test the update screen on a development instance before you set a minimum on your production instance:

1. In the Clerk Dashboard, navigate to the Native applications⁠ page and set a minimum version higher than your app's current version.
2. Close and reopen your app. The update screen opens.
3. Lower the minimum to your app's current version or older, or disable Minimum app version.
4. Bring your app to the foreground. Once the SDK rechecks the minimum, the update screen closes and the user remains signed in.

Troubleshooting

The update screen doesn't appear

Verify that:

Users see an error message instead of the update screen

On iOS, Clerk iOS SDK versions 1.0.0 through 1.6.x send the app's version but don't show an update screen. These versions come with earlier releases of @clerk/expo and @clerk/expo-native-components. When the app is below the minimum, their requests fail with the message "This version of the app is no longer supported. Update the app to continue."

Release a version of your app that uses @clerk/expo 4.15.0 or later, and the latest @clerk/expo-native-components if you use native components, so that users who later fall below a minimum see the update screen.