GitHub - meshtastic/web: Meshtastic Web Client/JS Monorepo

Overview

This monorepo consolidates the official Meshtastic web interface, the domain-driven JavaScript SDK that drives it, and a set of runtime-specific transport packages. Everything you need to read state from or send commands to a Meshtastic device lives here.

Packages

All projects live under packages/.

Package	Purpose
`packages/sdk`	Framework-agnostic TypeScript SDK. Domain-driven feature slices (device, chat, nodes, channels, config, telemetry, position, traceroute, files) built around a `MeshClient` orchestrator with `@preact/signals-core` reactive state.
`packages/sdk-react`	React hooks + `MeshProvider` on top of `@meshtastic/sdk`. Wraps signals in `useSyncExternalStore` for concurrent-safe renders.
`apps/web`	Reference React web client. Hosted at client.meshtastic.org.
`packages/ui`	Shared Radix + Tailwind component library.
`packages/protobufs`	Generated TypeScript stubs from `meshtastic/protobufs`, produced via `buf generate`. Source of truth for every wire-level type.
`packages/transport-http`	HTTP transport for devices exposing a network interface.
`packages/transport-web-bluetooth`	Web Bluetooth transport for BLE-capable devices (browsers).
`packages/transport-web-serial`	Web Serial transport for USB-serial devices (browsers).
`packages/transport-node`	TCP transport for Node.js.
`packages/transport-node-serial`	Serial transport for Node.js.
`packages/transport-deno`	TCP transport for Deno.
`packages/transport-mock`	In-memory transport for tests.

All publishable packages ship to both JSR and NPM.

Architecture

@meshtastic/sdk organises its source by feature slice. Each slice follows the same DDD layout:

features/<slice>/
  domain/          # entities & value objects — pure TypeScript types
  application/     # use-cases (SendTextUseCase, FavoriteNodeUseCase, …)
  infrastructure/  # protobuf ↔ domain mappers, admin-message adapters
  state/           # signals-backed reactive stores
  <Slice>Client.ts # public facade exposing readable signals + command methods
  index.ts

The shared kernel under packages/sdk/src/core/ owns:

client/ — MeshClient, the thin orchestrator that owns the transport, queue, event bus, and one instance of every slice client.
transport/ — the Transport interface every transport-* package implements.
event-bus/ — typed pub/sub channels populated by the packet codec.
packet-codec/ — frame parser (0x94 0xC3), FromRadio decoder, portnum router.
queue/, xmodem/ — packet ack/timeout pipeline and file-transfer protocol.
signals/ — signal and keyed-collection helpers consumed by every slice.
logging/ — tslog factory used consistently by every class.
identifiers/, errors/ — small primitives shared across slices.

The protobuf boundary is strict: wire messages enter through the packet codec, get mapped into domain entities inside features/*/infrastructure/*Mapper.ts, and signals only ever expose the domain shape.

 Transport   ─▶   Packet codec   ─▶   EventBus   ─▶   Slice infrastructure
                                                            │
                                                            ▼
                                                    Signals (state)  ─▶  sdk-react hooks  ─▶  UI
                                                            ▲
                                                            │
 Slice application (use-cases)  ─▶   MeshClient.sendPacket  ─▶   Queue   ─▶   Transport

Expected domain errors are returned as Result<T, E> via better-result; exceptions are reserved for programmer errors and truly exceptional conditions.

Getting Started

Prerequisites

You need pnpm installed. If you plan to regenerate protobufs, also install the Buf CLI.

Setup

git clone https://github.com/meshtastic/web.git
cd web
pnpm install

Run the web client

pnpm --filter @meshtastic/web dev

Build everything

Run tests

Lint + format

pnpm check
pnpm check:fix

Developing

Adding a new feature slice to `@meshtastic/sdk`

Create packages/sdk/src/features/<slice>/ with domain/, application/, infrastructure/, state/ subdirectories plus an index.ts barrel.
Implement a signals-backed store in state/.
Subscribe to the relevant EventBus channel(s) inside a <Slice>Client.ts class and write mapped domain entities to the store.
Wire the new client into MeshClient and re-export types from packages/sdk/mod.ts.
Add vitest coverage: domain invariants, use-cases against createFakeTransport(), and round-trip mapper fixtures.
If the slice has React callers, add a matching hook under packages/sdk-react/src/hooks/.

Adding a new transport

Implement the Transport interface exported from @meshtastic/sdk/transport:

interface Transport {
  toDevice: WritableStream<Uint8Array>;
  fromDevice: ReadableStream<DeviceOutput>;
  disconnect(): Promise<void>;
}

The SDK does the framing and decoding — transports only supply raw bytes.

Testing

Vitest is wired at the repo root and picks up packages/* projects. The SDK ships @meshtastic/sdk/testing with createFakeTransport() for wiring tests without real hardware.

Publishing

Each publishable package has build:npm / publish:npm / prepare:jsr / publish:jsr scripts. See each package's package.json for details.

Repository activity

Project	Repobeats
Meshtastic Web

Feedback

If you encounter any issues, please report them in our issues tracker. Your feedback helps improve the stability of future releases.

Star history

Contributors

License

GPL-3.0-only. See LICENSE.