react-native-runtimes: moving heavy React Native screens onto secondary Hermes runtimes
Run heavy React Native components and business logic in isolated Hermes runtimes (without freezing your main JS thread)
At a glance
- What is it?
- Margelo's react-native-runtimes adds a multi-runtime layer to React Native New Architecture apps, letting you mount components, screens and headless tasks in named Hermes runtimes. It is alpha software with no documented rollback path, and it is not for legacy-architecture apps.
- Who is it for?
- Adopt it if you are already on React Native 0.76+ with the New Architecture and Hermes, and you have one or two screens that repeatedly monopolize the main JS runtime. Do not adopt it if you depend on the legacy architecture, a non-Hermes engine, or if you need to pass large mutable objects between runtimes.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 108 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- margelo/react-native-runtimes563 ★ · +2
| Repository | 2026-09-20 | 2026-11-21 |
|---|---|---|
| margelo/react-native-runtimes | 561 | 563 |
2 Stars in the last 62 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem react-native-runtimes is aimed at
React Native gives an app one main JavaScript runtime. The README's framing is blunt about the consequence: when a feed, chat screen, editor, reducer or hydration job monopolizes that runtime, input, animation and navigation all compete for the same VM. That is not a bug you fix with memoization if the work itself is genuinely heavy. It is a scheduling problem, and the only real fix is to stop sharing the scheduler.
The project is for teams that already have one or two specific surfaces that repeatedly cause this. The README lists the qualifying symptoms: a chat, feed or inbox that janks on mount; reducers or stores competing with animation; slow first-open screens; background hydration or decoding; state that must be visible everywhere. It is explicitly not for apps where memoization, virtualization or moving work off render already fixes the issue, and not for legacy architecture or non-Hermes engines. That scoping is unusually honest for a library README, and it matters more than the feature list.
The target audience is React Native New Architecture apps on Hermes, version 0.76 or newer, including Expo apps via a config plugin. If you are not on that baseline, the rest of this article does not apply to you.
How the multi-runtime layer actually works
The mechanism has three moving parts, all visible in the README and the repository layout.
First, a Metro transform. Wrapping a component in OnRuntime does not register anything by hand. The README states that Metro rewrites the JSX to a registered threaded boundary at build time. That is why the component example is a single wrapper with no registration call: the build step is the registration step. It also means the transform is load-bearing. If your Metro config does not pick it up, the wrapper is just a component.
Second, named Hermes runtimes. Components mount into runtimes addressed by string names such as "chat-runtime" or a per-conversation name like `chat-${conversationId}`. The same naming scheme applies to ThreadedScreen for full routes, ThreadedRuntime.prewarm for starting a runtime before navigation, and ThreadedRuntime.runHeadlessTask for work with no view attached. One naming convention covers all four entry points, which is the cleanest part of the design.
Third, a native C++ singleton backing shared state. The @react-native-runtimes/state package is described as a Zustand-style shared store backed by a process-wide C++ singleton, giving synchronous reads and commits from every runtime. This is the piece that makes the isolation usable, because it avoids passing live objects across heaps. Cross-runtime function calls are the other path: runtimeFunction wraps a typed function, and call invokes it on a named runtime, with arguments and return values JSON-serialized automatically. Serialization is the boundary. Anything that cannot survive JSON cannot cross it.
Installing react-native-runtimes and mounting a first threaded component
The README does not print an install command. What it does give is the package split and the entry points. The two published packages are @react-native-runtimes/core and @react-native-runtimes/state, both released as 0.1.0-alpha.2 on 2026-08-05. The root package.json declares a workspace layout over packages/* and example, and an engines field requiring Node 22.11.0 or newer. The repository ships an example app with its own metro.config.js, babel.config.js and index.business-runtime.ts, which is the closest thing to a working reference.
Start from the wrapper. Import OnRuntime from core and wrap the component you want off the main runtime:
import { OnRuntime } from '@react-native-runtimes/core';
<OnRuntime name="feed-runtime">
<HeavyFeedList userId={userId} />
</OnRuntime>The README's comment above this snippet is "That's it. This component now renders in its own Hermes instance." What you should see is the wrapped component rendering normally while the main runtime stays free for navigation, gestures and input. If it renders but the main thread still janks, the transform did not rewrite the boundary.
For a whole route, the pattern changes to a threaded component plus a screen:
import { ThreadedScreen, threadedComponent } from '@react-native-runtimes/core';
export const ConversationScreen = threadedComponent<Props>(
'ConversationScreen',
(props) => <ConversationRoute {...props} />,
);That component is then passed to ThreadedScreen with a component prop, a props object and a runtimeName such as `chat-${conversationId}`. To remove the cold-start gap, prewarm the same name before the user taps:
import { ThreadedRuntime } from '@react-native-runtimes/core';
await ThreadedRuntime.prewarm(`chat-${conversationId}`);The README suggests firing this when the inbox row becomes visible. Note that prewarm returns a promise and the example awaits it; the README does not say what happens if the runtime is already warm, or what the promise resolves to.
Headless tasks and cross-runtime calls: where the JSON boundary bites
Headless tasks are the most useful part of the library for anything that is not a screen. You register a task on the threaded bundle side and dispatch it from anywhere:
registerThreadedHeadlessTask('hydrateConversation', async ({ payload }) => {
const messages = await loadMessages(payload.conversationId, payload.limit);
await messagesStore.setSubtreeState(payload.conversationId, messages, true);
});Dispatch takes a runtime name and a payload:
await ThreadedRuntime.runHeadlessTask('hydrateConversation', {
runtimeName: 'chat-worker-runtime',
payload: { conversationId, limit: 50 },
});Cross-runtime function calls follow the same shape. A function is wrapped with runtimeFunction and invoked with call on a named runtime, and the README states that arguments and return values are JSON-serialized automatically. The example returns a plain object with an input number, a result number and an ISO timestamp string.
This is the constraint to internalize. The README's own "when not to use it" section says you should not pass large mutable objects or non-serializable props directly between runtimes, and instead pass ids or keys and read shared data from native-backed state. That is not a stylistic preference. It is the architecture: isolated heaps with a serialization boundary between them. If your data model is a class instance, a Map, a Date used as a Date, or a deeply nested object you mutate in place, this library will force a rewrite of that path before it helps you.
What the alpha status and the missing rollback story mean in practice
Both published packages are 0.1.0-alpha.2. The first core release, 0.1.0-alpha.1, landed on 2026-06-01, and the current pair landed on 2026-08-05. That is a two-month gap between the two alpha lines, which is a normal cadence for early work and not a signal of abandonment. The repository is not archived and the last push was on 2026-08-05, which is recent.
Alpha status has concrete consequences here. The README does not document rollback, and it does not document what happens to a mounted threaded component when a runtime is torn down or when a prewarmed runtime is never used. Prewarming creates a runtime before the user navigates; if the user never taps that row, nothing in the README says how that runtime is reclaimed. Treat runtime lifetime as something you will have to measure yourself.
The Metro transform is the second risk. Because registration happens at build time rather than at runtime, a component that silently fails to be rewritten will still render, just on the main runtime. That failure mode is quiet. There is no documented diagnostic for it. You find out by profiling, not by reading a log.
The third limitation is architectural, not a bug: legacy architecture and non-Hermes engines are out of scope. The README states this directly. If you have not migrated to the New Architecture, react-native-runtimes is not a partial-adoption tool. It is a post-migration tool.
How it differs from worklets and worker-thread approaches
The closest mental model most React Native engineers already have is the worklet, as used by Reanimated and the broader worklet ecosystem. A worklet is a function you move to a separate JS context, typically a UI-oriented one, and it is designed around small, frequent, frame-critical units of work. react-native-runtimes is aimed at the opposite granularity: whole components, whole screens, long-lived named runtimes and headless tasks that hydrate stores. The README's own examples are a feed list, a conversation route and a hydration job, not a per-frame animation callback.
The second difference is state. Worklets communicate through shared values designed for animation. Here, sharing goes through @react-native-runtimes/state, a Zustand-style store backed by a process-wide C++ singleton with synchronous reads and commits from every runtime. That is a different promise: not "pass this value to the UI thread" but "every runtime sees the same store." Cross-runtime function calls are the explicit escape hatch when you need a result back, and they pay a JSON serialization cost each way.
If your problem is a janky gesture animation, this library is the wrong tool and the README implicitly agrees by not addressing that case. If your problem is that a chat screen's reducer and message decoding stall navigation for a few hundred milliseconds on open, the runtime-per-feature model maps onto it directly.
Licence, upgrade cost and what to check before you commit
The README badge says License: MIT and links to a LICENSE file. The repository metadata I have does not carry a licence identifier, so the badge is the only statement available; confirm the LICENSE file in the repository before you rely on it. MIT is permissive, which means the usual obligations apply: keep the copyright notice and the licence text with redistributed copies. That is a description of the licence, not legal advice, and if your organisation has a policy on alpha dependencies it will matter more than the licence text.
Upgrade cost is where alpha packages earn their reputation. The API surface shown in the README is small: OnRuntime, ThreadedScreen, threadedComponent, ThreadedRuntime.prewarm, ThreadedRuntime.runHeadlessTask, registerThreadedHeadlessTask, runtimeFunction and call. A small surface is easier to track across releases, but the Metro transform is the part that can change under you without a type error, because it rewrites JSX at build time. Pin your versions and read the release notes for @react-native-runtimes/core before bumping.
The example app is your best verification target. It ships metro.config.js, babel.config.js and index.business-runtime.ts, and the root scripts run it through bun with example:android, example:ios and example:start. Running the example first tells you whether the transform and the native side are wired correctly on your machine before you touch your own app.
Editorial conclusion
Adopt it if you are already on React Native 0.76+ with the New Architecture and Hermes, and you have one or two screens that repeatedly monopolize the main JS runtime. Do not adopt it if you depend on the legacy architecture, a non-Hermes engine, or if you need to pass large mutable objects between runtimes. Before committing, verify three things on your own device: that the Metro transform rewrites your JSX into a registered threaded boundary, that ThreadedRuntime.prewarm actually removes the cold-start gap you measured, and that your shared state reads come back synchronously from the native-backed store rather than through a bridge round-trip.
Frequently asked questions
Does react-native-runtimes require the New Architecture?
Yes. The README states it adds a multi-runtime layer for React Native New Architecture apps, and lists legacy architecture and non-Hermes JS engines under when not to use it. The React Native badge in the README shows 0.76+.
Can I pass objects between runtimes in react-native-runtimes?
Arguments and return values of cross-runtime function calls are JSON-serialized automatically, so anything that cannot survive JSON will not cross. The README advises passing ids or keys and reading shared data from native-backed state instead of passing large mutable objects or non-serializable props.
What packages does react-native-runtimes publish?
Two: @react-native-runtimes/core for mounting React components in secondary runtimes, and @react-native-runtimes/state for the Zustand-style shared store backed by a process-wide C++ singleton. Both were published as 0.1.0-alpha.2 on 2026-08-05.
How do I run the react-native-runtimes example app?
The root package.json exposes example:android, example:ios and example:start, all delegating to the example workspace through bun. The engines field requires Node 22.11.0 or newer.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/margelo-react-native-runtimes)Star history chart for your README
[](https://hysenlabs.com/projects/margelo-react-native-runtimes)Was this useful?