package
W3C Web NFC API (NDEFReader/NDEFMessage/NDEFRecord) for React Native on Android and iOS, with passthrough to the browser's native NDEFReader on web.
npm install react-native-web-nfc-apiGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Estimated unpacked size across 1 packages.
1.1 MB
Includes dependencies.
The W3C Web NFC API (
NDEFReader,NDEFMessage,NDEFRecord) for React Native on Android and iOS, passing through to the browser's nativeNDEFReaderon web (Chrome) by default.
Use the same API you already know from the browser — new NDEFReader(), scan(), write(), makeReadOnly(), onreading/onreadingerror — in a React Native app that talks to real NFC hardware, with a first-class in-memory simulator for testing and demos on every platform, including plain desktop web with no NFC hardware at all.
NDEFReader / NDEFMessage / NDEFRecord / NDEFReadingEventNfcAdapter/Ndef, iOS Core NFC)NfcTransport simulator (InMemoryNfcTransport + canned SimulatedTags) — no hardware, no mocking frameworkNDEFReader by default; an explicit mode: 'managed' opt-out runs the same simulatable implementation as native, in any browserexpose-nfc CLI) for driving a real device/emulator/browser against a simulated tag during manual QAIMPLEMENTATION_PLAN.md| Platform | Support | Notes |
|---|---|---|
| Android | Yes | Native NFC support (NfcAdapter/Ndef) through the TurboModule. |
| iOS | Implemented, unverified | Core NFC (ios/NfcModule.swift), covering live scanning and background/App-Clip tag-launch delivery — see "iOS status" below before relying on this. |
| Web | Yes | Passes through to the browser's native NDEFReader (Chrome, HTTPS, Android) by default; mode: 'managed' runs the simulator in any browser. |
The iOS Swift TurboModule (ios/NfcModule.swift, ios/NfcModule.mm,
ios/NfcPackage.swift, react-native-web-nfc-api.podspec) exists and is
implemented against Core NFC, matching the completeness level of the Android
module — but it has been written and reviewed with no Mac, no Xcode, and no
physical iPhone available, so nothing about it has been compiled, linked,
or run.
Spec (src/NativeNfc.ts) is not frozen for iOS per
IMPLEMENTATION_PLAN.md §7c: the operation-oriented shape, the session
type chosen in ios/NfcModule.swift, the NSUserActivityTypeBrowsingWeb
launch-delivery check, and the backgrounding-detection strategy are all
flagged UNVERIFIED/DECISION POINT comments at their exact locations in
that file, pending empirical confirmation.ios/NfcModule.mm and
ios/NfcPackage.swift is a best-understanding draft, not a confirmed
pattern for RN 0.85 — see those files' own headers for the open questions
(in particular, what RN 0.85's codegen actually generates for this
package's codegenConfig.name, which has not been observed).Info.plist, or .entitlements file anywhere
in this repo yet (there's no ios/*.xcodeproj and no example-app iOS
project) — the com.apple.developer.nfc.readersession.formats entitlement
and the NFCReaderUsageDescription Info.plist key both need to be added by
whoever integrates this into a real host app; they cannot ship from this
library alone.ios/ implementation, and the
codegenConfig/Spec freeze in IMPLEMENTATION_PLAN.md §13 step 7 are
blocked on running
docs/ios-feasibility-spike-checklist.md
on a Mac with a physical iPhone. Do not treat the iOS module as
production-ready until that checklist has been run and its findings
incorporated.npm install react-native-web-nfc-api
# or
yarn add react-native-web-nfc-apiThis is a New Architecture (Turbo Modules + codegen) library — no old-bridge fallback. Make sure your app has the New Architecture enabled. No manual linking is required on Android/iOS; the module is autolinked.
import {NDEFReader} from 'react-native-web-nfc-api';
async function run() {
const reader = new NDEFReader();
reader.onreading = event => {
console.log('serial number:', event.serialNumber);
for (const record of event.message.records) {
console.log(record.recordType, record.mediaType, record.data);
}
};
reader.onreadingerror = () => console.log('tag is not NDEF-formatted');
await reader.scan(); // resolves once the reader session is active, not once a tag is read
await reader.write('hello'); // encoded as a "text" record — see "Writing", below
}new NDEFReader() (the default, mode: 'passthrough') forwards every call straight to the browser's own window.NDEFReader — behaviorally identical to calling it yourself. Web NFC currently only works in Chrome on Android over HTTPS; in any other browser, methods reject with NotSupportedError at call time (see "The passthrough vs. managed split" below for why detection is per-call, not per-construction).write() accepts a string, BufferSource, or NDEFMessageInit:
await reader.write('hello'); // always a "text" record — strings are never auto-detected as URLs
await reader.write({records: [{recordType: 'url', data: 'https://example.com'}]});
await reader.write(new TextEncoder().encode('raw bytes'));Every async method accepts an AbortSignal:
const controller = new AbortController();
await reader.scan({signal: controller.signal});
controller.abort(); // scan()'s pending promise rejects with AbortErrorBecause this library always exports a working NDEFReader class (unlike a real unsupported browser, which simply has no global NDEFReader at all — see below), a non-spec static helper is provided for feature-detecting before construction:
if (NDEFReader.isSupported()) {
const reader = new NDEFReader();
// ...
}NDEFReader.isSupported(mode?) mirrors mode's own semantics: with the default 'passthrough' on web it reflects whether window.NDEFReader exists; on native, or with mode: 'managed', it's always true (whether real hardware/a transport is actually usable is an async, per-call concern answered by scan()/write() rejecting, not by this helper).
On native there's exactly one implementation — a managed polyfill backed by native NFC hardware — and mode has no effect. On web, NDEFReader decides at construction time which of two strategies to use:
interface NDEFReaderOptions {
mode?: 'passthrough' | 'managed'; // web only; ignored on native. Default: 'passthrough'.
}new NDEFReader() (default) — forwards every call directly to a real window.NDEFReader. No wire-format translation, no simulator, no transport in the path at all. If window.NDEFReader doesn't exist, methods reject with NotSupportedError at call time, not at construction/import time. This is a deliberate, documented divergence from a raw spec-compliant browser: real Chrome/other browsers simply don't define a global NDEFReader at all in an unsupported context, so bare spec-following app code gets a ReferenceError on new NDEFReader() itself. This library always exports a working class (so RN/web bundling has something concrete to import), so unsupported-browser detection necessarily happens per-method-call instead — use NDEFReader.isSupported?.() or a caught rejection.new NDEFReader({mode: 'managed'}) — routes through the same managed implementation native uses, resolving to whatever transport was installed via setNfcTransport() (typically InMemoryNfcTransport, see below), or a NotSupportedError-throwing stub if none was installed. This is what makes simulation/testing possible on web, in any browser, without physical NFC hardware.A per-instance option (rather than a module-level switch) means the same app can hold a real reader and a simulated one side by side — e.g. a live scan screen plus a demo/self-test screen — exactly as multiple concurrent NDEFReader instances are already supported on native.
The Web NFC spec relies on the browser's Permissions API (navigator.permissions.query({name: 'nfc'})). React Native has no such API, and this library does not implement a navigator.permissions shim — there is no reliable way to report permission state RN itself can't observe. Instead:
android.permission.NFC is a normal-protection permission — there is no runtime prompt. The library instead checks whether the NFC adapter is present and enabled (surfaced as NotSupportedError/NotReadableError from scan()/write()/makeReadOnly()).NFCReaderUsageDescription entry in Info.plist is required; the OS shows its own system permission prompt automatically the first time a Core NFC session starts. There is no separate JS-visible permission step — the first scan()/write() call triggers it.Document this divergence in your own app's UX (e.g. don't build a pre-flight "permission granted?" screen backed by navigator.permissions — there's nothing to query). See IMPLEMENTATION_PLAN.md §2 for the full rationale.
Everything above lib/'s codec layer is testable without hardware via react-native-web-nfc-api/testing:
import {NDEFReader, setNfcTransport} from 'react-native-web-nfc-api';
import {InMemoryNfcTransport, TextTag} from 'react-native-web-nfc-api/testing';
const transport = new InMemoryNfcTransport();
transport.addTag(new TextTag({text: 'hello from a virtual tag'}));
setNfcTransport(transport);
const reader = new NDEFReader({mode: 'managed'}); // works identically on Android, iOS, and web
reader.onreading = event => console.log(event.message.records);
await reader.scan();This mirrors the example app's Virtual Tag demo screen (see examples/self-test/App.tsx). Canned tags cover the common cases: TextTag, UrlTag, ReadOnlyTag, EmptyTag, MultiRecordTag, SlowTag (cancellation testing), FlakyTag (Nth-write failure), NonNdefTag (readingerror, not reading).
See TESTING.md for the full design spec: the behavioral matrix, InMemoryNfcTransport/SessionCoordinator API reference, the SimulatedTag catalogue, NfcClient, the conformance suite, the WebSocket bridge, and lifecycle/Maestro testing.
InMemoryNfcTransport covers in-process simulation for unit tests, but exercising a real device, emulator, or browser against a simulated tag — without physical NFC hardware — needs the WebSocket bridge:
npx expose-nfc --tag "text:hello from the bridge" --port 8787Simulated tag ("text:hello from the bridge") exposed on ws://127.0.0.1:8787
Waiting for a client connection... (Ctrl+C to stop)--tag accepts text:<value>, url:<value>, empty, readonly:<value>, or json:<path> (a JSON file of NdefWireRecord[] for a MultiRecordTag). Run npx expose-nfc --help for the full option list. See TESTING.md for the wire protocol and a client-side usage sketch.
For CI/Maestro runs against the example app, installInMemoryNfcTransport({enabled, tags}) (from react-native-web-nfc-api/websocket) does a flag-gated global install of a deterministic simulated transport at app startup — see TESTING.md's Maestro section.
Two RN-specific mechanisms, both normalized into the same NDEFReader/reading surface app code already uses — neither is part of the Web NFC spec, which has no app-lifecycle model at all:
reading event on the first scan() call after the app starts/resumes, via consumePendingLaunchTag()/launchTagReceived.scan() subscription survives the app losing and regaining the foreground: the physical native reader session is suspended (never surfaced to the caller as AbortError) and resumed automatically, with a fresh operation, once the app foregrounds again (assuming no exclusive write is in flight).Both are fully testable via InMemoryNfcTransport.simulateLaunchTag()/.simulateBackground()/.simulateForeground() — see TESTING.md §"launch-delivery and background/foreground lifecycle testing" and the example app's Launch/lifecycle screen.
To receive tag-tap launches, add an intent filter to your app's launcher activity:
<activity android:name=".MainActivity" ...>
<intent-filter>
<action android:name="android.nfc.action.NDEF_DISCOVERED" />
<category android:name="android.intent.category.DEFAULT" />
<data android:mimeType="text/plain" />
</intent-filter>
</activity>(This library cannot inject manifest entries into a consuming app — add this yourself if you need launch delivery.)
Add the com.apple.developer.nfc.readersession.formats entitlement and an NFCReaderUsageDescription entry to Info.plist.
Two runnable RN apps under examples/:
examples/self-test/ — exercises the library's own API directly across four screens: Live mode, Virtual Tag demo, Self-Test (the shared conformance suite, on-device), and a Launch/lifecycle banner with manual background/foreground toggles. See examples/self-test/.maestro/*.yaml for scripted e2e flows.examples/nfc-rewriter/ — a port of the community react-native-nfc-rewriter app (originally built on react-native-nfc-manager) rebuilt against this library's NDEFReader API, demonstrating a more realistic app shape (scan, write text/URI/vCard/WiFi records, save/reopen records, tag detail view). Screens relying on raw tag-technology access (Custom Transceive, Tag Kit) were dropped — see that app's own README/comments for what changed and why.Run either with:
cd examples/self-test # or: cd examples/nfc-rewriter
npm install
npm run android # or: npm run webThis library implements the Web NFC spec's own surface: NDEFReader/NDEFMessage/NDEFRecord, i.e. NDEF-formatted tags only. Raw tag-technology access below the NDEF layer (Mifare Classic/Ultralight, IsoDep, FeliCa, ISO15693 as distinct tag types) is out of scope — the spec has no concept of these.
MIT