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 state, read loops, or send queues themselves.

Audience: This README is primarily for library users (install, connect, Examples, Guide). Contributors and maintainers should start from Contributing and CONTRIBUTING.md. The short npm package README is the consumer-facing index published with @gurezo/web-serial-rxjs; this repository README is the monorepo hub (examples under apps/, contribution, and development tools).

Table of Contents

• Features
• Framework Support
• Browser Support
• Installation
• SerialSession at a glance
• Documentation
• Examples
• Migration
• Troubleshooting
• Contributing
• Development tools
• Development and Release Strategy
• Project Icon
• Security
• License
• Links

Features

• Session-oriented reactive API: a single SerialSession exposes state$ (canonical lifecycle discriminated union), errors$ (error event channel), receive$, lines$, and connect$, disconnect$, dispose$, and send$
• UTF-8 text stream: receive$ is already decoded with a streaming TextDecoder, so multi-byte characters split across chunks are joined correctly. This library is text-first: binary receive and non-UTF-8 charsets are out of scope (binary send via send$(Uint8Array) is supported). See the package README supported-data table and Guide concepts
• Ordered send queue: concurrent send$ calls are serialised internally in call order, without the caller having to manage a writer
• Unified error channel: every I/O error is normalised into SerialError and multiplexed on errors$
• Explicit lifecycle: state$ emits a discriminated union with status (idle / connecting / connected / disconnecting / unsupported / error / disposed) so UIs can narrow on state.status and access per-state data such as state.portInfo
• TypeScript support: full TypeScript type definitions included
• Framework agnostic: works with any JavaScript/TypeScript framework or vanilla JavaScript

Framework Support

This library is framework-agnostic and can be used with:

• Angular
• React
• Svelte
• Vanilla JavaScript / TypeScript

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 calling connect$. It is not a compatibility or official-support guarantee. Secure context (HTTPS or localhost) is a separate requirement.

Guide detail: Browser support and support policy.

Installation

Install the package using npm or pnpm:

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

Peer Dependencies

This library requires RxJS as a peer dependency:

npm install rxjs
# or
pnpm add rxjs

Minimum required version: RxJS ^7.8.0

SerialSession at a glance

The canonical API map (feature list, the SerialSession / SerialSessionState tables, and a minimal example) is in the package documentation:

• SerialSession overview · 日本語

The npm README for @gurezo/web-serial-rxjs is a short index; for a first connection, follow Quick Start.

Choosing receive$ versus lines$—terminal-style mirrors and buffering versus newline-delimited logs and parsing—is spelled out in that package README (receive$ vs lines$).

Documentation

Documentation is split into Guide (how to use; Japanese and English hand-written Markdown) and API Reference (English TypeDoc from TypeScript JSDoc). The canonical layout is defined in Documentation Architecture (日本語).

Published documentation site: gurezo.net/web-serial-rxjs

Role split: use the npm package README for a short consumer index shipped with the package; use this repository README for monorepo examples, contribution entry points, and development-tool pointers.

Doc	Use it for
This README	Monorepo hub: feature summary, examples, and contribution links.
npm package README	Short consumer-facing index published with @gurezo/web-serial-rxjs.
English Guide (site)	Getting Started reading order and full index on the published site.
日本語 Guide (site)	Getting Started の読み順と一覧（公開サイト）。
API Reference (site)	English TypeDoc API Reference on the published site.
English Guide index	Getting Started reading order and full index (source).
SerialSession overview	Full SerialSession / SerialSessionState map and minimal example.
Quick Start	Shortest path to a working open port and subscriptions.
Advanced Usage	Line framing, request/response-style flows, and recovery.
Troubleshooting	Common Web Serial / session problems and self-help checks.
Version support and release policy	SemVer, deprecations, support window (no LTS).
Bundler and framework compatibility	CI vs Example builds; ESM / RxJS / types (no full matrix).
Bundle size and tree-shaking	Library-only size snapshot and reproducible measurement.
Verified environment listing criteria	Minimum fields if hardware results are published (not a device catalog).
API concepts and design notes	Options, SerialSessionState, and SerialError details.
v3 → v4 Migration Guide	Phase 1+2 removals (receiveReplay$, isBrowserSupported(), options cleanup).
v2 → v3 Migration Guide	state$ discriminated union, SerialSessionStatus, and context.cause.
v1 → v2 Migration Guide	Replacing the removed v1 SerialClient / ShellClient API.

Examples

Framework examples demonstrate how to wire SerialSession in each stack. They are not a supported-device catalog, and a successful Example build is not a full bundler / framework compatibility matrix. For communication patterns (line protocol, command/reply, timeout, and so on), see the Recipes index. For what CI verifies and the ESM / RxJS baseline, see Bundler and framework compatibility. Criteria for any future hardware verification list: Verified environment listing criteria.

Start here: Vanilla TypeScript (Recommended / まずはこちら) — try the library API with TypeScript and RxJS, with no UI framework.

• Vanilla TypeScript — Recommended starting point (TypeScript + RxJS, no framework)
• Vanilla JavaScript — Same connect flow without TypeScript or a UI framework
• Angular — Wire SerialSession through an injectable Service
• React — Custom hook (useSerialSession)
• Vue — Vue 3 Composition API (composable)
• Svelte — Svelte Store

Interactive demos: https://gurezo.net/web-serial-rxjs/examples/.

Each sample is a minimal smoke test for connect, receive (terminal-style append via receive$ so \r redraws stay intact), send, and disconnect. Use lines$ only when you want newline-delimited logging or parsing—not for mirroring interactive terminal output; deeper patterns live in Advanced Usage.

Each example includes a README with setup and usage instructions.

Migration

Upgrading from an older major version:

• v3 → v4 Migration Guide · 日本語
• v2 → v3 Migration Guide · 日本語
• v1 → v2 Migration Guide · 日本語

Troubleshooting

Common Web Serial / session problems and self-help checks:

• Troubleshooting (English Guide) · 日本語

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Development setup
• Code style guidelines
• Commit message conventions
• Pull request process
• Release process

For Japanese contributors, please see CONTRIBUTING.ja.md.

For release instructions, see RELEASING.md (or RELEASING.ja.md for Japanese).

Development tools

For AI-assisted development in this repository:

• MCP servers (Nx, Angular CLI, Svelte) and configuration — see AI Assistant (MCP) in CONTRIBUTING
• Cursor rules, skills, and agents — see Cursor Rules / Skills in CONTRIBUTING

日本語は CONTRIBUTING.ja.md の同セクションを参照してください。

Development and Release Strategy

This project follows trunk-based development: main stays release-ready; work lands via short-lived feature/* / fix/* / docs/* pull requests; releases are Git tags (for example v1.0.0).

• Contribution details: CONTRIBUTING.md
• Release instructions: RELEASING.md
• Version support / release policy (Guide): English · 日本語
• Bundler / framework compatibility (Guide): English · 日本語
• Bundle size / tree-shaking (Guide): English · 日本語
• Verified environment listing criteria (Guide): English · 日本語

Project Icon

The project icon includes a modified design inspired by the RxJS logo, combined with a serial connector motif to represent Web Serial communication.

The icon is used only to indicate that this library provides RxJS-based abstractions for the Web Serial API.

This project is an independent open source project and is not affiliated with, endorsed by, or sponsored by the ReactiveX or RxJS project.

Security

To report a vulnerability privately, see the Security Policy (日本語). Do not open a public issue with vulnerability details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• Documentation: https://gurezo.net/web-serial-rxjs/
• GitHub Repository: https://github.com/gurezo/web-serial-rxjs
• Issues: https://github.com/gurezo/web-serial-rxjs/issues
• Security Policy: SECURITY.md (日本語)
• Web Serial API Specification: https://wicg.github.io/serial/