mirror of
https://seed.radicle.dev/rad:z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git
synced 2026-11-21 14:20:42 +08:00
Document the npm workspace and shared/ui
This commit is contained in:
@@ -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
@@ -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:
|
||||
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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):**
|
||||
|
||||
@@ -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`.
|
||||
Reference in New Issue
Block a user