@salve-software/react-native-hotswap

Fast Refresh covers your JavaScript. This covers the other half: the Kotlin, Swift and C++ underneath it.

hotswap  watching android/src/main/java  →  127.0.0.1:8099
  ✅ probe/android/src/main/java/com/probe/ProbeValues.kt  1234ms
  ✅ probe/cpp/probe.cpp  435ms

| | Save to running | | --------------------- | ----------------------------------------- | | Rebuild and reinstall | 10–30s, and the app restarts from scratch | | hotswap, Kotlin | ~1s, same process | | hotswap, C++ | ~0.5s Android, ~3s iOS | | hotswap, Swift | ~6s, same process |

Install

npm install --save-dev @salve-software/react-native-hotswap

Two lines in metro.config.js, and Android is done:

const { withHotswap } = require('@salve-software/react-native-hotswap/metro.cjs');

// `roots` is optional. Pass one per place you keep native code.
module.exports = withHotswap(mergeConfig(getDefaultConfig(__dirname), config));

The watcher starts with Metro and the agent attaches when the app launches. Everything else is read out of your Gradle build. There is nothing to add to build.gradle and nothing to call from your code.

On Expo, add "@salve-software/react-native-hotswap" to plugins in app.json instead of editing native files by hand, and use a development build. docs/expo.md covers it.

Swift needs two more lines in the Podfile. Without them a Swift method cannot be replaced at all:

require Pod::Executable.execute_command('node', ['-p',
  'require.resolve("@salve-software/react-native-hotswap/hotswap.rb", {paths: [process.argv[1]]})',
  __dir__]).strip

# inside post_install
hotswap_post_install(installer)

New files and removed methods

Patching rewrites code that is already loaded, so it cannot add a class or remove a method. When the runtime refuses for that reason, hotswap publishes a generation instead: it rebuilds the module, loads it beside what is running, and React Native builds its next instance from it.

  ♻️  probe/android/.../BornAtRuntime.kt  reloaded from a new generation  942ms

The cost is your JS state. React rebuilds its instance, so the app goes back to its first screen. The process keeps running, and patching is still tried first.

Generations need one line per platform:

// MainApplication.kt
override val reactHost: ReactHost by lazy {
  HotswapReactHost.create(applicationContext) { PackageList(this).packages }
}

// your RCTDefaultReactNativeFactoryDelegate subclass
import RNHotswap

@objc(getModuleClassFromName:)
func hotswapModuleClass(_ name: UnsafePointer<CChar>) -> AnyClass? {
  Hotswap.moduleClass(fromName: name)
}

Leave them out and patching still works. Only generations stop.

What you see

A successful swap draws a violet pill over the running app. It is not React Native's blue bar on purpose, so you can tell which half of the app changed when both show up. A failed swap draws nothing, and the terminal says why.

When a save seems to do nothing, run npx hotswap --check. It lists what is wired up and what is not. Usually the app is not running, or the build was not debuggable.

Limits

| Change | Result | | -------------------------------------- | ----------------------------------------- | | Method body, anywhere | ✅ patched | | New method or field on a class | ✅ patched, Android 11+ | | A class in a new file | ✅ a generation | | Removing a method or field | ✅ a generation | | MainActivity, MainApplication | patched only. A reload keeps the Activity | | Objective-C, inlined code, iOS devices | ⛔ never | | Release builds | ⛔ by design |

| Requires | | | -------- | ------------------------------------------------------------------------------------- | | Android | API 28 to attach, API 30 for structural changes | | iOS | simulator only | | Build | debuggable, build tools 34–36 (not 37) |

Docs

example/ is a React Native app with its own native code and a module beside it, both wired up. Run cd example && npm install && npx react-native start, then edit one of the files it lists on screen.

| Doc | What is in it | | ------------------------------------ | -------------------------------------------------- | | Expo | the config plugin, and why a dev build is required | | How it works | JVMTI, dynamic replacement, vtables, and prior art | | Generations | the second mechanism, in full | | Limits | everything that does and does not swap |

Licence

MIT.

android/src/main/cpp/vendor/jvmti.h comes from AOSP and is GPLv2 with the Classpath Exception, so linking against it imposes nothing on this package. The header is kept as published, with its licence notice intact.