Evaluating rush monorepo build tool for TS

.github/workflows/build.yml

@@ -33,22 +33,32 @@ jobs:
           path: dev-docs/output
           key: dev-docs-build-${{ steps.cache-key.outputs.git-hash }}
 
-      - name: Setup pnpm
-        if: steps.cache-dev-docs-build.outputs.cache-hit != 'true'
-        uses: pnpm/action-setup@v4
-
       - name: Setup NodeJS
         if: steps.cache-dev-docs-build.outputs.cache-hit != 'true'
         uses: actions/setup-node@v4
         with:
           node-version: 24
-          cache: "pnpm"
+
+      - name: Cache Rush install
+        if: steps.cache-dev-docs-build.outputs.cache-hit != 'true'
+        uses: actions/cache@v4
+        with:
+          path: |
+            common/temp/install-run
+            ~/.rush
+          key: rush-${{ runner.os }}-${{ hashFiles('rush.json', 'common/config/rush/pnpm-lock.yaml') }}
+          restore-keys: |
+            rush-${{ runner.os }}-
+
+      - name: Install Rush CLI
+        if: steps.cache-dev-docs-build.outputs.cache-hit != 'true'
+        run: npm install -g @microsoft/rush
 
       - name: Build developer docs
         if: steps.cache-dev-docs-build.outputs.cache-hit != 'true'
         run: |
-          pnpm install
-          pnpm --filter ./dev-docs run doc
+          rush install
+          rush doc --to dev-docs --only dev-docs
 
       - name: Report cache status
         run: |
@@ -92,16 +102,26 @@ jobs:
             packages/frontend/dist
           key: frontend-build-${{ steps.cache-key.outputs.git-hash }}-${{ github.event_name == 'release' && 'production' || 'staging' }}
 
-      - name: Setup pnpm
-        if: github.event_name == 'release' || steps.cache-frontend-build.outputs.cache-hit != 'true'
-        uses: pnpm/action-setup@v4
-
       - name: Setup NodeJS
         if: github.event_name == 'release' || steps.cache-frontend-build.outputs.cache-hit != 'true'
         uses: actions/setup-node@v4
         with:
           node-version: 24
-          cache: "pnpm"
+
+      - name: Cache Rush install
+        if: github.event_name == 'release' || steps.cache-frontend-build.outputs.cache-hit != 'true'
+        uses: actions/cache@v4
+        with:
+          path: |
+            common/temp/install-run
+            ~/.rush
+          key: rush-${{ runner.os }}-${{ hashFiles('rush.json', 'common/config/rush/pnpm-lock.yaml') }}
+          restore-keys: |
+            rush-${{ runner.os }}-
+
+      - name: Install Rush CLI
+        if: github.event_name == 'release' || steps.cache-frontend-build.outputs.cache-hit != 'true'
+        run: npm install -g @microsoft/rush
 
       - name: Install Rust toolchain from file
         if: github.event_name == 'release' || steps.cache-frontend-build.outputs.cache-hit != 'true'
@@ -110,21 +130,26 @@ jobs:
           # Don't override flags in cargo config files.
           rustflags: ""
 
-      - name: Build for Staging
+      - name: Rush install
+        if: github.event_name == 'release' || steps.cache-frontend-build.outputs.cache-hit != 'true'
+        run: rush install
+
+      - name: Build all dependencies of frontend
+        if: github.event_name == 'release' || steps.cache-frontend-build.outputs.cache-hit != 'true'
+        # `--to-except` selects everything frontend depends on but excludes frontend itself.
+        run: rush build --to-except frontend
+
+      - name: Build frontend for Staging
         if: (github.event_name == 'push' || github.event_name == 'pull_request') && steps.cache-frontend-build.outputs.cache-hit != 'true'
-        run: |
-          pnpm install
-          pnpm --filter ./packages/frontend run build:deps
-          # Uses env from packages/frontend/.env.staging
-          pnpm --filter ./packages/frontend run build:staging
+        # Uses env from packages/frontend/.env.staging
+        run: rushx --quiet build:staging
+        working-directory: packages/frontend
 
-      - name: Build for Production
+      - name: Build frontend for Production
         if: github.event_name == 'release'
-        run: |
-          pnpm install
-          pnpm --filter ./packages/frontend run build:deps
-          # Uses env from packages/frontend/.env.production
-          pnpm --filter ./packages/frontend run build
+        # Uses env from packages/frontend/.env.production
+        run: rushx --quiet build
+        working-directory: packages/frontend
 
       - name: Report cache status
         run: |
@@ -151,8 +176,7 @@ jobs:
 
       - name: Build frontend docs
         if: steps.cache-frontend-docs.outputs.cache-hit != 'true'
-        run: |
-          pnpm --filter ./packages/frontend run doc
+        run: rush doc --to frontend --only frontend
 
       - name: Report frontend docs cache status
         run: |
@@ -332,24 +356,34 @@ jobs:
           path: packages/ui-components/storybook-static
           key: ui-components-${{ steps.cache-key.outputs.git-hash }}
 
-      - name: Setup pnpm
-        if: steps.cache-ui-components.outputs.cache-hit != 'true'
-        uses: pnpm/action-setup@v4
-
       - name: Setup NodeJS
         if: steps.cache-ui-components.outputs.cache-hit != 'true'
         uses: actions/setup-node@v4
         with:
           node-version: 24
-          cache: "pnpm"
 
-      - name: Install dependencies
+      - name: Cache Rush install
+        if: steps.cache-ui-components.outputs.cache-hit != 'true'
+        uses: actions/cache@v4
+        with:
+          path: |
+            common/temp/install-run
+            ~/.rush
+          key: rush-${{ runner.os }}-${{ hashFiles('rush.json', 'common/config/rush/pnpm-lock.yaml') }}
+          restore-keys: |
+            rush-${{ runner.os }}-
+
+      - name: Install Rush CLI
+        if: steps.cache-ui-components.outputs.cache-hit != 'true'
+        run: npm install -g @microsoft/rush
+
+      - name: Rush install
         if: steps.cache-ui-components.outputs.cache-hit != 'true'
-        run: pnpm install
+        run: rush install
 
       - name: Build ui-components Storybook
         if: steps.cache-ui-components.outputs.cache-hit != 'true'
-        run: pnpm --filter ./packages/ui-components run build
+        run: rush build --to catcolab-ui-components --only catcolab-ui-components
 
       - name: Report cache status
         run: |

.github/workflows/ci.yml

@@ -88,23 +88,34 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-
       - name: Setup NodeJS
         uses: actions/setup-node@v4
         with:
           node-version: 24
-          cache: "pnpm"
 
-      - name: Install dependencies
-        run: pnpm install
+      - name: Cache Rush install
+        uses: actions/cache@v4
+        with:
+          path: |
+            common/temp/install-run
+            ~/.rush
+          key: rush-${{ runner.os }}-${{ hashFiles('rush.json', 'common/config/rush/pnpm-lock.yaml') }}
+          restore-keys: |
+            rush-${{ runner.os }}-
+
+      - name: Install Rush CLI
+        run: npm install -g @microsoft/rush
+
+      - name: Rush install
+        run: rush install
 
       - name: Install Playwright browser
-        run: pnpm --filter ./packages/ui-components exec playwright install chromium
+        run: ./node_modules/.bin/playwright install chromium
+        working-directory: packages/ui-components
 
       - name: Run ui-components tests
-        run: pnpm --filter ./packages/ui-components run test
+        run: rushx --quiet test
+        working-directory: packages/ui-components
 
   npm_checks:
     name: npm checks
@@ -113,29 +124,38 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-
       - name: Setup NodeJS
         uses: actions/setup-node@v4
         with:
           node-version: 24
-          cache: "pnpm"
 
-      - name: Install NodeJS dependencies
-        run: |
-          pnpm install
+      - name: Cache Rush install
+        uses: actions/cache@v4
+        with:
+          path: |
+            common/temp/install-run
+            ~/.rush
+          key: rush-${{ runner.os }}-${{ hashFiles('rush.json', 'common/config/rush/pnpm-lock.yaml') }}
+          restore-keys: |
+            rush-${{ runner.os }}-
+
+      - name: Install Rush CLI
+        run: npm install -g @microsoft/rush
+
+      - name: Rush install
+        run: rush install
 
       - name: Install Rust toolchain from file
         uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
           # Don't override flags in cargo config files.
           rustflags: ""
 
-      - name: Format/linting/import sorting
-        run: |
-          pnpm --filter "./packages/*" run build:deps
-          pnpm --filter "./packages/*" run ci
+      - name: Build dependencies (wasm, bindings, CSS modules)
+        run: rush build
+
+      - name: Run per-project CI checks (lint, format, typecheck)
+        run: rush ci
 
   build_nixos_system:
     name: build NixOS system
@@ -167,9 +187,6 @@ jobs:
       - name: Install Rust toolchain from file
         uses: actions-rust-lang/setup-rust-toolchain@v1
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-
       - name: Run dev setup
         run: |
             docker run --name catcolab-postgres -e POSTGRES_USER=catcolab -e POSTGRES_PASSWORD=password -e POSTGRES_DB=catcolab -p 5432:5432 -d postgres:15

.gitignore

@@ -112,3 +112,10 @@ CHANGELOG.html
 
 # VSCode
 .vscode/*
+
+# Rush
+common/deploy/
+common/temp/
+common/autoinstallers/*/.npmrc
+**/.rush/temp/
+

CONTRIBUTING.md

@@ -22,23 +22,30 @@ CatColab is written in a mix of [Rust](https://www.rust-lang.org/) and
 [TypeScript](https://www.typescriptlang.org/). To start any development, the first steps are
 
 1. install Rust (say, by using [rustup](https://rustup.rs/))
-2. install [pnpm](https://pnpm.io/)
+2. install [Node.js](https://nodejs.org/) 22 or newer (the Nix devShell does this for you)
 3. clone the [CatColab repository](https://github.com/ToposInstitute/CatColab)
 
+TypeScript dependencies and the build graph are managed by [Rush](https://rushjs.io/).
+Rush invokes pnpm under the hood. If you use the Nix devShell (`nix develop`)
+both `rush` and `rushx` are on your `PATH`; otherwise install Rush globally
+(`npm install -g @microsoft/rush`).
+
 ### General development
 
 "Most" development will likely only require changes to the **core** (`catlog`) and the **frontend** (`frontend`) (and thus also the **bindings** in `catlog-wasm`). For this, you can simply follow the instructions in the [`frontend` docs](https://next.catcolab.org/dev/frontend/), replacing `$MODE` by `staging`, i.e. running
 
 ```
-pnpm run dev --mode staging
+rush install
+rush build --to-except frontend
+cd packages/frontend && rushx dev --mode staging
 ```
 
 to view any changes made.
 
 If you are getting a `Cannot find module @... or its corresponding type declarations.` error then you should try running
 
 ```
-pnpm install
+rush install
 ```
 
 to install/update the npm packages.
@@ -55,8 +62,9 @@ code formatting and style. To format and lint the frontend code, run these
 commands from the top-level directory:
 
 ```sh
-pnpm --filter ./packages/frontend run format
-pnpm --filter ./packages/frontend run lint
+cd packages/frontend
+rushx format
+rushx lint
 ```
 
 To format and lint the Rust code, run these commands from the top-level directory:

common/config/rush/.npmrc

@@ -0,0 +1,11 @@
+# Rush-managed .npmrc used by `rush install` and friends.
+# Mirror the project-root .npmrc so behaviour matches the legacy pnpm workspace.
+
+# Match the pnpm-workspace.yaml `minimumReleaseAge` setting (9 days, in minutes).
+minimum-release-age=12960
+
+# Match Rush's pnpm-config.json so the lockfile generated by `rush update`
+# can be consumed by raw `pnpm install` (e.g. inside Nix).
+auto-install-peers=false
+strict-peer-dependencies=false
+resolution-mode=highest

common/config/rush/.npmrc-publish

@@ -0,0 +1,4 @@
+# .npmrc used by `rush publish`. CatColab does not publish to a registry, but
+# Rush expects this file to exist.
+registry=https://registry.npmjs.org/
+always-auth=false