Expo integration and troubleshooting

This guide describes v4. Install react-native-nfc-manager for stable v4, and lock the resolved version. Use the Expo setup and migration guide.

What is supported and tested

Expo prebuild plus a custom native Development Build is the supported integration path. Expo Go cannot load this module. The representative consumer is Expo 57.0.25 / RN 0.86.3 / New Architecture; this does not certify every Expo SDK.

The September 29 validation record covers a packed beta.9 candidate: prebuild/configuration, dependency provenance, Expo Doctor with the documented Directory exception, Android/iOS application builds, and basic iPhone/Android NFC flows. The earlier smoke record has broader event, timeout, and background/resume results on Expo 57.0.21. Preserve those original versions when referring to the results. Current published v4 is beta.11; the full Expo gate was not repeated on that artifact.

Hosted EAS Build and App Store submission remain unverified by maintainers. Local builds do not establish those outcomes. See the support policy for hardware gaps.

Rebuild the native app

A missing native module, including NativeNfcManager being null, commonly means the app is Expo Go or a native binary built before installing/configuring the library. Confirm which app is running, then build and install a Development Build. Historical examples: #501, #519.

For projects whose native directories are generated by Expo, after native dependency or config changes:

npx expo install expo-dev-client
npx expo prebuild --clean
npx expo run:android --device
# For iPhone, use npx expo run:ios --device instead.
npx expo start --dev-client

prebuild --clean recreates native directories. Preserve manual native edits first, or maintain them through config plugins. Projects that intentionally manage native directories must update their native configuration and rebuild using their own workflow. See Expo Development Builds and Continuous Native Generation.

Config-plugin dependency conflicts

#778 and #782 describe older releases installing an incompatible @expo/config-plugins version. v4's hardened Expo support, recorded in beta.10 release notes, uses an optional peer supplied by the Expo host instead of a package-owned runtime dependency.

Confirm the installed NFC-manager version and inspect the dependency graph with npm ls react-native-nfc-manager @expo/config-plugins. Follow your Expo SDK's compatible dependency versions and run npx expo-doctor. A v4 plugin fix is not evidence that the same change shipped in v3 or that all older SDKs were retested.

Android compileSdkVersion warning

#753 reports the old plugin trying to modify buildscript.ext.compileSdkVersion, which newer Expo layouts may not define. The current v4 plugin no longer calls that SDK-version modifier; this hardening is recorded in beta.10.

Let the Expo application own its Android SDK settings. If the warning persists, inspect the installed plugin version and other plugins/patches, regenerate the native configuration where applicable, and rebuild. An issue's automatic stale closure does not establish that its reported version was fixed.

Expo Doctor New Architecture warning

#782 also reports React Native Directory metadata marking the package as untested on New Architecture. Recorded v4 builds and device results are separate from that package-wide classification.

The pinned validator accepts this specific external metadata warning and rejects additional Doctor failures. Do not suppress all Doctor checks to hide dependency or configuration errors. Directory metadata will be coordinated with v4 becoming the default stable line so v3 is not mislabeled.

iOS NDEF entitlement and submission errors

#805 reports an App Store validation error about the NDEF reader-session entitlement. The plugin exposes includeNdefEntitlement: false to add only TAG; retain only one configured NFC-manager plugin entry:

{
  "expo": {
    "plugins": [
      [
        "react-native-nfc-manager",
        {
          "nfcPermission": "Allow this app to scan nearby NFC tags",
          "includeNdefEntitlement": false
        }
      ]
    ]
  }
}

The current plugin adds and deduplicates entitlement values. Setting this option to false does not remove NDEF already supplied in ios.entitlements, another plugin, or native configuration. A second default NFC-manager entry can also add NDEF. Inspect all configuration sources, regenerated entitlements, and the final signed app's entitlements. Check that the App ID/provisioning permits NFC. See Apple's reader-session entitlement reference.

Use the entitlement formats appropriate for your app and Apple's current requirements. This option is a configuration tool, not a guarantee of App Store acceptance or a verified solution for every error in #805. ISO 7816 identifiers and FeliCa codes should match the cards your app uses; copying arbitrary sample identifiers is not a general submission fix.

Finding current documentation

#806 highlights confusion between Expo and Expo Go instructions. The v4 README and this guide are the canonical v4 integration entrypoints. The default main branch contains v4 documentation; the v3 legacy branch retains a notice pointing to it. An unqualified npm install selects stable v4; use @3 for legacy applications.

Reporting an integration problem

Include exact NFC-manager, Expo, React Native, OS and device versions; New Architecture setting; Development Build versus Expo Go; plugin configuration; relevant Doctor/build output; and whether a fresh native build was installed. For a tag failure, also include tag technology, request/read/write sequence, error, and cleanup outcome. Remove credentials and signing secrets from shared logs.