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).
- 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
- Session-oriented reactive API: a single
SerialSessionexposesstate$(canonical lifecycle discriminated union),errors$(session-scoped errors),receive$,lines$, andconnect$,disconnect$,dispose$, andsend$ - UTF-8 text stream:
receive$is already decoded with a streamingTextDecoder, 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 viasend$(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 - Exclusive error notification: operation failures stay on the
connect$/send$/disconnect$subscriber. Post-connect read-pump errors, unexpected disconnect, andLINE_BUFFER_OVERFLOWare emitted onerrors$ - Explicit lifecycle:
state$emits a discriminated union withstatus(idle/connecting/connected/disconnecting/unsupported/error/disposed) so UIs can narrow onstate.statusand access per-state data such asstate.portInfo - TypeScript support: full TypeScript type definitions included
- Framework agnostic: works with any JavaScript/TypeScript framework or vanilla JavaScript
This library is framework-agnostic and can be used with:
- Angular
- React
- Svelte
- Vanilla JavaScript / TypeScript
This section separates Web Serial API availability (what the browser implements) from this project's official support policy (what we test and guarantee).
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.
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() 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.
Install the package using npm or pnpm:
npm install @gurezo/web-serial-rxjs
# or
pnpm add @gurezo/web-serial-rxjsThis library requires RxJS as a peer dependency:
npm install rxjs
# or
pnpm add rxjsMinimum required version: RxJS ^7.8.0
The canonical API map (feature list, the SerialSession / SerialSessionState tables, and a minimal example) is in the package documentation:
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 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. |
| v4 → v5 Migration Guide | Breaking changes: error notification, dispose(), removed deprecated APIs. |
| 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. |
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.
Upgrading from an older major version:
- v4 → v5 Migration Guide · 日本語
- v3 → v4 Migration Guide · 日本語
- v2 → v3 Migration Guide · 日本語
- v1 → v2 Migration Guide · 日本語
Common Web Serial / session problems and self-help checks:
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).
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 の同セクションを参照してください。
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 · 日本語
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.
To report a vulnerability privately, see the Security Policy (日本語). Do not open a public issue with vulnerability details.
This project is licensed under the MIT License - see the LICENSE file for details.
- 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/