From 98d036626e7420ba59423998d78d09c938a6c9d7 Mon Sep 17 00:00:00 2001 From: Dan Ditomaso Date: Sat, 22 Aug 2026 13:30:41 -0400 Subject: [PATCH 1/2] docs: fix build steps and package paths in READMEs Root README and apps/web README pointed to the pre-monorepo `packages/web` path and used a filter (`@meshtastic/web`) that resolves to the workspace root package, not the web app. Users following the docs hit `pnpm -r build` failures because Buf CLI is required for `@meshtastic/protobufs` to build, but was documented as optional. - Root README: clarify that libraries live under `packages/` while the reference web client lives under `apps/`; mark Buf CLI as required for `pnpm -r build`; document the topological order and add a web-only build path via `pnpm --filter meshtastic-web... build`. - apps/web README: replace `cd packages/web && pnpm install` with a root-level install; use `pnpm --filter meshtastic-web` for dev/build/ package scripts; correct the CONTRIBUTING link. Fixes #1252 --- README.md | 23 +++++++++++++++++++---- apps/web/README.md | 13 ++++++------- 2 files changed, 25 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 577e7efaa..02c4f3367 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ send commands to a Meshtastic device lives here. ## Packages -All projects live under `packages/`. +Libraries live under `packages/`; the reference web client lives under `apps/`. | Package | Purpose | | --- | --- | @@ -83,8 +83,12 @@ Expected domain errors are returned as `Result` via [`better-result`](http ### Prerequisites -You need [pnpm](https://pnpm.io/) installed. If you plan to regenerate -protobufs, also install the [Buf CLI](https://buf.build/docs/cli/installation/). +- [pnpm](https://pnpm.io/) — package manager for the workspace. +- [Buf CLI](https://buf.build/docs/cli/installation/) — required whenever + `@meshtastic/protobufs` needs to build (which happens on a full + `pnpm -r build`, since it runs `buf generate`). If you only want to run + the web client in dev, `pnpm --filter meshtastic-web dev` does not need + Buf as long as the protobuf stubs are already generated. ### Setup @@ -97,15 +101,26 @@ pnpm install ### Run the web client ```bash -pnpm --filter @meshtastic/web dev +pnpm --filter meshtastic-web dev ``` ### Build everything +`pnpm -r` walks the workspace in topological order, so `@meshtastic/protobufs` +runs first and every downstream package (including `packages/ui`) sees the +generated stubs. Requires the Buf CLI (see Prerequisites). + ```bash pnpm -r build ``` +If you only need the web client, build it and its dependency graph without +touching every publishable package: + +```bash +pnpm --filter meshtastic-web... build +``` + ### Run tests ```bash diff --git a/apps/web/README.md b/apps/web/README.md index ccce1876d..8a5f9d57a 100644 --- a/apps/web/README.md +++ b/apps/web/README.md @@ -86,17 +86,16 @@ instructions listed on the home page. ### Development -Install the dependencies. +Install the dependencies from the repo root (pnpm workspaces installs every package in one pass). ```bash -cd packages/web && pnpm install ``` -Start the development server: +Start the development server for the web client: ```bash -pnpm run dev +pnpm --filter meshtastic-web dev ``` ### Building and Packaging @@ -104,13 +103,13 @@ pnpm run dev Build the project: ```bash -pnpm run build +pnpm --filter meshtastic-web build ``` GZip the output: ```bash -pnpm run package +pnpm --filter meshtastic-web run package ``` ### Why pnpm? @@ -151,6 +150,6 @@ requests: Meshtastic nodes. Please review our -[Contribution Guidelines](https://github.com/meshtastic/web/blob/main/packages/web/CONTRIBUTING.md) +[Contribution Guidelines](https://github.com/meshtastic/web/blob/main/apps/web/CONTRIBUTING.md) before submitting a pull request. We appreciate your help in making the project better! From 29b11e3fe968f08f2c9877678e1f05f821d3ee68 Mon Sep 17 00:00:00 2001 From: Dan Ditomaso Date: Sat, 22 Aug 2026 15:51:53 -0400 Subject: [PATCH 2/2] docs: correct pnpm -r ordering claim in root README `pnpm -r --sort` (default) orders packages only by their `workspace:` dependencies. `packages/ui` has no workspace dep on `@meshtastic/protobufs`, and `@meshtastic/sdk` pulls protobufs over `jsr:`, so neither is sequenced after protobufs by workspace sort. The prior wording implied a stronger guarantee than pnpm provides. --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 02c4f3367..aae4e0feb 100644 --- a/README.md +++ b/README.md @@ -106,14 +106,20 @@ pnpm --filter meshtastic-web dev ### Build everything -`pnpm -r` walks the workspace in topological order, so `@meshtastic/protobufs` -runs first and every downstream package (including `packages/ui`) sees the -generated stubs. Requires the Buf CLI (see Prerequisites). +Requires the Buf CLI (see Prerequisites) — `@meshtastic/protobufs` runs +`buf generate` as part of its `build` script. ```bash pnpm -r build ``` +`pnpm -r` sorts packages by their `workspace:` dependencies (dependencies +before dependents) and runs up to `--workspace-concurrency` packages in +parallel. Packages linked over other protocols (for example `jsr:`) are +not sequenced against workspace peers, so run `pnpm --filter +@meshtastic/protobufs build` first if you are iterating on generated +stubs consumed via a non-workspace protocol. + If you only need the web client, build it and its dependency graph without touching every publishable package: