nfc.js

A lightweight JavaScript (TypeScript-ready) helper for working with Web NFC in modern browsers.

Easily scan, write, and lock NFC tags using a minimal API with fallback handling and timeouts.

Compatibility

✅ Works on:

• Chrome for Android v89+ (v100+ for read-only support)

🚫 Not supported on:

• iOS
• Desktop browsers

Installation

npm install nfc.js

Or via CDN:

<script src="https://unpkg.com/nfc.js"></script>

Quick Start

import { NfcManager } from 'nfc.js';

const nfc = new NfcManager();

Scanning NFC Tags

Basic Scan

try {
  const event = await nfc.scan(20_000); // optional timeout in milliseconds
  console.log('Tag read:', event);

  // Process records
  event.message.records.forEach(record => {
    console.log('Record type:', record.recordType);
    const decoded = nfc.decodeRecordData(record);
    console.log('Decoded data:', decoded);
  });
} catch (error) {
  console.error('NFC error:', error.message);
}

Scan with Processing

const result = await nfc.scanAndRead(async (event) => {
  console.log('Tag detected:', event.serialNumber);

  // Process the tag
  return event.message.records.map(record => {
    return nfc.decodeRecordData(record);
  });
}, 20_000);

console.log('Processed data:', result);

Scan Multiple Tags

try {
  for await (const event of nfc.scanMultiple(30_000)) {
    console.log('New tag:', event.serialNumber);

    // Process each tag
    const records = event.message.records;
    // ... handle records

    // Continue scanning for next tag
  }
} catch (error) {
  console.error('Scan error:', error);
}

Writing Data to NFC Tag

Write

import { NfcManagerRecordType } from 'nfc.js';

const message: NDEFMessage = {
  records: [
    {
      recordType: NfcManagerRecordType.Text,
      data: 'Hello NFC!',
      lang: 'en',
    },
  ],
};

try {
  await nfc.scanAndWrite(message, 20_000);
  console.log('Data successfully written to NFC tag');
} catch (error) {
  console.error('Write error:', error.message);
}

Manual Write Process

import { NfcManagerRecordType } from 'nfc.js';

const message: NDEFMessage = {
  records: [
    {
      recordType: NfcManagerRecordType.Text,
      data: 'Hello NFC!',
      lang: 'en',
    },
  ],
};

try {
  // Start scanning
  const event = await nfc.scan(20_000);
  console.log('Tag detected, writing data...');

  // Write to the detected tag
  await nfc.write(message);
  console.log('Write successful');

  // Stop scanning
  nfc.abort();
} catch (error) {
  console.error('Write process error:', error);
}

Making Tag Read-Only

try {
  // Start scanning
  const event = await nfc.scan(20_000);
  console.log('Tag detected, making read-only...');

  // Make tag read-only
  await nfc.makeReadOnly();
  console.log('Tag is now read-only');

  // Stop scanning
  nfc.abort();
} catch (error) {
  console.error('Read-only process error:', error);
}

Decode record (NDEFRecord) data

try {
  // Start scanning
  const event = await nfc.scan(20_000);
  console.log('Tag detected, decoding data...');

  const records = event.message.records;

  for (const record of records) {
    try {
      const decoded = nfc.decodeRecordData(record);
      console.log('Decoded data:', decoded);
    } catch (err) {
      console.warn('Failed to decode record:', err);
    }
  }

  // Stop scanning
  nfc.abort();
} catch (error) {
  console.error('Decode process error:', error);
}

Aborting the Current Operation

// Abort the current scanning or writing operation
nfc.abort();

API Methods

Method	Description	Returns
scan()	Scans for a single NFC tag	Promise
scanAndWrite()	Scans for a tag and writes data to it	Promise
scanAndRead()	Scans for a tag and processes it with a function	Promise
scanMultiple()	Scans for multiple tags in sequence	AsyncGenerator
write()	Writes data to an already detected tag	Promise
makeReadOnly()	Makes an already detected tag read-only	Promise
decodeRecordData()	Decodes NDEF record data to string	string
abort()	Aborts the current operation	void
isScanning()	Returns whether scanning is active	boolean

TODO

• Write tests