serialport-rs for Node.js

SerialPort-compatible serial I/O for Node.js, backed by Rust.

Use a familiar SerialPort 13-style API with a Rust native backend. Streams, parsers, bindings, and mock ports come together in one package, with no JavaScript runtime dependencies.

Install · Migration · API · Tests

Why this exists

This project started after Node.js 26.4 exposed a bug in the existing C++ bindings: serial I/O could stall until unrelated JavaScript activity caused pending Promises to continue.

The root cause was how @serialport/bindings-cpp called back into JavaScript, using an approach Node.js does not recommend. Fixes were proposed upstream, but SerialPort has seen limited maintenance, making timely fixes difficult as Node.js evolves.

This is an independent project, not an official SerialPort release.

For the technical background, see the Node.js event-loop optimization, Azq2's upstream poller fix, and DragonWork's follow-up callback-scope fix.

Install

Requires Node.js 20 or newer. Get the latest npm release:

npm install serialport-rs

Quick start

Save this as example.mjs. Set the device path, baud rate, and line delimiter to match your device; a Windows device path might be COM3.

import { SerialPort, ReadlineParser } from 'serialport-rs';

const port = new SerialPort({
  path: '/dev/ttyUSB0',
  baudRate: 115200,
});

const lines = port.pipe(new ReadlineParser({ delimiter: '\r\n' }));

port.on('error', error => console.error('Serial port error:', error.message));
port.on('close', () => console.log('Serial port closed'));
lines.on('error', error => console.error('Parser error:', error.message));
lines.on('data', line => console.log('Received:', line));

port.on('open', () => {
  console.log('Serial port opened');
  // Replace this with a command understood by your device.
  port.write('status\r\n', error => {
    if (error) console.error('Write failed:', error.message);
  });
});

CommonJS is also supported:

const { SerialPort, ReadlineParser } = require('serialport-rs');

Migrating from SerialPort

Start by changing your application import:

- import { SerialPort } from 'serialport';
+ import { SerialPort } from 'serialport-rs';

Parsers and mocks are exported by the same package. See the migration guide for those changes and for applications whose dependencies import SerialPort internally. Changing your own import does not replace another package's dependency.

Compatibility is a project goal backed by automated stream and parser comparisons, not a promise that every application and driver combination behaves identically. Unexpected behavior when migrating is useful feedback — so please report it.

Design and performance

Serial I/O runs on a dedicated, bounded Rust worker pool. Idle reads do not depend on a heartbeat timer. Read-ahead and pending-operation queues are bounded; your application must still honor stream backpressure.

The architecture guide explains buffer ownership, worker lifetime, and recovery behavior. Reconnection and protocol recovery belong to the application. A blocked physical-output drain can also delay closing a port.

Recorded Linux x64 and ARM64 pseudo-terminal comparisons show lower tail latency against a patched C++ baseline that includes the callback-scope fix. These measurements cover the host software path, not physical UART speed. Exact versions, workloads, results, and reproduction commands are in the benchmark documentation.

Documentation

• Migrating from SerialPort
• Stream and binding API, options, and parsers
• Mock ports
• Architecture, memory ownership, and lifecycle
• Native build targets
• Development and checks
• Changelog
• Benchmarks

Acknowledgements

Thanks to the SerialPort maintainers and contributors. Its API and testing approach helped shape this project.

License

Copyright 2026 DragonWork. Apache-2.0. See NOTICE and third-party licenses.