# Migrating from v3 to v4

v4 is available on npm `latest`. This guide describes the main development line; unpublished changes are not automatically included in a release. Confirm your installed version and its release notes before upgrading.

## Choose the architecture first

| Application | Package line |
| --- | --- |
| Legacy Architecture | Keep v3: `npm install react-native-nfc-manager@3` |
| RN 0.76–0.81 with New Architecture enabled | v4; legacy mode is outside the v4 contract |
| RN 0.82 or newer | New Architecture only; check the exact-version evidence in the support policy |
| RN older than 0.76 | Outside v4 support |

The v4 minimum iOS deployment target is 15.1 and its Swift language baseline is 5.7. Use the toolchain required by your React Native version, including its Android SDK/NDK requirements. A broad peer-dependency range is not evidence that every RN minor was compiled or tested.

## Install and rebuild

Install stable v4, then lock the exact resolved version:

```sh
npm install react-native-nfc-manager
```

Run your application's CocoaPods installation on iOS, then rebuild the native application on both platforms. A Metro refresh or JavaScript-only update cannot replace the native module. Review NFC capabilities, provisioning, iOS usage-description/identifier settings, and Android permissions in the [platform setup guides](./guide/installation.md#choose-your-setup).

Expo applications require prebuild and a custom Development Build. Expo Go cannot load this native module. Follow the [Expo instructions](./guide/expo.md), rebuild after plugin changes, and use [Expo troubleshooting](./EXPO_TROUBLESHOOTING.md) for dependency, rebuild and entitlement problems. Local build verification remains separate from hosted EAS verification.

An unqualified install selects stable v4 through `latest`. Existing legacy applications can explicitly install `react-native-nfc-manager@3`.

## TypeScript result corrections

The existing native payload is not uniform across tags and platforms. Current v4 declarations include these corrections:

- `TagEvent.ndefMessage` is optional. Use `tag?.ndefMessage ?? []` or check for presence before iterating.
- `NdefRecord.id` can be an Android hexadecimal string or an iOS byte array. Narrow before byte-array operations; do not interpret the hexadecimal string as UTF-8 bytes.
- Technology-specific metadata is optional. Android cached NFC-A, NFC-V, and ISO-DEP fields do not imply a new NFC exchange, and not all have hardware evidence.

```ts
for (const record of tag?.ndefMessage ?? []) {
  if (typeof record.id === 'string') {
    console.log('Android record ID (hex)', record.id);
  } else {
    console.log('Record ID bytes', record.id);
  }
}
```

These declaration corrections can require source changes even where native payloads are unchanged. Consult [CHANGELOG](https://github.com/revtel/react-native-nfc-manager/blob/main/CHANGELOG.md) for the release containing each change; the declaration and Expo hardening changes are recorded in beta.10, and Unicode/live-read fixes in beta.11.

## Preserve the asynchronous lifecycle

Await `start()` before requesting a technology. Handle initialization/request/I/O errors, avoid overlapping requests, and await `cancelTechnologyRequest()` in cleanup before allowing the next scan. Follow the [introductory example](./guide/reading-ndef.md). Existing cancellation, error, event, and timeout contracts remain applicable; an Android tag-wait timeout is not implied by a transceive timeout.

## Verify the flows your application uses

The [support policy](./SUPPORT_POLICY.md) distinguishes API availability, compiler evidence and device evidence. Recorded basic NDEF and Android NTAG215 flows do not establish coverage for every tag. Android NFC-V and ISO-DEP over NFC-A cached metadata have [physical-device evidence](./ANDROID_TAG_METADATA_VALIDATION_2026-10-09.md). iOS ISO 15693, configured transceive timeout, and ISO-DEP over NFC-B metadata remain unverified on hardware. Exercise your application's technologies, repeated requests, cancellation, background/resume, and failure recovery on physical devices before rollout.

To stay on v3, keep the `@3` version range and rebuild the application after native dependency changes. Existing lockfiles/ranges do not automatically cross the major-version boundary when npm latest changes.