Walkthrough

NativeScript adds isolate-preserving application reload APIs. Reload clears workers, tasks, and module caches, supports an optional base directory, invokes a JavaScript reload hook, and exposes a reload counter. Tests cover module re-evaluation, native delegates, and application preservation.

Changes

Application reload

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: 🟠 High · up to 60825

Application reload can retain stale modules and prior import state, causing OTA updates or programmatic restarts to execute old code or resolve imports against the previous application state; the merge should be blocked until reload isolation and completion validation are corrected.

Sequence Diagram(s)

sequenceDiagram
  participant JavaScript
  participant NativeScriptRuntime
  participant NativeScript
  participant Runtime
  participant ModuleRegistry
  JavaScript->>NativeScriptRuntime: reloadApplication(baseDir?)
  NativeScriptRuntime->>NativeScript: invoke reload hook
  NativeScript->>Runtime: ReloadJsApplication()
  Runtime->>ModuleRegistry: clear loaded modules and registries
  Runtime-->>JavaScript: invoke global.__onApplicationReload

Possibly related PRs

• NativeScript/ios#386: Adds worker inspector creation, termination, and cleanup related to the worker lifecycle handled during reload.

Suggested reviewers: edusperoni

Poem

A rabbit calls reload at dawn,
The main isolate carries on.
Caches clear and workers rest,
Delegates answer every test.
New modules hop into the nest.

❌ Failed checks (1 warning)

• Create stacked PR
• Commit on current branch

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

• X
• Mastodon
• Reddit
• LinkedIn

Comment @coderabbitai help to get the list of available commands.

I don't see this ever being a good idea.

Bundle 1 calls UIApplicationMain with a custom AppDelegate extended in JS
Bundle 1 calls reloadApplication, destroying its isolate
Bundle 2 loads. AppDelegate is inactive (was killed with previous isolate), any methods called will silently no-op

I don't see this ever being a good idea.

Bundle 1 calls UIApplicationMain with a custom AppDelegate extended in JS Bundle 1 calls reloadApplication, destroying its isolate Bundle 2 loads. AppDelegate is inactive (was killed with previous isolate), any methods called will silently no-op

Yeah, the delegate class outlives the isolate, UIKit keeps dispatching to the old instance, and MethodCallback bails when the isolate's gone. So a JS-extended AppDelegate from bundle 1 would go inert after reload.

The existing teardown behavior (same IsolateWrapper checks in ClassBuilder, the adapters, etc), and restartWithConfig itself has been in the runtime since the embedding work in #231. This just makes it callable from JS with the original config kept around.

The reason it holds up in practice is that core doesn't actually rely on delegate dispatch for lifecycle, everything goes through NSNotificationCenter observers that get re-registered when the new isolate boots, and the soft-reboot path recreates the window against the live scene. We've been shipping these PR changes in production this year and it's been solid on this path, so this is proven useful already.

The case you're describing (custom delegate methods like push token callbacks or openURL) is something worth handling though. Two things I can do as follow-up: have the soft-reboot path reassign UIApplication.sharedApplication.delegate to a fresh instance from the new bundle (with a strong ref since UIKit won't hold one), and add a log behind the script-loading flag when a dead-isolate callback fires so this failure mode is visible instead of silent.

If you can think of other dispatch paths that'd stay pinned to the old isolate, lemme know.

For now. With UIScene we now use delegates, so this only works until iOS 27. It works in embedding because in embedded we don't bootstrap the app and just render views on existing apps

Thanks again for all the feedback @edusperoni, I've pushed up the follow-ups to address all cases (modern UIScene delegates and soon to be legacy standard delegate behavior).
see fc0e142
And also the core adjustment to support both from the supporting pr: NativeScript/NativeScript@6c1479b

I still don't understand why this is needed. Is this for HMR? Because it seems like we're replacing irreplaceable parts of the application. Like if you change the app bootstrap or things that touch delegates we shouldn't expect the HMR to kick in instead of a full restart.

Extended classes are dynamic already, so even if we reevaluate modules they'd just create new native classes that would get picked up when a new view is created.

What does this bring in? Like 2s when someone touches critical files?

This is for seamless production OTA (over-the-air) updates (unrelated to hmr).

For OTA this is even worse! Half of people's delegates will be gone by that point and callbacks likely will just leak all around from the previous isolate. I could understand this for dev, but for prod it's just asking for crashes and weird behavior that are pretty much unfixable. Things like sentry and firebase will likely not work properly due to trying to initialize it multiple times for example

This has already been in production for 6 months and proven stable, it's very helpful. I can show you offline how it works - will share details later this week.