@gurezo/web-serial-rxjs

A TypeScript library that wraps the Web Serial API with a minimal, session-oriented RxJS surface. The public API exposes a single SerialSession so applications can drive their UI from state$ (canonical lifecycle state) + errors$ (error event channel) + receive$ + lines$, without rebuilding read loops or send queues themselves.

Primary focus: UTF-8 text. Incoming data is always decoded with a streaming UTF-8 TextDecoder. receive$ emits decoded text chunks (unframed), not raw wire bytes. Binary send via send$(Uint8Array) is supported; binary receive, non-UTF-8 charsets, and protocol framing (Modbus, COBS, SLIP, …) are out of scope. See Supported data below and API concepts.

Browser support

This section separates Web Serial API availability (what the browser implements) from this project's official support policy (what we test and guarantee).

Web Serial API availability

Where navigator.serial exists, this library can talk to the Web Serial API. Typical desktop availability:

• Chrome 89+
• Edge 89+
• Opera 75+
• Firefox 151+

Safari does not currently implement the Web Serial API. Many mobile browsers also lack navigator.serial; when the API is missing, isWebSerialSupported() returns false.

Project support policy

Official support covers the desktop browsers listed above (Chrome 89+, Edge 89+, Opera 75+, Firefox 151+).

Mobile browsers are untested and out of official support. Untested does not mean the library rejects them — if a mobile browser exposes Web Serial and the page is in a secure context, feature detection may succeed, but we do not guarantee behavior.

isWebSerialSupported()

isWebSerialSupported() returns a synchronous boolean for feature detection (navigator.serial present) before connect$. It is not a compatibility or official-support guarantee. Secure context (HTTPS or localhost) is a separate requirement.

Connection state (lifecycle UI)

Prefer state$ with state.status narrowing as the canonical API for lifecycle UI. Derive a boolean from state$ when you only need a connected flag. Session teardown uses dispose$() (subscribe to run it). See Migrating to v4.

Port info (device identification)

After a successful connect$, use state.portInfo when handling state$ with state.status === SerialSessionStatus.Connected — this is the canonical API. Raw SerialPort is not exposed. Removed convenience APIs (isConnected$, portInfo$, getPortInfo(), destroy$(), getCurrentPort(), receiveReplay$, isBrowserSupported()) and their replacements are documented in Migrating to v4.

Supported data (text / binary / charset)

| Item | Current support | | --- | --- | | UTF-8 text send / receive | Supported | | Chunk-oriented string receive | receive$ (decoded chunks, not wire bytes) | | Newline-delimited string receive | lines$ | | Terminal display with \r redraws | receive$ / terminalText$ | | Binary send | send$(Uint8Array) | | Binary receive | Not supported (no raw Uint8Array receive stream) | | Non-UTF-8 charsets | Not supported | | Protocol framing (Modbus, COBS, SLIP, …) | Application-side |

Full notes and future design considerations: API concepts — Supported data.

receive$ vs lines$

Pick the stream that matches your use case. Using lines$ for a terminal mirror drops \r and redraw behaviour, which breaks shells and tools that rely on carriage-return updates (overview).

receive$ (decoded chunks)

• UTF-8 decoder chunks as they arrive—not line-aligned, and not raw wire bytes.
• Preserves \r, partial lines, and other control characters from the decoded text.
• Use for: terminal display, prompt detection, buffering / scrollback you control, and other unframed decoded-stream handling.

lines$ (line-delimited events)

• Emits complete lines (\n, \r\n, interior \r per implementation).
• Use for logs, structured parsing, and protocols framed on newlines.
• Not suitable for mirroring interactive CLI output when peers use \r for in-place redraws—you lose those semantics.

Avoid / Prefer

Avoid—appending lines$ strings for a terminal-style view hides redraws and corrupts layouts.

session.lines$.subscribe((line) => {
  output += line + '\n';
});

Prefer—concatenate chunks from receive$ for mirrors and shell-style buffers.

session.receive$.subscribe((chunk) => {
  output += chunk;
});

Installation

npm install @gurezo/web-serial-rxjs
# or
pnpm add @gurezo/web-serial-rxjs

Peer dependency

This library requires RxJS ^7.8.0 as a peer dependency:

npm install rxjs
# or
pnpm add rxjs

The package is ESM-only (import via package.json exports).

Where to go next

• Full API map (features, SerialSession table, SerialSessionState, minimal example): SerialSession overview (日本語)
• Shortest path to an open port: Quick Start
• Common problems and self-help: Troubleshooting
• Browse the published documentation site: web-serial-rxjs Documentation
• Browse API Reference (TypeDoc): web-serial-rxjs API Documentation

Documentation

| Doc | Use it for | | --- | --- | | Documentation home | Site landing with Guide (ja/en) and API Reference | | English Guide (site) | Getting Started reading order on the published site | | API Reference (site) | English TypeDoc API Reference | | English Guide index | Getting Started reading order and full index | | Overview | Features and the SerialSession / SerialSessionState map | | Quick Start | Open a port and wire subscriptions end-to-end | | Advanced Usage | Line framing, request/response-style flows, recovery | | Troubleshooting | Common Web Serial / session problems and self-help checks | | API concepts and design notes | SerialSessionOptions, SerialError, and formal details | | v3 → v4 migration | Phase 1+2 removals (receiveReplay$, isBrowserSupported(), options cleanup) | | v2 → v3 migration | state$ discriminated union, SerialSessionStatus, context.cause | | v1 → v2 migration | Replacing the removed v1 SerialClient / ShellClient API | | Repository README | Monorepo hub: examples under apps/, contribution entry, development-tool pointers | | CONTRIBUTING | MCP / Cursor setup for repository contributors |

License

MIT — see the LICENSE file in the repository.

Links

• Repository: github.com/gurezo/web-serial-rxjs
• Issues: github.com/gurezo/web-serial-rxjs/issues
• Web Serial API (spec): wicg.github.io/serial