VerSynch

A lightweight, simplified React-based version management system that provides automatic update detection, user-friendly update notifications, and intelligent cache management for web applications.

Overview

VerSynch provides a streamlined approach to version management with:

• Simple API: Just a few hooks and components for quick integration
• Smart Updates: Automatic version checking with configurable intervals
• User-Friendly: Activity detection to determine optimal update timing
• Flexible Controls: Postponement system with configurable limits
• Critical Updates: Force update capabilities when needed
• Efficient Caching: Intelligent cache management for smooth updates
• Service Worker Support: Easy integration with service workers
• Persistent State: localStorage-based version tracking

What's New in v1.0.3

• Simplified Architecture: Reduced from many files to just 4 core files
• Smaller Package Size: Significantly reduced bundle size
• Cleaner API: More intuitive hooks and component props
• Enhanced User Experience: Better update notification component
• Improved Activity Detection: Smarter timing of update prompts
• Zero Configuration: Works with sensible defaults out of the box

Installation

npm install versynch
# or
yarn add versynch

Quick Start

import React from 'react';
import { VersionManager, initializeVersionBroadcast } from 'versynch';

// Initialize version broadcast system
initializeVersionBroadcast();

const App = () => {
  return (
    <div className="app">
      {/* Your app content */}
      
      <VersionManager 
        version="1.0.0"
        build={100}
        minBuildToForceUpdate={150} // Force update for builds 150+
      />
    </div>
  );
};

Architecture

The system is designed to be minimal and easy to use, with just a few key components:

Core Hooks (2)

• useVersionManager - Main version detection and management
• useCacheUpdateManager - User interaction and update timing logic

Utility Functions (1)

• versionUtils.ts - Version broadcasting, cache clearing, and simulation utilities

UI Components (1)

• VersionManager.tsx - Ready-to-use update notification component

This simplified architecture makes implementation easy while maintaining all essential functionality.

Configuration Options

useVersionManager Options

interface UseVersionManagerOptions {
  version: string;                    // Current app version
  build: number;                      // Current build number
  minBuildToForceUpdate?: number;     // Build number that triggers force updates (default: 999)
  checkInterval?: number;             // Check interval in ms (default: 300000 = 5 minutes)
  onForceUpdate?: () => void;         // Callback for force updates
  onUpdateAvailable?: () => void;     // Callback when update is detected
}

useCacheUpdateManager Options

interface UseCacheUpdateManagerOptions {
  isUpdateAvailable: boolean;         // Whether an update is available
  onUpdateConfirmed?: () => void;     // Callback when user confirms update
  onUpdatePostponed?: () => void;     // Callback when user postpones update
  countdownDuration?: number;         // Auto-update countdown in ms (default: 60000)
  inactivityThreshold?: number;       // Inactivity threshold in ms (default: 30000)
  maxPostponeCount?: number;          // Maximum postponements allowed (default: 3)
}

Usage Scenarios

Basic Version Checking

const MyApp = () => {
  const versionManager = useVersionManager({
    version: '1.0.0',
    build: 100,
    onUpdateAvailable: () => console.log('Update available!'),
  });

  return <VersionManager {...versionManager} />;
};

Force Updates for Critical Builds

const MyApp = () => {
  const versionManager = useVersionManager({
    version: '1.0.0',
    build: 100,
    minBuildToForceUpdate: 150, // Force update for builds 150+
    onForceUpdate: () => {
      alert('Critical update required!');
      window.location.reload();
    },
  });

  return <VersionManager {...versionManager} />;
};

Custom Update Timing

const MyApp = () => {
  const versionManager = useVersionManager({
    version: '1.0.0',
    build: 100,
    checkInterval: 120000, // Check every 2 minutes
  });

  const cacheManager = useCacheUpdateManager({
    isUpdateAvailable: versionManager.isUpdateAvailable,
    countdownDuration: 30000,    // 30 second countdown
    inactivityThreshold: 15000,  // 15 seconds of inactivity
    maxPostponeCount: 5,         // Allow 5 postponements
  });

  return (
    <VersionManager 
      {...versionManager} 
      cacheManager={cacheManager}
    />
  );
};

Service Worker Integration

// In your service worker
self.addEventListener('install', (event) => {
  // Send update notification to main thread
  self.clients.matchAll().then(clients => {
    clients.forEach(client => {
      client.postMessage({
        type: 'SW_UPDATED',
        version: '1.1.0',
        build: 101,
        timestamp: Date.now()
      });
    });
  });
});

Testing and Development

import { simulateVersionUpdate, clearAppCache } from 'versynch';

// Simulate a version update for testing
const handleTestUpdate = () => {
  simulateVersionUpdate('1.1.0', 101);
};

// Clear cache for development
const handleClearCache = async () => {
  await clearAppCache();
  window.location.reload();
};

API Reference

useVersionManager Hook

Returns an object with:

{
  currentVersion: string;           // Current app version
  currentBuild: number;             // Current build number
  isUpdateAvailable: boolean;       // Whether update is available
  isForceUpdate: boolean;           // Whether force update is required
  lastChecked: Date | null;         // Last check timestamp
  forceUpdate: () => void;          // Force app reload
  checkForUpdates: () => Promise<void>; // Manual update check
}

useCacheUpdateManager Hook

Returns an object with:

{
  isUpdateInProgress: boolean;      // Whether update is in progress
  isPostponed: boolean;             // Whether update was postponed
  postponeCount: number;            // Number of postponements
  countdownSeconds: number;         // Countdown timer value
  handleUpdate: () => Promise<void>; // Trigger update
  postponeUpdate: () => void;       // Postpone update
}

Utility Functions

• initializeVersionBroadcast() - Sets up localStorage defaults and service worker listeners
• clearAppCache() - Clears all caches and unregisters service workers
• forceAppReload() - Forces app reload with cache-busting timestamp
• simulateVersionUpdate(version, build) - Simulates version update for testing purposes

Version Update Flow

VerSynch's update process is designed to be intuitive and straightforward:

1. Quick Initialization: System reads current version/build from props with minimal overhead
2. Efficient Storage: Simple localStorage-based version comparison
3. Smart Detection: Intelligent determination of update availability and requirements
4. User-Friendly Notification: Clean, unobtrusive UI based on update type
5. Activity-Aware: Sophisticated user activity tracking for optimal update timing
6. Flexible Controls: Configurable countdown and postponement options
7. Clean Updates: Comprehensive cache clearing and smooth application reload

Best Practices

Version Numbering

Use semantic versioning with incrementing build numbers for simplicity:

// In your main application configuration
const APP_VERSION = '1.2.3';
const BUILD_NUMBER = 145;

Build Number Strategy

• Keep it simple with a straightforward incrementing build number
• Use build ranges for force updates with clear boundaries:
  • 100-149: Regular updates with user choice
  • 150+: Critical updates requiring immediate action

Update Timing

• Set appropriate check intervals (5-15 minutes) based on your application needs
• Take advantage of the built-in inactivity detection to avoid disrupting active users
• Configure appropriate postponement limits to ensure updates aren't delayed indefinitely

User Experience

• Use the default notification UI for a consistent experience, or customize as needed
• The built-in countdown timer keeps users informed about pending updates
• Postponement options give users control while still ensuring timely updates
• Reserve force updates for security fixes and critical changes only

License

MIT