Document the npm workspace and shared/ui

This commit is contained in:
Rūdolfs Ošiņš
2026-10-29 16:27:03 +01:00
parent 7ce1deaf22
commit 2c44c70ff2
8 changed files with 148 additions and 37 deletions
+27 -12
View File
@@ -1,13 +1,16 @@
# radicle-gui
Monorepo for Radicle's graphical interfaces. It holds two independent
projects, each with its own npm package, Cargo workspace, toolchain files,
checks and conventions:
Monorepo for Radicle's graphical interfaces. It holds two projects, each with
its own Cargo workspace, toolchain files, checks and conventions, and the UI
code they share. One npm workspace at the root holds all three packages:
- **Explorer** (`explorer/`): the Svelte web app for browsing Radicle
repositories, its TypeScript HTTP client, and the `radicle-httpd` and
`radicle-search` backends it talks to. See `explorer/AGENTS.md`.
- **Desktop** (`desktop/`): the Tauri desktop app. See `desktop/AGENTS.md`.
- **Shared UI** (`shared/ui/`): the `@radicle-gui/ui` package with Svelte
components, helpers, design tokens and fonts used by both apps. See
`shared/ui/AGENTS.md`.
This file covers what applies to both. Each project's `AGENTS.md` is the
source of truth for anything inside it.
@@ -18,20 +21,27 @@ source of truth for anything inside it.
|---|---|
| `explorer/` | Web app, HTTP client, `radicle-httpd` and `radicle-search` |
| `desktop/` | Tauri app: Svelte frontend in `src/`, Rust in `crates/` |
| `shared/ui/` | UI code shared by both apps |
| `package.json`, `package-lock.json`, `.npmrc`, `.nvmrc` | The npm workspace, its lockfile and npm and Node settings |
| `docs/adr/` | Decisions that affect the whole repository |
| `.github/workflows/` | GitHub CI: `explorer-*.yml` for explorer, `desktop-*.yml` for desktop |
| `.github/workflows/` | GitHub CI: `explorer-*.yml` for explorer, `desktop-*.yml` for desktop, `shared-ui.yml` for the shared UI |
| `.buildkite/` | Radicle CI pipelines (explorer only) |
| `.ryph/` | Dev machine image and setup for agents, see `.ryph/environment.md` |
## Working in this repo
- Work out which project a change belongs to first, and run every command
from that project's directory. There are no root `npm` or `cargo`
commands.
- Install npm dependencies at the root: `npm ci` for everything, or
`npm ci -w explorer` or `npm ci -w desktop` for one app. Run every other
command from the project's directory; there are no root `cargo` commands.
- Work out which project a change belongs to first. Changes to `shared/ui`
affect both apps: check `shared/ui` and both apps.
- A change that touches both projects is two changes: check each project
with its own commands.
- Explorer's components use legacy Svelte syntax (`$:`, stores,
`export let`), desktop's use Svelte 5 runes.
`export let`), desktop's and the shared ones use Svelte 5 runes.
- Code in `shared/ui` must not import `@tauri-apps/*`, `@bindings`,
`@http-client` or anything else from one app. It takes plain props, and
each app adapts its own data to them.
- Record a bigger architectural change as a new ADR, numbered after the last
one and in the same format: in `docs/adr/` if it affects the whole
repository, in the project's own `docs/adr/` otherwise.
@@ -46,7 +56,7 @@ source of truth for anything inside it.
use proper English sentences
- Ask before adding new dependencies: each one is a supply-chain risk, and
installs are gated by `min-release-age` and `strict-allow-scripts`
- Use npm, never `yarn` or `pnpm`: the lockfiles and `.npmrc` settings are
- Use npm, never `yarn` or `pnpm`: the lockfile and `.npmrc` settings are
npm's
- Updates and audit fixes must respect each project's 7-day cooldown, see
"Updating dependencies" below
@@ -66,8 +76,9 @@ source of truth for anything inside it.
## Updating dependencies
Both projects only install releases that are at least 7 days old: npm through
`min-release-age` in `.npmrc`, Cargo through `cooldown.toml` and
`cargo-cooldown`. Run these from the project's directory:
`min-release-age` in the root `.npmrc`, Cargo through `cooldown.toml` and
`cargo-cooldown`. npm commands cover the whole workspace and change the root
lockfile; run Cargo commands from the project's directory:
```sh
npm audit # list advisories
@@ -77,11 +88,15 @@ cargo cooldown update -p <crate> # update a crate within the cooldown
```
- Never run plain `cargo update`: it ignores `cooldown.toml`
- `katex` is pinned for the whole workspace by an override in the root
`package.json`, so mermaid and both apps use one version. Bump it there as
well as in the apps, or the apps' bump has no effect
- Never run `npm audit fix --force`: it takes major-version bumps. Ask first
- If a fix is still cooling down, report when it clears and ask before
taking it early. Taking it early means reviewing the release's diff
against the previous version, then:
- npm: `npm install <pkg>@<version> --min-release-age=0`
- npm: `npm install <pkg>@<version> -w <project> --min-release-age=0` at
the root
- Cargo: add an `[[allow.exact]]` entry to `cooldown.toml` with a comment
naming the advisory and the date it can be removed
+9 -8
View File
@@ -1,8 +1,8 @@
# Contributing
This repository holds two projects, each with its own development guide:
`explorer/README.md` and `desktop/README.md`. This file covers what
applies to both.
`explorer/README.md` and `desktop/README.md`, and the UI code they share in
`shared/ui/`. This file covers what applies to all of them.
* Before adding any code dependencies, check with the maintainers if this is okay.
* Write properly formatted comments: they should be english sentences, eg:
@@ -31,9 +31,10 @@ When proposing changes via a patch:
Both projects only install releases that are at least 7 days old, to give
the ecosystem time to catch compromised packages. npm enforces this through
`min-release-age` in each project's `.npmrc`; Cargo through its
`cooldown.toml`, which needs `cargo install cargo-cooldown cargo-audit`.
From the project's directory:
`min-release-age` in the root `.npmrc`; Cargo through each project's
`cooldown.toml`, which needs `cargo install cargo-cooldown cargo-audit`. npm
commands cover the whole workspace from anywhere in it; run Cargo commands
from the project's directory:
```sh
npm audit
@@ -46,8 +47,8 @@ Use `cargo cooldown update` rather than `cargo update`, which ignores the
cooldown, and avoid `npm audit fix --force`, which takes major-version bumps.
When a security fix is still cooling down and can't wait, review the release's
diff against the previous version first. Then install it with
`npm install <pkg>@<version> --min-release-age=0`, or allow it in
diff against the previous version first. Then install it at the root with
`npm install <pkg>@<version> -w <project> --min-release-age=0`, or allow it in
`cooldown.toml` with an `[[allow.exact]]` entry and a comment naming the
advisory and the date it can be removed.
@@ -107,7 +108,7 @@ filters can tell the projects apart:
| `httpd` | `explorer/crates/radicle-httpd/` and `explorer/crates/radicle-search/` |
A patch that touches several components gets several labels. Changes to
shared files (`.github/`, `.buildkite/`, `.ryph/`, root docs) get the labels
shared files (`shared/`, `.github/`, `.buildkite/`, `.ryph/`, root files) get the labels
of the components they affect. `git push` can't set labels, so add them
once the patch is open:
+5 -1
View File
@@ -7,8 +7,12 @@ publishing stack.
[radicle.network][app], with the `radicle-httpd` and `radicle-search`
backends it talks to.
* [`desktop/`](desktop/README.md): the desktop app.
* [`shared/ui/`](shared/ui/AGENTS.md): UI components, design tokens and fonts
used by both.
Each project is built, tested and released on its own; see its README. The
One npm workspace at the root holds all three: install the dependencies there,
with `npm ci -w explorer` or `npm ci -w desktop` for a single app. Each app is
built, tested and released on its own; see its README. The
guidelines for contributing to either are in [CONTRIBUTING.md](CONTRIBUTING.md),
and decisions that affect the whole repository are in [`docs/adr/`](docs/adr/).
+6 -4
View File
@@ -4,10 +4,12 @@ Tauri desktop app for Radicle. Svelte 5 frontend communicates with a Rust
backend via Tauri IPC commands. TypeScript types are generated from Rust structs
using ts-rs (`crates/radicle-types/`).
The app lives in `desktop/` of the radicle-gui monorepo. It is its own npm
package and Cargo workspace: run every command here from `desktop/`, and all
paths in this file are relative to it. Conventions shared with explorer are in
the root `AGENTS.md`.
The app lives in `desktop/` of the radicle-gui monorepo. It is a package in the
root npm workspace and its own Cargo workspace: install npm dependencies at the
repository root with `npm ci -w desktop`, and run every other command here from
`desktop/`. All paths in this file are relative to it. Conventions shared with
explorer are in the root `AGENTS.md`, and UI code shared with it lives in
`shared/ui/`.
## Svelte syntax and aliases
+5 -3
View File
@@ -4,7 +4,8 @@ This desktop application lets you interact with [Radicle][rad], a peer-to-peer
code collaboration and publishing stack.
It lives in the `desktop/` folder of the radicle-gui repository, next to the
Radicle web explorer. Run all commands below from `desktop/`.
Radicle web explorer. Install dependencies at the repository root, and run all
other commands below from `desktop/`.
## Installation
@@ -29,8 +30,9 @@ Run the following commands to build the desktop app locally:
```
git clone https://seed.radicle.dev/z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git radicle-gui
cd radicle-gui/desktop
npm install
cd radicle-gui
npm ci -w desktop
cd desktop
npm run tauri build
```
+6 -4
View File
@@ -3,10 +3,12 @@
The Svelte web app for browsing Radicle repositories, its TypeScript HTTP
client, and the `radicle-httpd` and `radicle-search` backends it talks to.
The project lives in `explorer/` of the radicle-gui monorepo. It is its own npm
package and Cargo workspace: run every command here from `explorer/`, and all
paths in this file are relative to it. Conventions shared with desktop are in
the root `AGENTS.md`.
The project lives in `explorer/` of the radicle-gui monorepo. It is a package in
the root npm workspace and its own Cargo workspace: install npm dependencies at
the repository root with `npm ci -w explorer`, and run every other command here
from `explorer/`. All paths in this file are relative to it. Conventions shared
with desktop are in the root `AGENTS.md`, and UI code shared with it lives in
`shared/ui/`.
## Checks and linting (tsc, svelte-check, eslint, prettier)
+7 -5
View File
@@ -4,8 +4,8 @@ This user interface lets you interact with [Radicle][rad], a peer-to-peer code
collaboration and publishing stack, directly from your web browser.
It lives in the `explorer/` folder of the radicle-gui repository, next to the
[Radicle desktop app](../desktop/README.md). Run all commands below from
`explorer/`.
[Radicle desktop app](../desktop/README.md). Install dependencies at the
repository root, and run all other commands below from `explorer/`.
**Deployment Options:**
@@ -24,8 +24,9 @@ Run the following commands to access the web UI locally:
```shell
git clone https://seed.radicle.dev/z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git radicle-gui
cd radicle-gui/explorer
npm install
cd radicle-gui
npm ci -w explorer
cd explorer
npm start
```
@@ -37,7 +38,8 @@ There are several ways to deploy the UI publicly. Here are two common options:
**Using your own web server:**
1. Run `npm install && npm build` to create a build for deployment
1. Run `npm ci -w explorer` at the repository root, then `npm run build` in
`explorer/` to create a build for deployment
2. Configure your web server to serve the contents of the `/build` directory
**Using Vercel (or similar static file hosting):**
+83
View File
@@ -0,0 +1,83 @@
# @radicle-gui/ui
UI code shared by explorer and desktop: Svelte components in `components/`,
TypeScript helpers in `lib/`, and the design tokens, stylesheets and fonts in
`public/`. Desktop is the source we extract shared code from.
The package lives in `shared/ui/` of the radicle-gui monorepo, in the root npm
workspace: install dependencies at the repository root with `npm ci`, and run
every other command here from `shared/ui/`. All paths in this file are
relative to it. Conventions shared with both apps are in the root `AGENTS.md`.
## Rules
- Don't import `@tauri-apps/*`, `@bindings`, `@http-client` or anything else
from one app. Components take plain props, and each app adapts its own data
to them
- Write components with current Svelte 5 APIs: runes, callback props and
snippets. Explorer still uses legacy syntax and migrates to Svelte 5
incrementally: when it adopts an extracted component, update the explorer
components that use it to runes too, rather than shaping the shared
component around legacy syntax
- Import within the package with relative paths. The apps import it as
`@radicle-gui/ui/components/<Name>.svelte` and `@radicle-gui/ui/lib/<name>`
- Declare every package the shared code uses at runtime in `package.json`,
with `svelte` as a peer dependency, and ask before adding one
## Component API
Shared components take data in and report changes out. They can offer rich
interactions such as editing, but the app owns all data and I/O.
- Props are plain data in types defined in `lib/types.ts`, never an app's
types, stores or class instances
- Writes are callback props such as `onEdit?: (body: string) => Promise<void>`.
When a callback is absent, the component leaves out that control, which is
how explorer gets the read-only version
- Callbacks may return a promise: the component shows its own pending and
error states while the app does the actual work
- Anything app-specific comes in as a snippet or a string, such as an `href` or
a link snippet. Components never navigate on their own
- State that only the component cares about, such as whether a menu is open or
an unsaved draft, may be internal or `$bindable`. Everything else is passed
in, and never fetched, cached or persisted by the component
- No side effects: no `fetch`, `invoke`, `localStorage`, `location`, polling or
app context. Context defined in this package, such as the theme, is fine
- Style only with scoped CSS and the shared design tokens
ESLint enforces the import and global restrictions.
## Prop types
Both apps' types come from heartwood, through different serializations, and
should converge over time. Keep shared types small so that this doesn't churn
the components:
- Ask only for the fields a component uses: `UserAvatar` takes a `did`, not a
whole author
- Name and shape shared types after heartwood's types, not either app's. Where
the apps differ, such as explorer's author `id` and desktop's `did`, follow
heartwood
- Define them in `lib/types.ts`, named after domain concepts such as `Author`
or `Reaction`. The first extraction that needs a domain type creates the
file
- Apps pass their own objects when the shapes match, and map them in one place
where they don't. Never import an app's types here
## Stylesheets and fonts
The `sharedPublic()` Vite plugin in `vite.ts` serves `public/` at each app's
root URL in dev and adds it to their builds. The apps link the stylesheets in
`index.html` with `vite-ignore`, so Vite doesn't look for them in the app's
own `public/`. Don't add files at paths an app's own `public/` already uses.
## Checks and tests
```sh
npm run check # svelte-check, eslint, prettier
npm run format # auto-fix prettier and eslint issues
npm run test:unit
```
CI runs these in `.github/workflows/shared-ui.yml`. A change here affects both
apps, so also run explorer's `npm run check` and desktop's `npm run check-js`.