Building features that interact with Near Field Technology (NFC) using React Native may look simple on the surface, but developers soon discover a labyrinth of strict platform constraints, configuration hurdles, and subtle API bugs. A new open-source project named TapCard offers a deep dive into these challenges, chronicling the realities of reading, writing, locking, and decoding NFC tags using React Native without relying on third-party dependencies by the end of its lifecycle.
The project highlights how a chip costing about twenty pence and holding roughly a hundred and thirty bytes can trigger complex software workflows, from digital business cards to productivity focus sessions. However, earning the right to execute those reads and writes requires navigating two distinct gauntlets: Apple’s provisioning requirements and CoreNFC’s session-based API.
The initial hurdle belongs to Apple, requiring a paid developer account, a correctly registered App ID, a ticked capability, and a regenerated provisioning profile. A misstep in any of these components results in cryptic code-signing build errors. The second hurdle lies within CoreNFC itself, a session-based API characterized by delegate callbacks, nested asynchronous steps, and strict operational rules that offer little feedback when things go wrong.
To bypass limitations found in existing open-source libraries—such as truncated Unicode characters, discarded language codes, and missing UTF-16 support—the project’s creator authored a custom NDEF decoder in plain TypeScript. This custom solution handles data integrity and parsing cleanly before passing payloads to the React Native UI.
Hardware testing presents another unique challenge, as NFC functionality is entirely absent from the iOS Simulator and Android emulator. Developers must rely on physical hardware, making iterative testing reliant on real-world conditions. Furthermore, platform differences quickly emerge between iOS and Android. While iOS draws a system-controlled modal sheet during scans and abstracts much of the UI, Android requires applications to implement their own scanning interfaces and cancellation buttons, while shifting the internal hardware antenna location from the top edge of the device to the middle of the back.
Data handling on tags brings its own technical considerations. Standard tags like the NTAG213 provide roughly 144 bytes of user memory, which quickly becomes constrained when formatting complex structures like vCards. Writing to these chips requires pre-flight checks to ensure capacity limits are respected, preventing partial writes or unhandled overflow errors.
Beyond contact sharing, the TapCard project explores utility applications such as enforcing productivity habits. By requiring a user to physically tap a distant tag to terminate an active focus timer, the software leverages physical geography as a behavioral constraint. Because iOS restricts privileged digital wellbeing entitlements for third-party apps, the system relies on immutable local history logs and explicit confirmation steps to enforce its design goals rather than attempting system-level app blocking.
The project also documents critical pitfalls encountered during development, such as CoreNFC sessions deallocating prematurely due to improper variable scoping, promise settlement conflicts resulting from overlapping delegate callbacks, and unexpected runtime failures caused by requesting unauthorized polling options like FeliCa without corresponding entitlements.
Ultimately, the TapCard codebase serves as an extensive exploration of mobile NFC capabilities, providing a transparent look at the platform restrictions, architectural decisions, and native module replacements necessary to build reliable, hardware-integrated mobile software.
