web-serial-rxjs

April 29, 2026 · View on GitHub

web-serial-rxjs project icon

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

Table of Contents

Features

  • Session-oriented reactive API: a single SerialSession exposes state$, isConnected$, receive$, lines$, errors$, plus connect$, disconnect$, and send$
  • UTF-8 text stream: receive$ is already decoded with a streaming TextDecoder, so multi-byte characters split across chunks are joined correctly
  • 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 idle / connecting / connected / disconnecting / unsupported / error so UIs can drive directly from it
  • 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

The Web Serial API is currently only supported in Chromium-based browsers:

  • Chrome 89+
  • Edge 89+
  • Opera 75+

SerialSession.isBrowserSupported() returns a synchronous boolean for feature detection before calling connect$.

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 (v2) at a glance

The canonical v2 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

DocUse it for
This READMEMonorepo hub: feature summary, examples, and contribution links.
SerialSession (v2) overviewFull v2 SerialSession / SerialSessionState map and minimal example.
Quick StartShortest path to a working open port and subscriptions.
Advanced UsageLine framing, request/response-style flows, and recovery.
API ReferenceOptions, SerialSessionState, and SerialError details.
v1 → v2 Migration GuideReplacing the removed v1 SerialClient / ShellClient API.

Examples

Examples are available for the following environments:

  • Angular - Angular example using a Service
  • React - React example with custom hook (useSerialSession)
  • Svelte - Svelte example using Svelte Store
  • Vanilla JavaScript - Basic usage with vanilla JavaScript
  • Vanilla TypeScript - TypeScript example with RxJS
  • Vue - Vue 3 example using Composition API

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.

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.

AI Assistant (MCP)

This project includes Model Context Protocol (MCP) server configuration for AI-assisted development. The following MCP servers are available:

ServerPurpose
nx-mcpNx workspace analysis, project graph, CI monitoring, and documentation
angular-cliAngular CLI tools for example-angular (code generation, documentation, best practices)
svelteSvelte/SvelteKit documentation and code analysis for example-svelte

Configuration files:

  • .mcp.json - Standard MCP configuration (Cursor, VS Code, Claude, etc.)
  • .cursor/mcp.json - Cursor-specific configuration

To use MCP servers in Cursor, the configuration is automatically loaded from .cursor/mcp.json. For VS Code, add the MCP extension and configure it to use .mcp.json, or add the server definitions to your MCP settings.

Development and Release Strategy

This project follows a trunk-based development approach:

  • main branch: Always in a release-ready state
  • Short-lived branches: feature/*, fix/*, docs/* for pull requests
  • Releases: Managed via Git tags (e.g., v1.0.0), not branches
  • Version maintenance: release/v* branches are added only when needed for maintaining multiple major versions

For detailed contribution guidelines, see CONTRIBUTING.md.

For detailed release instructions, see RELEASING.md.

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).

License

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