{"id":50686959,"url":"https://github.com/margelo/react-native-runtimes","last_synced_at":"2026-06-25T22:00:36.489Z","repository":{"id":360763120,"uuid":"1243782787","full_name":"margelo/react-native-runtimes","owner":"margelo","description":"Run heavy React Native components and business logic in isolated Hermes runtimes (without freezing your main JS thread)","archived":false,"fork":false,"pushed_at":"2026-06-14T20:24:42.000Z","size":3958,"stargazers_count":460,"open_issues_count":7,"forks_count":10,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-06-14T22:14:15.024Z","etag":null,"topics":["library","nitro","parallel","performance","react-native","runtimes","threading","worklets"],"latest_commit_sha":null,"homepage":"https://runtimes.margelo.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/margelo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-19T16:56:07.000Z","updated_at":"2026-06-14T20:24:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/margelo/react-native-runtimes","commit_stats":null,"previous_names":["szymon20000/react-native-runtimes","margelo/react-native-runtimes"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/margelo/react-native-runtimes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/margelo%2Freact-native-runtimes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/margelo%2Freact-native-runtimes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/margelo%2Freact-native-runtimes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/margelo%2Freact-native-runtimes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/margelo","download_url":"https://codeload.github.com/margelo/react-native-runtimes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/margelo%2Freact-native-runtimes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34793951,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["library","nitro","parallel","performance","react-native","runtimes","threading","worklets"],"created_at":"2026-06-09T00:00:24.244Z","updated_at":"2026-06-25T22:00:36.479Z","avatar_url":"https://github.com/margelo.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./assets/image.png\" width=\"1280\" alt=\"react-native-runtimes logo\" /\u003e\n\n# react-native-runtimes\n\n**Run heavy React Native UI and business logic in isolated Hermes runtimes — without freezing your main JS thread**\n\n[![React Native](https://img.shields.io/badge/React%20Native-0.76%2B-61DAFB?style=flat-square\u0026logo=react)](https://reactnative.dev)\n[![New Architecture](https://img.shields.io/badge/New%20Architecture-required-brightgreen?style=flat-square)](https://reactnative.dev/docs/the-new-architecture/landing-page)\n[![Expo](https://img.shields.io/badge/Expo-config%20plugin-000020?style=flat-square\u0026logo=expo)](https://expo.dev)\n[![Android](https://img.shields.io/badge/Android-supported-3DDC84?style=flat-square\u0026logo=android)](https://developer.android.com)\n[![iOS](https://img.shields.io/badge/iOS-supported-000000?style=flat-square\u0026logo=apple)](https://developer.apple.com)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)\n\n[📖 Docs](https://runtimes.margelo.com/) · [⚡ Quick Start](#getting-started) · [📦 Core](packages/core/README.md) · [🗂 State](packages/state/README.md)\n\n\u003c/div\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ca href=\"https://margelo.com\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./assets/margelo_light.svg\"\u003e\u003cimg src=\"./assets/margelo_dark.svg\" height=\"48\" align=\"middle\" alt=\"Margelo\" /\u003e\u003c/picture\u003e\u003c/a\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./assets/x_light.svg\"\u003e\u003cimg src=\"./assets/x_dark.svg\" height=\"18\" align=\"middle\" alt=\"✕\" /\u003e\u003c/picture\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n\u003ca href=\"https://www.callstack.com\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./assets/callstack_light.svg\"\u003e\u003cimg src=\"./assets/callstack_dark.svg\" height=\"40\" align=\"middle\" alt=\"Callstack\" /\u003e\u003c/picture\u003e\u003c/a\u003e\n\n\u003cbr/\u003e\n\n**react-native-runtimes** is built in collaboration with our friends at **[Callstack](https://www.callstack.com)**\n\n\u003csub\u003eWe love fast apps ⚡ and cars 🏎️\u003c/sub\u003e\n\n\u003c/div\u003e\n\n---\n\n## What is this?\n\nReact Native gives your product one main JavaScript runtime. When a feed, chat screen, editor, reducer, or hydration job monopolizes that runtime, input, animation, and navigation all start competing for the same VM.\n\n**react-native-runtimes** adds a multi-runtime layer for React Native New Architecture apps:\n\n- mount selected React components in named secondary Hermes runtimes\n- run whole screens, headless tasks, and typed functions away from the main runtime\n- share state across isolated JS heaps through a native C++ singleton\n- prewarm runtimes before navigation so expensive surfaces are ready when users arrive\n- wire it through Metro and, for Expo, a config plugin instead of hand-written runtime plumbing\n\n```tsx\n// That's it. This component now renders in its own Hermes instance.\n\u003cOnRuntime name=\"chat-runtime\"\u003e\n  \u003cMessageList conversationId={conversationId} /\u003e\n\u003c/OnRuntime\u003e\n```\n\n---\n\n## What it unlocks\n\n| If your app has... | You can move... | Main runtime keeps... |\n|---|---|---|\n| A chat, feed, or inbox that janks on mount | The expensive list or route surface | Navigation, gestures, and input |\n| Reducers or stores competing with animation | Business logic in a long-lived runtime | Frame-critical UI work |\n| Slow first-open screens | A prewarmed runtime before the user taps | Predictable navigation latency |\n| Background hydration or decoding | Headless tasks on a worker runtime | Responsive startup and render |\n| State that must be visible everywhere | Native-backed shared stores | Synchronous reads without bridge round-trips |\n\n---\n\n## When to reach for it\n\n- You have one or two expensive features that repeatedly monopolize the main JS runtime.\n- You want a chat, feed, editor, map sidebar, or media-heavy route to stay alive and warm.\n- You need business logic or cache hydration to run without blocking interaction.\n- You are already on React Native New Architecture with Hermes, or you are willing to move there.\n\n## When not to use it\n\n- Your app is simple enough that memoization, virtualization, or moving work off render fixes the issue.\n- You need legacy architecture or a non-Hermes JS engine.\n- You want to pass large mutable objects or non-serializable props directly between runtimes. Pass ids/keys and read shared data from native-backed state instead.\n\n---\n\n## Packages\n\n| Package | Description |\n|---|---|\n| [`@react-native-runtimes/core`](packages/core/README.md) | Mount React components in secondary runtimes. Metro transform, `OnRuntime`, `ThreadedScreen`, headless tasks, cross-runtime function calls. |\n| [`@react-native-runtimes/state`](packages/state/README.md) | Zustand-style shared store backed by a process-wide C++ singleton. Synchronous reads and commits from every runtime. |\n\n---\n\n## Core capabilities\n\n### 🧵 Zero-boilerplate threaded components\n\nWrap a component in `OnRuntime` — Metro rewrites the JSX to a registered threaded boundary at build time. No manual registration required.\n\n```tsx\nimport { OnRuntime } from '@react-native-runtimes/core';\n\n\u003cOnRuntime name=\"feed-runtime\"\u003e\n  \u003cHeavyFeedList userId={userId} /\u003e\n\u003c/OnRuntime\u003e\n```\n\n### 📱 Full-screen threaded routes\n\nFor navigation flows that should live entirely on a secondary runtime:\n\n```tsx\nimport { ThreadedScreen, threadedComponent } from '@react-native-runtimes/core';\n\nexport const ConversationScreen = threadedComponent\u003cProps\u003e(\n  'ConversationScreen',\n  (props) =\u003e \u003cConversationRoute {...props} /\u003e,\n);\n\n// In your navigator:\n\u003cThreadedScreen\n  component={ConversationScreen}\n  props={{ conversationId }}\n  runtimeName={`chat-${conversationId}`}\n/\u003e\n```\n\n### ⚡ Runtime prewarming\n\nStart the runtime before the user navigates so there is no cold-start lag:\n\n```tsx\nimport { ThreadedRuntime } from '@react-native-runtimes/core';\n\n// e.g. when the inbox row becomes visible\nawait ThreadedRuntime.prewarm(`chat-${conversationId}`);\n```\n\n### 🏃 Headless tasks\n\nRun JS on a named runtime without mounting a view — perfect for pre-hydrating stores, decoding data, or running reducers in a long-lived worker:\n\n```tsx\n// Register on the threaded bundle side:\nregisterThreadedHeadlessTask('hydrateConversation', async ({ payload }) =\u003e {\n  const messages = await loadMessages(payload.conversationId, payload.limit);\n  await messagesStore.setSubtreeState(payload.conversationId, messages, true);\n});\n\n// Dispatch from anywhere:\nawait ThreadedRuntime.runHeadlessTask('hydrateConversation', {\n  runtimeName: 'chat-worker-runtime',\n  payload: { conversationId, limit: 50 },\n});\n```\n\n### 🔀 Cross-runtime function calls\n\nCall a typed function on a specific runtime and await the result — arguments and return values are JSON-serialized automatically:\n\n```tsx\nimport { call, runtimeFunction } from '@react-native-runtimes/core';\n\nexport const fibonacci = runtimeFunction((n: number) =\u003e ({\n  input: n,\n  result: fibonacciNumber(n),\n  computedAt: new Date().toISOString(),\n}));\n\n// Call it on a named runtime from the main runtime:\nconst result = await call(fibonacci).on('fibonacci-worker-runtime')(38);\n```\n\nOr use a function directive for fixed-runtime helpers — Metro rewrites the call site automatically:\n\n```tsx\nasync function refreshCache(key: string) {\n  'background'; // ← directive: this function always runs on 'background' runtime\n  await cacheStore.hydrate();\n  return cacheStore.get(key);\n}\n\nconst value = await refreshCache('settings'); // cross-runtime, no extra API\n```\n\n### 🗂 Shared state — synchronous, cross-heap\n\nA Zustand-style API backed by a native C++ process-wide singleton. Reads are synchronous. No bridge round-trip. Any runtime can write and every subscriber is notified.\n\n```tsx\nimport { createSharedStore } from '@react-native-runtimes/state';\n\nexport const chatStore = createSharedStore({\n  name: 'chat',\n  initialState: { messages: {}, settings: { theme: 'dark' } },\n});\n\n// Path handles for fine-grained subscriptions:\nconst roomMessages = chatStore.path\u003cMessage[]\u003e(['messages', 'release-room']);\n\nawait roomMessages.update(items =\u003e [...(items ?? []), newMessage]);\n\n// Subscribe with a selector — works in any runtime:\nconst count = roomMessages.use(items =\u003e items?.length ?? 0);\n```\n\nAdd native persistence with a single option:\n\n```tsx\nexport const preferencesStore = createSharedStore({\n  name: 'preferences',\n  initialState: { counter: { count: 0 } },\n  persist: { key: 'preferences', version: 1, subtrees: ['counter'] },\n});\n```\n\n### 🏗 Business runtimes\n\nFor an app-lifetime runtime that sees the same native modules as the main runtime, use `prewarmBusinessRuntime`:\n\n```kotlin\nThreadedRuntime.setMainReactPackagesProvider { PackageList(this).packages }\nThreadedRuntime.prewarmBusinessRuntime(applicationContext, \"business-runtime\")\n```\n\n```tsx\nif (global.__THREADED_RUNTIME_ENV__?.kind === 'business-runtime') {\n  require('./src/businessRuntimeEntry');\n}\n```\n\n### 🔌 Expo support\n\n`@react-native-runtimes/core` ships a config plugin. No manual native edits needed:\n\n```ts\n// app.config.ts\nexport default {\n  newArchEnabled: true,\n  plugins: [\n    ['@react-native-runtimes/core', {\n      packages: ['@react-native-runtimes/state'],\n    }],\n  ],\n};\n```\n\n---\n\n## Getting Started\n\n### 1. Install\n\n```sh\nnpm install @react-native-runtimes/core @react-native-runtimes/state react-native-nitro-modules\n```\n\n### 2. Configure Metro\n\n```js\n// metro.config.js\nconst { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');\nconst { withThreadedRuntime } = require('@react-native-runtimes/core/metro');\n\nmodule.exports = withThreadedRuntime(\n  mergeConfig(getDefaultConfig(__dirname), {}),\n  { roots: ['App.tsx', 'src'], generatedDir: '.threaded-runtime' },\n);\n```\n\n### 3. Load the generated entry\n\n```js\n// index.js\nif (global.__THREADED_RUNTIME_ENV__) {\n  require('./.threaded-runtime/entry');\n} else {\n  require('./App');\n}\n```\n\n### 4. Render\n\n```tsx\nimport { OnRuntime } from '@react-native-runtimes/core';\n\nexport default function App() {\n  return (\n    \u003cOnRuntime name=\"my-runtime\"\u003e\n      \u003cHeavyComponent /\u003e\n    \u003c/OnRuntime\u003e\n  );\n}\n```\n\n→ Full setup guide: [packages/core/README.md](packages/core/README.md)\n\n---\n\n## Requirements\n\n| Requirement | Support |\n|---|---|\n| React Native | **0.76+** |\n| Architecture | New Architecture required |\n| JavaScript engine | Hermes |\n| Platforms | Android and iOS |\n| Expo | Config plugin included in `@react-native-runtimes/core` |\n\n---\n\n## Documentation\n\n- 📖 [Hosted docs](https://runtimes.margelo.com/)\n- 📦 [Core package — full API reference](packages/core/README.md)\n- 🗂 [State package — shared store API](packages/state/README.md)\n- 🧪 [Example app](example)\n- 🏗 [Docusaurus source](website/docs/intro.md)\n- 🤝 [Contributing guide](CONTRIBUTING.md)\n\n---\n\n## Authors\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://github.com/Szymon20000\"\u003e\n        \u003cimg src=\"https://github.com/Szymon20000.png\" width=\"32\" /\u003e\u003cbr/\u003e\n        \u003csub\u003e\u003cb\u003eSzymon Kapała\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\u003cbr/\u003e\n      \u003ca href=\"https://x.com/Turbo_Szymon\"\u003e@Turbo_Szymon\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://github.com/v3ron\"\u003e\n        \u003cimg src=\"https://github.com/v3ron.png\" width=\"32\" /\u003e\u003cbr/\u003e\n        \u003csub\u003e\u003cb\u003eSzymon Chmal\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\u003cbr/\u003e\n      \u003ca href=\"https://x.com/ChmalSzymon\"\u003e@ChmalSzymon\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://github.com/pioner92\"\u003e\n        \u003cimg src=\"https://github.com/pioner92.png\" width=\"32\" /\u003e\u003cbr/\u003e\n        \u003csub\u003e\u003cb\u003eAlex Shumihin\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\u003cbr/\u003e\n      \u003ca href=\"https://x.com/pioner_dev\"\u003e@pioner_dev\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://github.com/riteshshukla04\"\u003e\n        \u003cimg src=\"https://github.com/riteshshukla04.png\" width=\"32\" /\u003e\u003cbr/\u003e\n        \u003csub\u003e\u003cb\u003eRitesh Shukla\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\u003cbr/\u003e\n      \u003ca href=\"https://x.com/RiteshRk14\"\u003e@RiteshRk14\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nMIT License · Built with ❤️ for the React Native community\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmargelo%2Freact-native-runtimes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmargelo%2Freact-native-runtimes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmargelo%2Freact-native-runtimes/lists"}