react-native-version-checker

Type-safe app version checking and update prompts for React Native (iOS & Android).

Built with TypeScript strict mode and runtime validation via Zod. Supports React Native New Architecture (TurboModule).

Features

• Fully typed API -- every function, option, and return value is strictly typed
• Runtime validation -- all external data (native bridge, store APIs) validated with Zod schemas
• Typed error hierarchy -- catch specific errors (NetworkError, ParseError, ProviderError) instead of generic Error
• New Architecture -- TurboModule support (JSI, no JSON bridge)
• Zero global state -- stateless functions, no singletons
• Custom providers -- implement StoreProvider to fetch versions from any source
• Minimal dependencies -- only zod as production dependency

Requirements

• React Native >= 0.73
• iOS >= 13.4
• Android minSdk >= 21

Installation

npm install react-native-version-checker
# or
yarn add react-native-version-checker

For iOS, install pods:

cd ios && pod install

Quick Start

import { needUpdate } from 'react-native-version-checker';

const result = await needUpdate();

if (result.isNeeded) {
  // Prompt the user to update
  console.log(`New version available: ${result.latestVersion}`);
  console.log(`Update at: ${result.storeUrl}`);
}

API Reference

App Metadata

Functions that read metadata from the native platform. These are synchronous and return cached, Zod-validated values.

getCountry()

Returns the device's country code (e.g. "US", "BR").

import { getCountry } from 'react-native-version-checker';

const country: string = getCountry();

getPackageName()

Returns the app's package name / bundle identifier (e.g. "com.myapp").

import { getPackageName } from 'react-native-version-checker';

const pkg: string = getPackageName();

getCurrentVersion()

Returns the app's current version string (e.g. "1.2.3").

import { getCurrentVersion } from 'react-native-version-checker';

const version: string = getCurrentVersion();

getCurrentBuildNumber()

Returns the app's current build number as a string (consistent across iOS and Android).

import { getCurrentBuildNumber } from 'react-native-version-checker';

const build: string = getCurrentBuildNumber();

Version Checking

getLatestVersion(options?)

Fetches the latest published version from the App Store (iOS) or Play Store (Android).

import { getLatestVersion } from 'react-native-version-checker';

const latestVersion: string = await getLatestVersion();

Options:

| Property | Type | Default | Description | |----------|------|---------|-------------| | provider | string \| StoreProvider | Auto (per platform) | Provider to use: 'appStore', 'playStore', or a custom StoreProvider object | | fetchOptions | Record<string, unknown> | undefined | Custom options passed to fetch() |

Examples:

// Force a specific provider
const version = await getLatestVersion({ provider: 'appStore' });

// With custom fetch options (e.g. timeout, headers)
const version = await getLatestVersion({
  fetchOptions: {
    signal: AbortSignal.timeout(5000),
  },
});

needUpdate(options?)

Determines whether the app needs an update by comparing the current version against the latest store version. Returns a fully typed NeedUpdateResult.

import { needUpdate } from 'react-native-version-checker';
import type { NeedUpdateResult } from 'react-native-version-checker';

const result: NeedUpdateResult = await needUpdate();
// {
//   isNeeded: true,
//   currentVersion: "1.0.0",
//   latestVersion: "1.2.0",
//   storeUrl: "itms-apps://apps.apple.com/US/app/id123456789"
// }

Options:

| Property | Type | Default | Description | |----------|------|---------|-------------| | currentVersion | string | Native version | Override the current version (useful for testing) | | latestVersion | string | Fetched from store | Skip the store request by providing the latest version directly | | depth | number | Infinity | Number of version segments to compare | | provider | string \| StoreProvider | Auto (per platform) | Provider to use | | fetchOptions | Record<string, unknown> | undefined | Custom options passed to fetch() |

Examples:

// Only notify on major or minor updates (ignore patch)
const result = await needUpdate({ depth: 2 });
// "1.0.0" vs "1.0.5" → isNeeded: false (patch ignored)
// "1.0.0" vs "1.1.0" → isNeeded: true  (minor changed)

// Only notify on major updates
const result = await needUpdate({ depth: 1 });
// "1.0.0" vs "1.9.0" → isNeeded: false (minor ignored)
// "1.0.0" vs "2.0.0" → isNeeded: true  (major changed)

// Compare manually without store request
const result = await needUpdate({
  currentVersion: '1.0.0',
  latestVersion: '2.0.0',
});

// Use a version from your own backend
const backendVersion = await fetchVersionFromMyAPI();
const result = await needUpdate({ latestVersion: backendVersion });

Store URLs

getStoreUrl(options)

Returns the store URL for the current platform (App Store on iOS, Play Store on Android).

import { getStoreUrl } from 'react-native-version-checker';

// On iOS - requires appID
const url = await getStoreUrl({ appID: '123456789' });

// On Android - uses native packageName if not provided
const url = await getStoreUrl({});

getAppStoreUrl(options)

Returns an App Store URL (itms-apps://) that opens directly in the App Store app.

import { getAppStoreUrl } from 'react-native-version-checker';

const url = await getAppStoreUrl({ appID: '123456789' });
// "itms-apps://apps.apple.com/US/app/id123456789"

// With explicit country
const url = await getAppStoreUrl({ appID: '123456789', country: 'BR' });
// "itms-apps://apps.apple.com/BR/app/id123456789"

| Property | Type | Required | Description | |----------|------|----------|-------------| | appID | string | Yes | The App Store app ID | | country | string | No | Country code (defaults to device locale) |

getPlayStoreUrl(options?)

Returns a Google Play Store URL.

import { getPlayStoreUrl } from 'react-native-version-checker';

const url = await getPlayStoreUrl();
// "https://play.google.com/store/apps/details?id=com.myapp"

// With explicit package name
const url = await getPlayStoreUrl({ packageName: 'com.other.app' });

| Property | Type | Required | Description | |----------|------|----------|-------------| | packageName | string | No | Defaults to the native package name |

Custom Providers

You can implement the StoreProvider interface to fetch version information from any source -- your own backend, a CMS, Firebase Remote Config, etc.

import { needUpdate, getLatestVersion } from 'react-native-version-checker';
import type { StoreProvider, StoreResult } from 'react-native-version-checker';

const myProvider: StoreProvider = {
  async getVersion({ packageName }): Promise<StoreResult> {
    const res = await fetch(`https://api.mybackend.com/version/${packageName}`);
    const data = await res.json();

    return {
      version: data.latestVersion,     // must match /^\d+(\.\d+)*$/
      storeUrl: data.updateUrl,
    };
  },
};

// Use with getLatestVersion
const version = await getLatestVersion({ provider: myProvider });

// Use with needUpdate
const result = await needUpdate({ provider: myProvider });

The StoreProvider interface:

interface StoreProvider {
  getVersion(options: StoreProviderOptions): Promise<StoreResult>;
}

interface StoreProviderOptions {
  packageName?: string;
  country?: string;
  fetchOptions?: Record<string, unknown>;
}

interface StoreResult {
  version: string;   // validated: /^\d+(\.\d+)*$/
  storeUrl: string;
}

Error Handling

Every error thrown by the library is an instance of VersionCheckerError. You can catch specific error types to handle different failure modes:

import {
  needUpdate,
  NetworkError,
  ParseError,
  ProviderError,
  ValidationError,
  VersionCheckerError,
} from 'react-native-version-checker';

try {
  const result = await needUpdate();
} catch (error) {
  if (error instanceof NetworkError) {
    // No internet or store unreachable
    console.warn('Network issue:', error.message);
  } else if (error instanceof ParseError) {
    // Store response has unexpected format
    console.warn('Parse issue:', error.message);
  } else if (error instanceof ProviderError) {
    // App not found in store
    console.warn('Provider issue:', error.message);
  } else if (error instanceof ValidationError) {
    // Invalid options or native data
    console.warn('Validation issue:', error.message);
  }
}

Error hierarchy:

| Error | Code | When | |-------|------|------| | VersionCheckerError | -- | Base class for all library errors | | NetworkError | NETWORK_ERROR | fetch() fails or HTTP status is not ok | | ParseError | PARSE_ERROR | Store response cannot be parsed or has unexpected structure | | ProviderError | PROVIDER_ERROR | App not found in store or provider-specific failure | | ValidationError | VALIDATION_ERROR | Invalid options, typos in option keys, or invalid native data |

Every error includes:

• message -- human-readable description
• code -- machine-readable string for programmatic handling
• cause -- the original underlying error (when applicable)

Exported Types

All types are available for import:

import type {
  // Return types
  NeedUpdateResult,
  StoreResult,
  VersionInfo,

  // Option types
  GetLatestVersionOptions,
  NeedUpdateOptions,
  GetAppStoreUrlOptions,
  GetPlayStoreUrlOptions,
  GetStoreUrlOptions,

  // Provider interface
  StoreProvider,
} from 'react-native-version-checker';

NeedUpdateResult

{
  isNeeded: boolean;
  currentVersion: string;
  latestVersion: string;
  storeUrl: string;
}

VersionInfo

{
  country: string;
  packageName: string;
  currentVersion: string;
  currentBuildNumber: string;
}

Full Example

import { Linking } from 'react-native';
import {
  needUpdate,
  getCurrentVersion,
  NetworkError,
} from 'react-native-version-checker';

async function checkForUpdates() {
  try {
    const result = await needUpdate({ depth: 2 });

    if (result.isNeeded) {
      Alert.alert(
        'Update Available',
        `A new version (${result.latestVersion}) is available. You are on ${result.currentVersion}.`,
        [
          { text: 'Later', style: 'cancel' },
          { text: 'Update', onPress: () => Linking.openURL(result.storeUrl) },
        ]
      );
    }
  } catch (error) {
    if (error instanceof NetworkError) {
      // Silently ignore -- user is offline
      return;
    }
    // Log unexpected errors to your monitoring service
    console.error(error);
  }
}

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library