feat: re-export shared JavaScript APIs from nitro-core

Author: mrousavy

.github/workflows/lint-typescript.yml

@@ -11,6 +11,8 @@ on:
       - 'packages/react-native-nitro-modules/nitro'
       - '.gitmodules'
       - 'scripts/sync-core.mjs'
+      - 'scripts/update-core-version.mjs'
+      - 'bun.lock'
       - '.github/workflows/lint-typescript.yml'
       - 'config'
       - '**/*.ts'
@@ -25,6 +27,8 @@ on:
       - 'packages/react-native-nitro-modules/nitro'
       - '.gitmodules'
       - 'scripts/sync-core.mjs'
+      - 'scripts/update-core-version.mjs'
+      - 'bun.lock'
       - '.github/workflows/lint-typescript.yml'
       - 'config'
       - '**/*.ts'
@@ -48,6 +52,9 @@ jobs:
       - name: Install npm dependencies (bun)
         run: bun install
 
+      - name: Test nitro-core
+        run: bun nitro-core test
+
       - name: Run TypeScript (tsc)
         run: bun typecheck
 
@@ -66,6 +73,9 @@ jobs:
       - name: Run ESLint CI in apps/example/
         working-directory: apps/example
         run: bun lint-ci
+      - name: Run ESLint CI in nitro-core
+        working-directory: packages/react-native-nitro-modules/nitro/packages/nitro-core
+        run: bun lint-ci
       - name: Run ESLint CI in packages/react-native-nitro-modules/nitro/packages/nitrogen
         working-directory: packages/react-native-nitro-modules/nitro/packages/nitrogen
         run: bun lint-ci
@@ -82,6 +92,9 @@ jobs:
       - name: Run ESLint with auto-fix in apps/example/
         working-directory: apps/example
         run: bun lint
+      - name: Run ESLint with auto-fix in nitro-core
+        working-directory: packages/react-native-nitro-modules/nitro/packages/nitro-core
+        run: bun lint
       - name: Run ESLint with auto-fix in packages/react-native-nitro-modules/nitro/packages/nitrogen
         working-directory: packages/react-native-nitro-modules/nitro/packages/nitrogen
         run: bun lint

.gitignore

@@ -93,9 +93,8 @@ apps/*/.harness/
 # Claude Code local settings
 .claude/settings.local.json
 
-# Shared implementation staged by bun sync-core. Edit packages/react-native-nitro-modules/nitro/ instead.
+# Native implementation staged by bun sync-core. Edit packages/react-native-nitro-modules/nitro/ instead.
 /packages/react-native-nitro-modules/cpp/
 /packages/react-native-nitro-modules/ios/
 /packages/react-native-nitro-modules/android/src/
-/packages/react-native-nitro-modules/src/
 /packages/react-native-nitro-modules/LICENSE

CONTRIBUTING.md

@@ -23,8 +23,9 @@ Either is welcome. A clean, deterministic repro is often more valuable than a gu
 The React Native repository is a Bun monorepo with a pinned `packages/react-native-nitro-modules/nitro/` submodule from [margelo/nitro](https://github.com/margelo/nitro):
 
 - [apps/example/](apps/example) — React Native example app that hosts the runtime test harness.
+- [packages/react-native-nitro-modules/nitro/packages/nitro-core/](https://github.com/margelo/nitro/tree/core-split/packages/nitro-core) - shared JS/TS definitions and runtime helpers, published from `nitro`.
 - [packages/react-native-nitro-modules/nitro/packages/nitrogen/](https://github.com/margelo/nitro/tree/core-split/packages/nitrogen) - the `nitrogen` code generator, maintained in `nitro`.
-- [packages/react-native-nitro-modules/](packages/react-native-nitro-modules) - the published React Native package and its CocoaPods, Gradle, and CMake configuration. Its implementation is staged from `packages/react-native-nitro-modules/nitro/packages/react-native-nitro-modules/`.
+- [packages/react-native-nitro-modules/](packages/react-native-nitro-modules) - the published React Native package and its CocoaPods, Gradle, and CMake configuration. Its native sources are staged from `packages/react-native-nitro-modules/nitro/packages/react-native-nitro-modules/`; its RN-specific JS is maintained here. Shared JS/TS comes from `nitro-core`.
 - [packages/react-native-nitro-test/](packages/react-native-nitro-test) — a Nitro module full of specs used as compile-time and runtime tests.
 - [packages/react-native-nitro-test-external/](packages/react-native-nitro-test-external) — a second Nitro module used to cover cross-module behavior.
 - [packages/template/](packages/template) - the `npx nitrogen init` React Native library template. It stays here with the CocoaPods/Gradle/CMake integration and React Native dependencies it configures.
@@ -40,7 +41,7 @@ We use **Bun** as the package manager and task runner. Don't use `npm`, `yarn`,
 bun bootstrap       # initialize the pinned core submodule, install, and build
 bun bootstrap:ios   # also install Bundler dependencies and example app Pods
 bun sync-core       # refresh staged implementation sources
-bun run build       # stage sources and build nitro, nitrogen, and the test modules
+bun run build       # stage native sources and build core, RN, Nitrogen, and tests
 bun specs           # regenerate nitrogen output for react-native-nitro-test
 bun lint-all        # run all linters (JS/TS, C++, Swift, Kotlin)
 ```
@@ -49,7 +50,7 @@ bun lint-all        # run all linters (JS/TS, C++, Swift, Kotlin)
 
 The `packages/react-native-nitro-modules/nitro/` gitlink records the exact Nitro commit used by this repository. This repository develops on `main`; the submodule's development branch in `nitro` is `core-split`. Ordinary builds and `git submodule update --init --recursive` use the recorded commit. Do not use `git submodule update --remote` in builds.
 
-Edit the runtime implementation in `packages/react-native-nitro-modules/nitro/packages/react-native-nitro-modules/`. The wrapper's `cpp/`, `ios/`, `android/src/`, and `src/` directories are generated by `bun sync-core` and ignored by Git. The staging command owns only those directories and the additional shared files listed in `scripts/sync-core.mjs`. Keep handwritten package and build configuration outside them. Nitrogen is used directly from `packages/react-native-nitro-modules/nitro/packages/nitrogen/` and is not copied into the wrapper.
+Edit native sources in `packages/react-native-nitro-modules/nitro/packages/react-native-nitro-modules/` and shared JS/TS in `packages/react-native-nitro-modules/nitro/packages/nitro-core/`. The wrapper's `cpp/`, `ios/`, and `android/src/` directories are generated by `bun sync-core` and ignored by Git. The wrapper maintains `src/` for RN bootstrap, views, worklets, and shared API re-exports. The staging command owns only those directories and the additional shared files listed in `scripts/sync-core.mjs`. Keep handwritten package and build configuration outside them. Nitrogen is used directly from `packages/react-native-nitro-modules/nitro/packages/nitrogen/` and is not copied into the wrapper.
 
 To update the pinned core:
 
@@ -59,11 +60,11 @@ To update the pinned core:
 4. If the core version changed, run `bun update-core-version`. Run `bun install`, `bun specs`, and the relevant native checks, then commit the core pin, version/lockfile changes, and any intended generated test bindings here. Push the wrapper commit after the core commit is available remotely.
 5. On another checkout, run `git submodule update --init --recursive` followed by `bun install` after pulling the wrapper commit.
 
-Prepare version changes in the standalone `nitro` repository with `bun version:set VERSION`. This updates the shared runtime, Nitrogen, its runtime dependency, and native `NITRO_VERSION`. Build Nitrogen and refresh the core lockfile before committing. Publish `nitrogen` through the `nitro` release workflow, then use the final pushed core commit when updating the wrapper as described above. Nitrogen's existing semver dependency on `react-native-nitro-modules` still applies, so coordinate matching package versions in both repositories.
+Prepare version changes in the standalone `nitro` repository with `bun version:set VERSION`. This updates `nitro-core`, Nitrogen, its core dependency, the native source manifest, and embedded JS/native versions. Build Nitrogen and refresh the core lockfile before committing. Publish `nitro-core` followed by `nitrogen` from the `nitro` repository, then use the final pushed core commit when updating the wrapper as described above. Nitrogen depends on `nitro-core` with a compatible semver range. The RN package depends on the exact core version to match its native runtime. All three packages use the coordinated release version.
 
-`bun update-core-version` copies the authoritative version into the wrapper and test packages. Inspect real `npm pack` tarballs from both package directories and run the native consumer checks before publishing. In this repository, `bun release` checks the existing version and publishes only `react-native-nitro-modules` through `npm publish`; it does not bump versions with release-it.
+`bun update-core-version` copies the authoritative version into the wrapper and test packages. Inspect real `npm pack` tarballs for `nitro-core`, `nitrogen`, and the RN package and run the native consumer checks before publishing. In this repository, `bun release` checks the existing version and publishes only `react-native-nitro-modules` through `npm publish`; it does not bump versions with release-it.
 
-The runtime tarball includes staged implementation files and needs no core checkout or Git access when installed from npm.
+The RN tarball includes staged native files and its own JS integration. Shared JS is installed through its `nitro-core` dependency. Neither package needs a core checkout or Git access when installed from npm.
 
 ## You don't need to ship a fix — a clean repro is enough
 

apps/benchmark/metro.config.js

@@ -15,8 +15,12 @@ const corePath = path
 const config = {
   watchFolders: [root],
   resolver: {
-    // Metro reads the staged package, so exclude the second source tree.
-    blockList: [new RegExp(`^${corePath}[/\\\\].*`)],
+    // Native sources are staged in the RN package. Only nitro-core is a JS workspace.
+    blockList: [
+      new RegExp(
+        `^${corePath}[/\\\\](?!packages(?:[/\\\\]nitro-core(?:[/\\\\]|$)|$)).*`
+      ),
+    ],
   },
 }
 

apps/example/__tests__/nitro.harness.ts

@@ -1,5 +1,13 @@
-import { describe, it } from 'react-native-harness'
-import { NitroModules } from 'react-native-nitro-modules'
+import { describe, expect, it } from 'react-native-harness'
+import {
+  getHybridObjectConstructor,
+  NitroModules,
+} from 'react-native-nitro-modules'
+import {
+  getHybridObjectConstructor as getCoreHybridObjectConstructor,
+  getInstalledNitro,
+  NitroModules as CoreNitroModules,
+} from 'nitro-core'
 import type {
   TestObjectCpp,
   TestObjectSwiftKotlin,
@@ -30,5 +38,13 @@ const testObjectSwiftKotlin =
     'TestObjectSwiftKotlin'
   )
 
+describe('nitro-core integration', () => {
+  it('shares the installed native proxy and constructor helper with React Native', () => {
+    expect(getInstalledNitro()).toBe(NitroModules)
+    expect(CoreNitroModules).toBe(NitroModules)
+    expect(getCoreHybridObjectConstructor).toBe(getHybridObjectConstructor)
+  })
+})
+
 describe('TestObject (C++)', createTestRunner(testObjectCpp))
 describe('TestObject (Swift/Kotlin)', createTestRunner(testObjectSwiftKotlin))

apps/example/metro.config.js

@@ -20,8 +20,12 @@ const config = {
   // We need to make sure that only one version is loaded for peerDependencies
   // So we block them at the root, and alias them to the versions in example's node_modules
   resolver: {
-    // Metro reads the staged package, so exclude the second source tree.
-    blockList: [new RegExp(`^${corePath}[/\\\\].*`)],
+    // Native sources are staged in the RN package. Only nitro-core is a JS workspace.
+    blockList: [
+      new RegExp(
+        `^${corePath}[/\\\\](?!packages(?:[/\\\\]nitro-core(?:[/\\\\]|$)|$)).*`
+      ),
+    ],
     extraNodeModules: modules.reduce((acc, name) => {
       acc[name] = path.join(__dirname, 'node_modules', name)
       return acc

apps/example/package.json

@@ -29,7 +29,8 @@
     "react-native-nitro-test-external": "*",
     "react-native-nitro-modules": "*",
     "react-native-safe-area-context": "^5.8.0",
-    "react-native-screens": "^4.25.2"
+    "react-native-screens": "^4.25.2",
+    "nitro-core": "0.37.1"
   },
   "devDependencies": {
     "@babel/core": "^7.29.7",

bun.lock

@@ -9,6 +9,7 @@
   "author": "Marc Rousavy <me@mrousavy.com> (https://github.com/mrousavy)",
   "workspaces": [
     "packages/react-native-nitro-modules",
+    "packages/react-native-nitro-modules/nitro/packages/nitro-core",
     "packages/react-native-nitro-modules/nitro/packages/nitrogen",
     "packages/react-native-nitro-test",
     "packages/react-native-nitro-test-external",
@@ -20,7 +21,7 @@
     "build": "bun sync-core && bun nitro build && bun nitrogen build && bun nitro-test-external build && bun nitro-test build",
     "bootstrap": "git submodule update --init --recursive && bun install",
     "typecheck": "bun --filter=\"**\" typecheck",
-    "lint": "bun nitro lint && bun nitrogen lint && bun nitro-test lint && bun example lint",
+    "lint": "bun nitro-core lint && bun nitro lint && bun nitrogen lint && bun nitro-test lint && bun example lint",
     "lint-cpp": "./scripts/clang-format.sh",
     "lint-swift": "./scripts/swift-format.sh",
     "lint-kotlin": "./scripts/kotlin-format.sh",
@@ -39,7 +40,8 @@
     "benchmark": "bun --cwd apps/benchmark",
     "sync-core": "node scripts/sync-core.mjs",
     "bootstrap:ios": "bun bootstrap && bun example bundle-install && bun example pods",
-    "update-core-version": "node scripts/update-core-version.mjs"
+    "update-core-version": "node scripts/update-core-version.mjs",
+    "nitro-core": "bun --cwd packages/react-native-nitro-modules/nitro/packages/nitro-core"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.5",

package.json

@@ -22,6 +22,8 @@ npm i react-native-nitro-modules
 cd ios && pod install
 ```
 
+The package re-exports the shared `nitro-core` API and installs it into the React Native runtime. Existing imports from `react-native-nitro-modules` remain supported.
+
 ### Inside a nitro module library
 
 If you are building a nitro module yourself, add [react-native-nitro-modules](https://npmjs.org/react-native-nitro-modules) as a `peerDependency` into your library's `package.json`:
@@ -212,7 +214,7 @@ The following C++ / JS types are supported out of the box:
     <td><code><a href="https://github.com/margelo/nitro/blob/core-split/packages/react-native-nitro-modules/android/src/main/java/com/margelo/nitro/core/Promise.kt">Promise&lt;T&gt;</a></code></td>
   </tr>
   <tr>
-    <td><code><a href="https://github.com/margelo/nitro/blob/core-split/packages/react-native-nitro-modules/src/AnyMap.ts">AnyMap</a></code></td>
+    <td><code><a href="https://github.com/margelo/nitro/blob/core-split/packages/nitro-core/src/AnyMap.ts">AnyMap</a></code></td>
     <td><code>std::shared_ptr&lt;<a href="https://github.com/margelo/nitro/blob/core-split/packages/react-native-nitro-modules/cpp/core/AnyMap.hpp">AnyMap</a>&gt;</code></td>
     <td><code><a href="https://github.com/margelo/nitro/blob/core-split/packages/react-native-nitro-modules/ios/core/AnyMap.swift">AnyMap</a></code></td>
     <td><code><a href="https://github.com/margelo/nitro/blob/core-split/packages/react-native-nitro-modules/android/src/main/java/com/margelo/nitro/core/AnyMap.kt">AnyMap</a></code></td>
@@ -230,7 +232,7 @@ The following C++ / JS types are supported out of the box:
     <td><code>java.time.Instant</code></td>
   </tr>
   <tr>
-    <td>..any <code><a href="https://github.com/margelo/nitro/blob/core-split/packages/react-native-nitro-modules/src/HybridObject.ts">HybridObject</a></code></td>
+    <td>..any <code><a href="https://github.com/margelo/nitro/blob/core-split/packages/nitro-core/src/HybridObject.ts">HybridObject</a></code></td>
     <td><code>std::shared_ptr&lt;<a href="https://github.com/margelo/nitro/blob/core-split/packages/react-native-nitro-modules/cpp/core/HybridObject.hpp">HybridObject</a>&gt;</code></td>
     <td><code><a href="https://github.com/margelo/nitro/blob/core-split/packages/react-native-nitro-modules/ios/core/HybridObject.swift">HybridObject</a></code></td>
     <td><code><a href="https://github.com/margelo/nitro/blob/core-split/packages/react-native-nitro-modules/android/src/main/java/com/margelo/nitro/core/HybridObject.kt">HybridObject</a></code></td>