# Opt-in iOS compatibility patch for Nitro 0.37.1

This patch carries the four-header fix from
[Nitro PR #1575](https://github.com/margelo/nitro/pull/1575), pinned to its fix
commit `68479ed8e502f201da35e16a69c7b1f1cd27f305` (PR head `a9dbfb4053c1bac9edbcafac8aaf9b6480682115`).
The upstream PR was open on 2026-10-16. See [issue #1573](https://github.com/margelo/nitro/issues/1573).
The backport retains Nitro's [MIT license and copyright notice](LICENSE.nitro).

Nitro 0.37.1 exposes React renderer headers to its Swift-facing Clang module.
With the glog modulemap in RN 0.78–0.83, Swift compilation then fails with
`import of module 'glog.glog.log_severity' appears within namespace 'google'`.
The fix hides three C++ view headers while compiling the NitroModules module;
ordinary C++ includes retain their contents. Timer code, generated bindings,
Nitro's version and the public timer API are unchanged.

This is an explicit app-side workaround for **exactly Nitro 0.37.1**. It is
not applied by installing this library. Pin that version when using this patch;
do not apply it to another Nitro release or downgrade Nitro under bindings
generated by a newer Nitrogen. The RN 0.84–0.88 matrix rows pass without this fix.

The patch ships in **version 0.5.0**, not the published 0.4.0 package.
Install 0.5.0 or a local tarball using the [installation instructions](../README.md#installation).

## npm / patch-package

Run in the application's root after installing this library. If the app already
patches Nitro 0.37.1, merge this fix into its existing patch before proceeding;
do not overwrite that patch.

```sh
npm install --save-exact react-native-nitro-modules@0.37.1
npm install --save-dev --save-exact patch-package@8.0.1
mkdir -p patches
cp node_modules/react-native-nitro-bg-timer-plus/compat/react-native-nitro-modules+0.37.1.patch patches/
npx --no-install patch-package --error-on-fail
```

Add `patch-package --error-on-fail` to the
app's `postinstall` script, preserving any existing commands, and commit the
patch, manifest and lockfile. For example, an app without an existing hook uses:

```json
{
  "scripts": {
    "postinstall": "patch-package --error-on-fail"
  }
}
```

Native-build CI must install the dev dependencies containing patch-package and
copy/restore `patches/` before installation. Keep the patch in the cache key if
caching node_modules. Reinstall Pods and rebuild the app after applying it.

## Yarn 4

Use Yarn's [dependency patching](https://yarnpkg.com/features/patching) rather
than the npm postinstall hook:

```sh
yarn add --exact react-native-nitro-modules@0.37.1
yarn patch react-native-nitro-modules@npm:0.37.1
# Yarn prints an editable directory. Substitute its path below, and use an
# absolute path to this library's supplied .patch file:
git -C /path/printed/by/yarn apply -p3 /absolute/path/to/react-native-nitro-modules+0.37.1.patch
yarn patch-commit -s /path/printed/by/yarn
yarn install
```

`-p3` removes the patch-package `a/node_modules/react-native-nitro-modules/`
prefix so the patch applies to the extracted Nitro package. Commit the generated
`.yarn/patches/` file, manifest changes and `yarn.lock`; CI can then use
`yarn install --immutable`. Reinstall Pods and rebuild after applying the patch.
The Yarn 4 persistence flow was checked separately; native qualification used npm.

For pnpm, use its official [`patch`](https://pnpm.io/cli/patch) and
[`patch-commit`](https://pnpm.io/cli/patch-commit) workflow. A pnpm native build
was not part of this qualification.

## Reproduce the compatibility run

From a library checkout (the matrix runner is a contributor tool):

```sh
RN_CLI_VERSION=20.2.0 scripts/compat-matrix.sh --platform ios --run --nitro-ios-compat 0.78.3 0.83.10
```

The flag requires installed Nitro 0.37.1 and applies the patch from the installed
library tarball with patch-package 8.0.1 before Pods. It does not change peer
constraints or apply the patch to Android. Without the flag the runner tests
unmodified Nitro, retaining the original failing configuration.