react-native-cli

<!-- GENERATED from docs/playbooks/integration/react-native-cli.md by scripts/build-agent-skill.mjs. Do not edit. -->

Integration — React Native CLI (bare workflow)

> Persona 2 sub-playbook. The user's project is a bare React Native app (`react-native` in deps, no `expo`). Detection: `react-native` + `metro.config.js` + (`android/` and/or `ios/`) directories.

Goal

Add crossbind to a React Native CLI app so:

• Native C++ compiles to a `.so` (Android) and `.a` / xcframework (iOS) and links into the app bundle.
• JS side calls into C++ via the Embind/JSI bridge.
• Metro bundler picks up the crossbind loader for the JS side.

When to use

• `react-native` in deps; **no** `expo`/`@expo/cli` in deps.
• React Native 0.81 or newer: the bindings keep the JS functions passed as C callbacks in JSI runtime data, which React Native added in 0.81.
• `metro.config.js` at root.
• `android/` and/or `ios/` native project directories present.
• Expo users → see `docs/playbooks/integration/react-native-expo.md`.

Files involved

| File | Role | |------|------| | `package.json` | + `@crossbind/plugin-react-native`, `@crossbind/plugin-react-native-ios-helper` (dependencies, autolinked), `@crossbind/plugin-metro` (devDependency), optional `@crossbind/port-<name>` | | `metro.config.js` | Wrap `getDefaultConfig` output with `CrossbindMetroPlugin(...)` | | `crossbind.config.{js,mjs}` *(new at project root)* | Project-level crossbind config: deps to consume, paths | | `src/native/` *(if user wraps own C++)* | `.h` + `.cpp` source files | | `android/app/build.gradle` | Auto-wired by `@crossbind/plugin-react-native`'s native CMake hook (no manual edits) | | `ios/Podfile.lock` | Updated by `pod install` after adding the plugin | | `ios/<App>.xcodeproj` | Native iOS link picks up the auto-generated podspec |

Commands

pnpm add @crossbind/plugin-react-native@beta @crossbind/plugin-react-native-ios-helper@beta
pnpm add -D @crossbind/plugin-metro@beta     # bundling only; the RN plugin brings the toolchain
pnpm add @crossbind/port-<name>@beta     # optional

# iOS — install pods (regenerates Podfile.lock + xcframeworks)
cd ios && pod install && cd ..

# Run on Android
pnpm android      # or: pnpm react-native run-android
# Run on iOS
pnpm ios          # or: pnpm react-native run-ios

`pod install` runs build hooks from `react-native-crossbind.podspec` that compile the iOS native libraries. `pnpm android` triggers Gradle's externalNativeBuild, which calls `script/CMakeLists.txt` from `@crossbind/plugin-react-native` and shells out to `crossbind build -p android`.

Reference config

Mirror `examples/mobile-reactnative-cli/`.

`metro.config.js` (canonical):

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const CrossbindMetroPlugin = require('@crossbind/plugin-metro');

const defaultConfig = getDefaultConfig(__dirname);

const config = {
    ...CrossbindMetroPlugin(defaultConfig),
};

module.exports = mergeConfig(defaultConfig, config);

`crossbind.config.{js,mjs}` at project root:

import Matrix from '@crossbind/example-lib-prebuilt-matrix/crossbind.config.js';
// or any other prebuilt, one variant per platform:
// import gdalAndroid from '@crossbind/port-gdal-android/crossbind.config.js';
// import gdalIos from '@crossbind/port-gdal-ios/crossbind.config.js';

export default {
    dependencies: [
        Matrix,
        // Gdal,
    ],
    paths: {
        config: import.meta.url,
    },
};

`.mjs` is preferred (ESM) so the `import.meta.url` reference works; `.js` is fine too if `package.json` declares `"type": "module"`.

CI bridge cache (optional, advanced)

The `examples/mobile-reactnative-cli` example keeps a snapshot of generated bridge files at `ci/crossbind-snapshot/` — the iOS workflow restores it before `pod install` to skip the SWIG bridge generation step in CI. This is **not** required for normal development, only for fast CI builds. Pattern:

my-app/
└── ci/
    └── crossbind-snapshot/        ← snapshot of .crossbind/build/{bridge,interface} + cache.json
        └── build/
            ├── bridge/
            │   ├── native.i.cpp
            │   └── native.i.cpp.exports.json
            ├── interface/
            │   └── native.i
            └── ...

In CI, before pod install:

mkdir -p .crossbind
cp -r ci/crossbind-snapshot/. .crossbind/

Don't name the snapshot dir `.crossbind` — `clear:cache:examples`-style globs may pick it up and delete it. Use a different name (`crossbind-snapshot`, `bridge-cache`, etc.).

Multithread → COOP/COEP

**Not applicable.** React Native runs JS on JSC/Hermes, not in a browser, so there's no SharedArrayBuffer / COOP/COEP gate. Multithread (`runtime: 'mt'`) on RN uses pthreads via JSI directly. No header config needed for RN apps.

Validation

• [ ] `pnpm install` succeeds.
• [ ] `cd ios && pod install` succeeds, `Podfile.lock` updated, `*.xcframework` directories appear under `ios/Pods/` or vendored locations.
• [ ] `pnpm android` builds the APK and launches; the app calls into C++ without "library not loaded" errors.
• [ ] `pnpm ios` builds and launches in the iOS simulator (arm64 macOS) or on-device.
• [ ] JSI bridge: `import { initNative } from './native/native.h'; await initNative(); Module.fn(...)` returns expected result.
• [ ] If wrapping own C++: editing `src/native/native.cpp` + restarting Metro picks up the change (or at least re-run `pod install` / `pnpm android` to recompile).

Common pitfalls

• **Mixing Expo and bare RN.** If `expo` is in deps, this playbook doesn't apply — switch to `react-native-expo.md`.
• **React Native older than 0.81.** The generated bridges stop compiling with errors about `facebook::jsi::UUID` or `getRuntimeData`; upgrade React Native.
• **Skipping `pod install`** after adding the plugin. iOS will fail to find the xcframeworks at link time.
• **Deleting `ci/.crossbind` directly with the older `find`-based clear scripts.** Us