DOCSEARCHbyAlgolia
Submit Docs

Swiftpatch Documentation

website·Indexed 31 days ago

https://docs.swiftpatch.io

An over-the-air (OTA) update service for React Native applications. Swiftpatch provides a CLI (swiftpatch-cli) and SDK for shipping JavaScript bundles with features including differential updates, Ed25519 bundle signing, brick protection, staged rollouts, and automatic rollbacks. The platform includes a dashboard for managing apps and releases, support for Expo projects, and integration guides for CI/CD and Sentry.

Tokens
32.8K
Snippets
177
Records
248
Agent score
53%

What's inside Swiftpatch

  1. Overview of Swiftpatch OTA updates

    Swiftpatch is an over-the-air (OTA) update platform for React Native that allows developers to push JavaScript bundles to users without requiring App Store or Play Store reviews. Key features include:

    • Brick Protection: A three-slot architecture with a boot counter to prevent apps from getting stuck on a white screen due to bad bundles.
    • AI-Native Tooling: Risk-scoring for releases, auto-clustered crashes, and an AI PR agent (F8) that suggests fixes via GitHub PRs.
    • Efficiency: Uses delta patches (bsdiff) to download only changed bytes, typically reducing bundle size by 60–98%.
    • Security: Every bundle is verified using Ed25519 signatures.
    • Automation: The swiftpatch init command automatically patches native files including AppDelegate, MainApplication, Info.plist, and strings.xml.

  2. Enable the React Native New Architecture (TurboModules)

    Swiftpatch supports the New Architecture as a TurboModule. Enabling it allows native calls to go through JSI directly, bypassing bridge serialization and improving performance (e.g., checkForUpdate round trip drops from 15ms to 2ms).
    # iOS: Update Podfile
# ENV['RCT_NEW_ARCH_ENABLED'] = '1'
cd ios && pod install && cd ..

# Android: Update gradle.properties
# newArchEnabled=true
cd android && ./gradlew clean && cd ..
    import { IS_TURBO_MODULE_ENABLED } from '@swiftpatch/react-native';
console.log('Using TurboModules:', IS_TURBO_MODULE_ENABLED);

  3. Manage deployment channels for OTA updates

    Channels are named deployment targets that control which users receive specific bundle versions. Every app is automatically created with a default production channel.

    Adding a Channel:

    1. Open the app overview.
    2. In the Channels panel, click + New Channel.
    3. Name the channel (e.g., staging, beta, canary) and click Create.

    Deployment Strategies:

    • Simple: Use only production to ship to all users.
    • Staged: Use staging and production to test before promoting.
    • Multi-tier: Use canary, beta, and production for graduated rollouts.

    Tip: Promote a bundle between channels instead of re-uploading to ensure the exact same bundle is delivered.

  4. Understand the Swiftpatch crash detection layers

    Swiftpatch employs three layers to detect crashes:

    1. Native crash handler: An async-signal-safe handler (C shim on iOS for SIGSEGV, SIGABRT, etc.; JNI breakpad-style on Android) that writes a minimal crash marker (release id, timestamp, signal) to disk.
    2. JS error capture: Uses ErrorUtils.setGlobalHandler and process.on('unhandledRejection') to catch uncaught exceptions and promise rejections.
    3. Boot counter: Trips when a bundle fails to reach markMounted() a specific number of times (N), triggering brick protection.

  5. Understand Brick Protection and the Three-Slot Layout

    Swiftpatch prevents 'bricking' (crash loops or white screens) by ensuring the store-bundled JavaScript always acts as a fallback floor. It uses three slots on disk:

    1. Binary Slot (Immutable): The original bundle from the App Store/Play Store. This is the final fallback.
    2. Stable Slot: The last OTA release that successfully survived crash detection.
    3. New Slot: The most recent downloaded OTA release (staging area).

  6. Prevent JS crashes with native-version pinning

    Swiftpatch prevents JS bundles from crashing on devices with outdated native binaries by using native-version pinning. The SDK reports the device's native version during every checkForUpdate call. The server will only serve releases where the minNativeVersion field is less than or equal to the device's current native version. This ensures that JS bundles requiring new native modules are invisible to older binaries, which continue running the last compatible OTA update.

  7. Manage release tracks using Channels

    Channels are named release tracks that allow you to target specific releases to different groups of devices (e.g., dev, staging, production). Each device subscribes to exactly one channel. Releases published to a specific channel are only visible to devices on that channel.

  8. Configure Swiftpatch for React Native New Architecture

    The Swiftpatch SDK handles its own codegenConfig within its own package.json. Application developers do not need to add a codegenConfig entry to their own package.json for Swiftpatch to work; React Native autolinking automatically detects the SDK's configuration to generate TurboModule stubs.
    {
  "codegenConfig": {
    "name": "RNSwiftPatchSpec",
    "type": "modules",
    "jsSrcsDir": "src/native",
    "ios": { "componentProvider": "" }
  }
}

  9. Enable New Architecture for SwiftPatch v2.0

    SwiftPatch v2.0 supports the React Native New Architecture (TurboModules and Fabric), which significantly improves update check and installation performance.

    <!-- iOS: ios/Podfile --> ENV['RCT_NEW_ARCH_ENABLED'] = '1'

    <!-- Android: android/gradle.properties --> newArchEnabled=true

  10. SwiftPatch Android requirements and compatibility

    SwiftPatch requires Android API 24 (Android 7.0) or higher. This is necessary for WorkManager support used in scheduled background sync. The SDK fully supports the React Native New Architecture (set newArchEnabled=true in android/gradle.properties).

  11. Swiftpatch New Architecture legacy bridge fallback

    If the New Architecture is not enabled in the project, the Swiftpatch SDK automatically falls back to the legacy bridge module. Because the JavaScript API is identical for both the TurboModule and the legacy bridge, there is no change required at the call-site.

  12. Understand how Swiftpatch Delta patches work

    Swiftpatch uses delta patches to reduce the size of React Native bundle updates. Instead of shipping a full 5–10 MB bundle, the server automatically generates bsdiff patches against the last five releases. When a device checks for an update, the SDK identifies the patch matching its current bundle hash, downloads it, verifies the Ed25519 signature, and applies it using a native bspatch implementation to reconstruct the new bundle. If any step fails, the SDK silently falls back to downloading the full bundle.