nfc-pcsclite

Cross-platform NFC library for Node.js Read and write NFC tags and smart cards using built-in PC/SC bindings. Works on Linux, macOS, and Windows.

Content

• Overview
• Installation
  • Requirements
    • Node.js
    • Build tools
    • PC/SC API
    • Install package
• NFC Tag Handling Flow
• Basic Usage
• Alternative Usage (Manual Processing)
• Reading & Writing Data
• FAQ
  • Can I use it in Electron?
  • Can I use it in Angular + Electron?
  • Do I need Babel?
  • Supported Node.js versions
  • Can I read NDEF tags?
  • React Native support?
• Common Issues
  • Transaction failed using CONNECT_MODE_DIRECT
  • Authentication Error after Multiple Writes (MIFARE Classic)
  • Reading Type 4 tags (Elsys sensors)
• Disclaimer
• License

Overview

nfc-pcsclite provides a low-level Node.js interface for NFC operations using PC/SC bindings. It supports automatic card detection, UID reading, and communication with Android HCE devices.

✅ Supports card UID auto-reading

✅ Works with ACR122 USB reader and other PC/SC-compliant devices

✅ Includes native pcsclite bindings

⚠️ If card detection fails, check the Alternative Usage section.

Installation

Requirements

Node.js

Compatible with Node.js 18 or newer.

Build tools

This package includes native bindings built with node-gyp. Ensure you have a C/C++ toolchain installed for your OS. See node-gyp Installation Guide.

PC/SC API

• macOS / Windows: Already included.

• Linux / UNIX: Install manually:

apt-get install libpcsclite1 libpcsclite-dev pcscd

Install package

# Using npm
npm install nfc-pcsclite

# Using Yarn
yarn add nfc-pcsclite

NFC Tag Handling Flow

When a tag is detected, the following occurs:

1. Detects the card standard (TAG_ISO_14443_3 or TAG_ISO_14443_4);
2. Connects to the card;
3. Depending on autoProcessing:
   • true (default): automatically retrieves UID or APDU data; or
   • false: triggers card event only, letting you handle transmission manually;
4. You can then read, write, or send custom commands.

Basic Usage

import { NFC } from 'nfc-pcsc';

const nfc = new NFC(); // optional: pass a logger (e.g. Pino, Winston)

nfc.on('reader', reader => {
  console.log(`${reader.reader.name} device attached`);

  reader.on('card', card => {
    console.log(`${reader.reader.name} card detected`, card);
  });

  reader.on('card.off', card => {
    console.log(`${reader.reader.name} card removed`, card);
  });

  reader.on('error', err => {
    console.error(`${reader.reader.name} error`, err);
  });

  reader.on('end', () => {
    console.log(`${reader.reader.name} device removed`);
  });
});

nfc.on('error', err => {
  console.error('An error occurred', err);
});

Alternative Usage (Manual Processing)

import { NFC } from 'nfc-pcsc';

const nfc = new NFC();

nfc.on('reader', reader => {
  reader.autoProcessing = false;

  console.log(`${reader.reader.name} device attached`);

  reader.on('card', card => {
    console.log(`${reader.reader.name} card inserted`, card);

    // Send custom APDU commands using reader.transmit()
  });
});

Reading & Writing Data

Example with MIFARE Ultralight tag:

reader.on('card', async card => {
  try {
    const data = await reader.read(4, 12);
    console.log('Data read:', data.toString());
  } catch (err) {
    console.error('Error reading data', err);
  }

  try {
    const text = 'Bright minds build code';
    const buffer = Buffer.alloc(12, 0);
    buffer.write(text);
    await reader.write(4, buffer);
    console.log('Data written');
  } catch (err) {
    console.error('Error writing data', err);
  }
});

FAQ

Can I use it in Electron?

Yes. It works with Electron and other Node.js environments that support native modules.

See Electron’s guide on native modules.

Can I use it in Angular + Electron?

Yes. You’ll need to update your package.json and webpack.config.js per this issue comment.

Do I need Babel?

No. The library is already transpiled to support Node.js 18+.

Supported Node.js versions

It supports from the version 18.x to the latest 25.x, including the current LTS on 22.x. Node.js uses the convention of having the even-numbered versions as stable releases and odd-numbered versions having experimental features, but even and odd-numbered version numbers are basically backwards compatible.

Ref: Official Node.js Release Plan

Can I read NDEF tags?

Yes. Use reader.read() and parse the raw bytes with TapTrack/NdefJS.

React Native support?

No. nfc-pcsclite depends on Node.js native bindings and PC/SC APIs, unavailable in mobile runtimes.

Common Issues

Transaction failed using CONNECT_MODE_DIRECT

See explanation.

Authentication Error after Multiple Writes (MIFARE Classic)

See instructions.

Reading Type 4 tags (Elsys sensors)

Set readClass to 0x00 in:

reader.read(blockNumber, length, blockSize, packetSize, 0x00);

See discussion.

Disclaimer

This library revives maintenance over an abandoned project. For a high-level API, see nfc-pcsc.

License

Released under the MIT License.