npm package: @gurezo/web-serial-rxjs
Description: RxJS-based utilities for the Web Serial API, usable from Angular, React, Svelte, and Vanilla JavaScript/TypeScript.
Author: Akihiko Kigure
Latest version: 0.2.0

# web-serial-rxjs

<p align="center">
  <img src="https://raw.githubusercontent.com/gurezo/web-serial-rxjs/main/assets/icon/web-serial-rxjs-icon.png" alt="web-serial-rxjs project icon" width="512" />
</p>

A TypeScript library that provides a reactive RxJS-based wrapper for the Web Serial API, enabling easy serial port communication in web applications.

## Table of Contents

- [Features](#features)
- [Framework Support](#framework-support)
- [Browser Support](#browser-support)
- [Installation](#installation)
- [Documentation](#documentation)
- [Examples](#examples)
- [Project Icon](#project-icon)
- [AI Assistant (MCP)](#ai-assistant-mcp)
- [Development and Release Strategy](#development-and-release-strategy)
- [Contributing](#contributing)
- [License](#license)
- [Links](#links)

## Features

- **RxJS-based reactive API**: Leverage the power of RxJS Observables for reactive serial port communication
- **Text-friendly API**: Use `getReadStreamAsText()` and `writeText()` without manual encoding/decoding
- **Shell utility layer**: Execute command/prompt workflows with `createShellClient()`
- **TypeScript support**: Full TypeScript type definitions included
- **Browser detection**: Built-in browser support detection and error handling
- **Error handling**: Comprehensive error handling with custom error classes and error codes
- **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+

The library includes built-in browser detection utilities to check for Web Serial API support before attempting to use it.

## Installation

Install the package using npm or pnpm:

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

### Peer Dependencies

This library requires RxJS as a peer dependency:

```bash
npm install rxjs
# or
pnpm add rxjs
```

**Minimum required version**: RxJS ^7.8.0

## Documentation

- **[Quick Start](docs/QUICK_START.md)** - Get started with basic examples and usage patterns
- **[API Reference](docs/API_REFERENCE.md)** - Complete API documentation with detailed descriptions
- **[Advanced Usage](docs/ADVANCED_USAGE.md)** - Advanced patterns, stream processing, and error recovery

## Examples

Examples are available for the following environments:

- **[Angular](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-angular)** - Angular example using a Service
- **[React](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-react)** - React example with custom hook (`useSerialClient`)
- **[Svelte](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-svelte)** - Svelte example using Svelte Store
- **[Vanilla JavaScript](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vanilla-js)** - Basic usage with vanilla JavaScript
- **[Vanilla TypeScript](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vanilla-ts)** - TypeScript example with RxJS
- **[Vue](https://github.com/gurezo/web-serial-rxjs/tree/main/apps/example-vue)** - Vue 3 example using Composition API

Each example includes a README with setup and usage instructions.

## Project Icon

The project icon includes a modified design inspired by the [RxJS](https://rxjs.dev/) 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](http://reactivex.io/) or [RxJS](https://rxjs.dev/) project**.

## AI Assistant (MCP)

This project includes [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server configuration for AI-assisted development. The following MCP servers are available:

| Server          | Purpose                                                                                |
| --------------- | -------------------------------------------------------------------------------------- |
| **nx-mcp**      | Nx workspace analysis, project graph, CI monitoring, and documentation                 |
| **angular-cli** | Angular CLI tools for example-angular (code generation, documentation, best practices) |
| **svelte**      | Svelte/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](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.md).

For detailed release instructions, see [RELEASING.md](https://github.com/gurezo/web-serial-rxjs/blob/main/RELEASING.md).

## Contributing

We welcome contributions! Please see our [Contributing Guide](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.md) for details on:

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

For Japanese contributors, please see [CONTRIBUTING.ja.md](https://github.com/gurezo/web-serial-rxjs/blob/main/CONTRIBUTING.ja.md).

For release instructions, see [RELEASING.md](https://github.com/gurezo/web-serial-rxjs/blob/main/RELEASING.md) (or [RELEASING.ja.md](https://github.com/gurezo/web-serial-rxjs/blob/main/RELEASING.ja.md) for Japanese).

## License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/gurezo/web-serial-rxjs/blob/main/LICENSE) file for details.

## Links

- **GitHub Repository**: [https://github.com/gurezo/web-serial-rxjs](https://github.com/gurezo/web-serial-rxjs)
- **Issues**: [https://github.com/gurezo/web-serial-rxjs/issues](https://github.com/gurezo/web-serial-rxjs/issues)
- **Web Serial API Specification**: [https://wicg.github.io/serial/](https://wicg.github.io/serial/)