@markvivanco/app-version-checker

app-version-checker

Universal app version checking and update prompts for React, React Native, and web applications.

Features

• 🔄 Semantic Version Comparison - Full support for major.minor.patch.build versioning
• 📱 Multi-Platform Support - Works with iOS, Android, and Web
• 🏗️ Framework Agnostic - Core logic has zero dependencies
• ⚛️ React Integration - Optional React hooks and context providers
• 🔌 Pluggable Architecture - Bring your own data source and storage
• 🎯 Smart Timing - Configurable check intervals and "remind me later" functionality
• 🏪 App Store Integration - Generate App Store and Play Store URLs
• 📦 Tree-Shakeable - Import only what you need
• 📝 TypeScript - Full type definitions included

Installation

npm install app-version-checker
# or
yarn add app-version-checker
# or
pnpm add app-version-checker

Quick Start

Basic Usage (Vanilla JavaScript)

import { VersionChecker } from 'app-version-checker';
import { LocalStorageProvider } from 'app-version-checker/stores';

// Create your data provider
class MyDataProvider {
  getCurrentVersion() {
    return '1.0.0';
  }

  async getLatestVersion(platform) {
    // Fetch from your API
    const response = await fetch(`/api/version/${platform}`);
    const data = await response.json();
    return data.version;
  }

  getAppStoreConfig() {
    return {
      iosAppStoreId: '123456789',
      androidPackageName: 'com.example.app'
    };
  }
}

// Initialize the checker
const checker = new VersionChecker(
  new MyDataProvider(),
  new LocalStorageProvider(),
  {
    minCheckInterval: 60 * 60 * 1000, // 1 hour
    remindLaterDuration: 24 * 60 * 60 * 1000, // 24 hours
  }
);

// Check for updates
const result = await checker.shouldShowUpdatePrompt();
if (result.shouldShowPrompt) {
  // Show your update dialog
  console.log(`Update available: ${result.versionInfo.latestVersion}`);
}

React Usage

import React from 'react';
import { VersionCheckProvider, useVersionCheck } from 'app-version-checker/react';
import { LocalStorageProvider } from 'app-version-checker/stores';

// Your update dialog component
const UpdateDialog = ({ visible, versionInfo, onUpdateNow, onRemindLater }) => {
  if (!visible) return null;

  return (
    <div className="update-dialog">
      <h2>Update Available!</h2>
      <p>Version {versionInfo.latestVersion} is now available</p>
      <button onClick={onUpdateNow}>Update Now</button>
      <button onClick={onRemindLater}>Remind Me Later</button>
    </div>
  );
};

// App component
function App() {
  return (
    <VersionCheckProvider
      dataProvider={new MyDataProvider()}
      storageProvider={new LocalStorageProvider()}
      dialogComponent={UpdateDialog}
    >
      <YourApp />
    </VersionCheckProvider>
  );
}

// Using the hook in a component
function YourComponent() {
  const { isUpdateAvailable, currentVersion, checkForUpdates } = useVersionCheck();

  return (
    <div>
      <p>Current version: {currentVersion}</p>
      {isUpdateAvailable && <p>An update is available!</p>}
      <button onClick={checkForUpdates}>Check for Updates</button>
    </div>
  );
}

React Native Usage

import React from 'react';
import { VersionCheckProvider, useAppStateVersionCheck } from 'app-version-checker/react';
import { AsyncStorageProvider } from 'app-version-checker/stores';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { AppState, Linking } from 'react-native';

// Create providers
const storageProvider = new AsyncStorageProvider(AsyncStorage);

function App() {
  const handleOpenStore = async (url) => {
    const supported = await Linking.canOpenURL(url);
    if (supported) {
      await Linking.openURL(url);
    }
  };

  return (
    <VersionCheckProvider
      dataProvider={new MyDataProvider()}
      storageProvider={storageProvider}
      onOpenStore={handleOpenStore}
      checkOnForeground={true}
    >
      <AppContent />
    </VersionCheckProvider>
  );
}

// Use app state checking
function AppContent() {
  // Automatically check when app comes to foreground
  useAppStateVersionCheck(AppState, true);

  return <YourApp />;
}

Provider Interfaces

Data Provider

Implement IVersionDataProvider to fetch version data from your source:

interface IVersionDataProvider {
  getCurrentVersion(): Promise<string> | string;
  getLatestVersion(platform: Platform): Promise<string | null>;
  getAppStoreConfig(): Promise<AppStoreConfig> | AppStoreConfig;

  // Optional methods
  getCurrentPlatform?(): Platform;
  getFormattedVersion?(): Promise<string> | string;
  isUpdateMandatory?(currentVersion: string, latestVersion: string): Promise<boolean> | boolean;
  getChangeLog?(version: string): Promise<string | null>;
}

Storage Provider

Implement IStorageProvider to store preferences:

interface IStorageProvider {
  getLastCheckTime(): Promise<number | null>;
  setLastCheckTime(timestamp: number): Promise<void>;
  getRemindLaterTime(): Promise<number | null>;
  setRemindLaterTime(timestamp: number): Promise<void>;
  clearRemindLaterTime(): Promise<void>;

  // Optional methods
  getDismissCount?(): Promise<number>;
  incrementDismissCount?(): Promise<void>;
}

Built-in Providers

Storage Providers

• LocalStorageProvider - For web browsers
• AsyncStorageProvider - For React Native
• InMemoryStorageProvider - For testing

Example Data Providers

See the examples/ folder for sample implementations:

• REST API provider
• GraphQL provider
• Firebase provider
• Supabase provider

Core Utilities

Version Comparison

import { compareVersions, isUpdateAvailable } from 'app-version-checker/core';

// Compare versions
compareVersions('1.0.0', '1.0.1'); // Returns -1
compareVersions('2.0.0', '1.9.9'); // Returns 1
compareVersions('1.0.0', '1.0.0'); // Returns 0

// Check if update needed
isUpdateAvailable('1.0.0', '1.0.1'); // Returns true

Version Formatting

import { formatVersionWithBuild, parseVersion } from 'app-version-checker/core';

// Format with build number
formatVersionWithBuild('1.0.0', '123'); // Returns '1.0.0.123'

// Parse version
parseVersion('1.2.3.456');
// Returns { major: 1, minor: 2, patch: 3, build: 456 }

Store URLs

import { getStoreUrl } from 'app-version-checker/core';

const url = getStoreUrl('ios', {
  iosAppStoreId: '123456789'
});
// Returns: https://apps.apple.com/app/id123456789

React Hooks

useVersionCheck

Main hook for accessing version check context:

const {
  versionInfo,           // Current version information
  isUpdateAvailable,     // Boolean flag
  currentVersion,        // Current app version
  formattedVersion,      // Formatted version string
  showUpdateDialog,      // Dialog visibility state
  isChecking,           // Loading state
  error,                // Any errors
  checkForUpdates,      // Manual check function
  handleUpdateNow,      // Open app store
  handleRemindLater,    // Set reminder
} = useVersionCheck();

usePeriodicVersionCheck

Check for updates at regular intervals:

usePeriodicVersionCheck(
  60 * 60 * 1000, // Check every hour
  true            // Enabled
);

useVisibilityVersionCheck

Check when page becomes visible (web):

useVisibilityVersionCheck(true);

Configuration Options

const options = {
  // Minimum time between version checks (milliseconds)
  minCheckInterval: 60 * 60 * 1000, // Default: 1 hour

  // Duration for "remind me later" (milliseconds)
  remindLaterDuration: 24 * 60 * 60 * 1000, // Default: 24 hours

  // Skip version checking on web platform
  skipWebPlatform: true, // Default: true

  // Custom platform detection
  getPlatform: () => detectPlatform(), // Optional
};

Migration from Existing Code

If you have existing version checking code, here's how to migrate:

• Extract your version fetching logic into a data provider
• Choose or implement a storage provider for preferences
• Replace your version checking logic with VersionChecker
• Update your UI components to use the provided hooks

See examples/migration/ for detailed migration guides.

Examples

Check the examples/ directory for:

• React web app example
• React Native app example
• Next.js integration
• Vue.js integration
• Firebase integration
• Supabase integration
• Custom provider examples

Testing

The package includes utilities for testing:

import { InMemoryStorageProvider } from 'app-version-checker/stores';

// Use in-memory storage for tests
const testStorage = new InMemoryStorageProvider();

// Mock your data provider
const mockDataProvider = {
  getCurrentVersion: () => '1.0.0',
  getLatestVersion: () => Promise.resolve('2.0.0'),
  // ...
};

API Reference

Full API documentation is available at docs/api.md.

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT © [Your Name]

Changelog

See CHANGELOG.md for version history.

Support

• 📧 Email: [e-mail]
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues