Getting Started

Force Updates lets you require, recommend, or block any app version from the dashboard. The SDK checks the running version on launch and tells your app what to do.

This guide uses Expo. For a bare React Native app, see the section at the bottom — only the adapters change.

Before you start

Create a project in the dashboard and copy your Org ID, Project ID, and API key from project settings.

1. Install

npx expo install @teardown/force-updates expo-device expo-application react-native-mmkv

MMKV is the recommended storage adapter — it's fast, synchronous, and encrypted. It requires a custom dev build (it doesn't run in Expo Go). On Expo Go, use AsyncStorage instead — see below.

Using async storage instead

npx expo install @teardown/force-updates expo-device expo-application @react-native-async-storage/async-storage

Then swap the storage adapter in step 2:

teardown.ts

import { AsyncStorageAdapter } from "@teardown/force-updates/adapters/async-storage";

// ...
storageAdapter: new AsyncStorageAdapter(),

2. Configure

Create a single teardown.ts that builds the client once, then import it anywhere.

teardown.ts

import { TeardownCore } from "@teardown/force-updates";
import { ExpoDeviceAdapter } from "@teardown/force-updates/expo";
import { MMKVStorageAdapter } from "@teardown/force-updates/adapters/mmkv";

export const teardown = new TeardownCore({
  config: { type: "hosted", org_id: "your_org_id", project_id: "your_project_id", api_key: "your_api_key" },
  storageAdapter: new MMKVStorageAdapter(),
  deviceAdapter: new ExpoDeviceAdapter(),
});

3. Wrap your app and gate it

Wrap your app in TeardownProvider, then read the version status with useForceUpdate() to block the app when an update is required.

App.tsx

import { TeardownProvider, useForceUpdate } from "@teardown/force-updates";
import { Text, View } from "react-native";
import { teardown } from "./teardown";

function UpdateGate({ children }: { children: React.ReactNode }) {
  const { isUpdateRequired } = useForceUpdate();

  if (isUpdateRequired) {
    return (
      <View style={{ flex: 1, alignItems: "center", justifyContent: "center", padding: 24 }}>
        <Text>A new version is required. Please update to continue.</Text>
      </View>
    );
  }

  return <>{children}</>;
}

export default function App() {
  return (
    <TeardownProvider core={teardown}>
      <UpdateGate>
        <RootNavigator />
      </UpdateGate>
    </TeardownProvider>
  );
}

That's it. Mark a version as required in the dashboard and it will be gated on the next launch. See Force Updates for recommended-update banners and the full list of statuses.

Identify your users (optional)

By default the SDK identifies the device anonymously. To tie updates and analytics to a signed-in user, call identify after login:

await teardown.identity.identify({
  user_id: "user_123",
  email: "ada@example.com",
});

Call teardown.identity.signOut() on logout. See the API Reference for details.

Bare React Native

Same setup — swap the Expo adapters for the bare adapters and install their native modules.

npm install @teardown/force-updates react-native-device-info react-native-mmkv

teardown.ts

import { TeardownCore } from "@teardown/force-updates";
import { DeviceInfoAdapter } from "@teardown/force-updates/adapters/device-info";
import { MMKVStorageAdapter } from "@teardown/force-updates/adapters/mmkv";

export const teardown = new TeardownCore({
  config: { type: "hosted", org_id: "your_org_id", project_id: "your_project_id", api_key: "your_api_key" },
  storageAdapter: new MMKVStorageAdapter(),
  deviceAdapter: new DeviceInfoAdapter(),
});

See Adapters for every storage, device, and notification option.

1. Install

2. Configure

3. Wrap your app and gate it

Identify your users (optional)

Bare React Native

On this page