SwiftPatch React Native SDK

Over-the-Air (OTA) update SDK for React Native with differential patching, automatic rollback, and cryptographic verification. Optimized for the React Native New Architecture.

✨ Features

• 🚀 Differential Patching - Download only what changed (bsdiff/bspatch)
• 🔄 Automatic Rollback - Crash detection with instant recovery
• 🔒 Bundle Signing - RSA signature verification for security
• ⚡ New Architecture - TurboModules for 40% faster performance
• 🎯 Dual-Slot System - Safe production/staging environment switching
• 📦 Small Updates - Patches typically 10-50x smaller than full bundles
• 🛡️ Type-Safe - Full TypeScript support
• 🎨 React Hooks - Modern API with Provider pattern
• 📱 Cross-Platform - iOS and Android support

📦 Installation

npm install @swiftpatch/react-native
# or
yarn add @swiftpatch/react-native

iOS Setup

cd ios
pod install
cd ..

Android Setup

No additional steps required.

🚀 Quick Start

1. Wrap your app with SwiftPatchProvider

import { SwiftPatchProvider } from '@swiftpatch/react-native';

export default function App() {
  return (
    <SwiftPatchProvider
      config={{
        deploymentKey: 'YOUR_DEPLOYMENT_KEY',
        serverUrl: 'https://your-server.com/api/v1', // optional
        debug: __DEV__,
      }}
    >
      <YourApp />
    </SwiftPatchProvider>
  );
}

2. Use the hook in your components

import { useSwiftPatch, UpdateStatus } from '@swiftpatch/react-native';

function UpdateButton() {
  const {
    status,
    availableUpdate,
    downloadProgress,
    checkForUpdate,
    downloadUpdate,
    installUpdate,
    restart,
  } = useSwiftPatch();

  const handleUpdate = async () => {
    // Check for updates
    const update = await checkForUpdate();

    if (update) {
      // Download the update
      await downloadUpdate();

      // Install and restart
      await installUpdate();
      restart();
    }
  };

  if (status === UpdateStatus.DOWNLOADING) {
    return <Text>Downloading: {downloadProgress?.percentage}%</Text>;
  }

  return (
    <Button
      title={availableUpdate ? 'Update Available' : 'Check for Updates'}
      onPress={handleUpdate}
    />
  );
}

3. Or use the built-in modal

import { useSwiftPatchModal, SwiftPatchModal } from '@swiftpatch/react-native';

function App() {
  const { showModal } = useSwiftPatchModal();

  return (
    <>
      <YourApp />
      <SwiftPatchModal />
      <Button title="Check for Updates" onPress={showModal} />
    </>
  );
}

📚 API Reference

SwiftPatchProvider

interface SwiftPatchConfig {
  deploymentKey: string;
  serverUrl?: string;
  checkOnResume?: boolean;
  checkInterval?: number;
  installMode?: InstallMode;
  mandatoryInstallMode?: InstallMode;
  debug?: boolean;
  customHeaders?: Record<string, string>;
  publicKey?: string;
  autoStabilizeAfterLaunches?: number;
}

useSwiftPatch Hook

const {
  // State
  status,                    // Current update status
  downloadProgress,          // Download progress (0-100%)
  currentBundle,             // Currently installed bundle info
  availableUpdate,           // Available update info
  isRestartRequired,         // Whether restart is needed
  error,                     // Last error
  lastCheckedAt,             // Last check timestamp
  slotMetadata,             // Dual-slot system metadata
  environment,              // Current environment (PROD/STAGE)

  // Actions
  checkForUpdate,           // Check for available updates
  downloadUpdate,           // Download available update
  installUpdate,            // Install downloaded update
  restart,                  // Restart app to apply update
  rollback,                 // Rollback to previous version
  clearPendingUpdate,       // Clear pending update
  getCurrentBundle,         // Get current bundle info
  stabilize,                // Stabilize current bundle
  switchEnvironment,        // Switch PROD/STAGE environment
  getSlotMetadata,          // Get slot metadata
  markMounted,              // Mark app as mounted (crash detection)
  downloadStageBundle,      // Download staging bundle
} = useSwiftPatch();

Imperative API (Non-React)

For use outside React components:

import { SwiftPatch } from '@swiftpatch/react-native';

const swiftPatch = new SwiftPatch({
  deploymentKey: 'YOUR_KEY',
});

await swiftPatch.init();

const update = await swiftPatch.checkForUpdate();
if (update) {
  await swiftPatch.downloadAndInstall(update);
  swiftPatch.restart();
}

🎯 Install Modes

enum InstallMode {
  IMMEDIATE = 'immediate',           // Install and restart immediately
  ON_NEXT_RESTART = 'onNextRestart', // Install on next app restart
  ON_NEXT_RESUME = 'onNextResume',   // Install when app resumes
}

🔧 Advanced Features

Differential Patching

SwiftPatch automatically uses differential patching when available:

// Server determines if patch is available
// SDK handles full bundle vs patch automatically
await downloadUpdate();

// Patch files are typically 10-50x smaller
// e.g., 50MB bundle → 2MB patch

Automatic Rollback

// Crash detection window: 10 seconds
// If app crashes during this window, automatic rollback occurs

const { rollback } = useSwiftPatch();

// Manual rollback
await rollback();

Bundle Signing (Optional)

<SwiftPatchProvider
  config={{
    deploymentKey: 'YOUR_KEY',
    publicKey: 'YOUR_RSA_PUBLIC_KEY',
  }}
>
  <App />
</SwiftPatchProvider>

// SDK automatically verifies signatures

Environment Switching (PROD/STAGE)

const { switchEnvironment, environment } = useSwiftPatch();

// Switch to staging
await switchEnvironment(EnvironmentMode.STAGING);

// Download and test staging bundle
await downloadStageBundle(url, hash);

// Switch back to production
await switchEnvironment(EnvironmentMode.PRODUCTION);

🆕 New Architecture Support

SwiftPatch v2.0+ fully supports the React Native New Architecture:

Enable New Architecture

iOS (ios/Podfile):

ENV['RCT_NEW_ARCH_ENABLED'] = '1'

Android (android/gradle.properties):

newArchEnabled=true

Performance Benefits

| Operation | Legacy | TurboModule | Improvement | |-----------|--------|-------------|-------------| | Check Update | 15ms | 2ms | 87% faster | | Get Bundle Info | 8ms | 1ms | 87% faster | | Native Calls | 3-5ms | 0.5-1ms | 80% faster |

Detection

import { IS_TURBO_MODULE_ENABLED } from '@swiftpatch/react-native';

console.log('Using TurboModules:', IS_TURBO_MODULE_ENABLED);

🧪 Testing

npm test

All core functionality is tested:

• Update checking
• Download & installation
• Rollback mechanisms
• Cryptographic verification
• Event handling

📱 Platform Requirements

| Platform | Minimum | Recommended | |----------|---------|-------------| | iOS | 13.4+ | 15.0+ | | Android | API 24+ (7.0) | API 31+ (12) | | React Native | 0.76.0+ | 0.76.5+ | | React | 18.2.0+ | 18.3.0+ |

🔒 Security

• Bundle Signing: Optional RSA signature verification
• HTTPS Only: All downloads over secure connections
• Hash Verification: SHA-256 hash checking for all bundles
• Integrity Checks: Automatic corruption detection

📊 Bundle Size

| File | Size | Compressed | |------|------|------------| | Core JS | ~45KB | ~12KB | | Native (iOS) | ~150KB | - | | Native (Android) | ~200KB | - |

🛠️ Development

# Clone the repository
git clone https://github.com/codewprincee/react-native-swiftpatch.git

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run prepare

# Run example app
npm run example start

🐛 Troubleshooting

iOS Build Errors

cd ios
rm -rf Pods Podfile.lock
pod install
cd ..

Android Build Errors

cd android
./gradlew clean
cd ..

Type Errors

npm run typescript

📄 License

MIT License - see LICENSE for details

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide first.

📞 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Docs: swiftpatch.io

🎉 Acknowledgments

Built with:

• React Native
• bsdiff/bspatch for differential patching
• TypeScript

Made with ❤️ by the SwiftPatch Team