chore: manage dependencies with pnpm

.github/workflows/angular-smoke.yml

@@ -24,25 +24,29 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # Must come BEFORE setup-node: `cache: pnpm` shells out to `pnpm store path`.
+      - uses: pnpm/action-setup@v4
+
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
-          cache: npm
+          node-version: 22
+          cache: pnpm
 
       - name: Install monorepo deps
-        # Remove the lockfile before installing to sidestep npm's cross-platform
-        # optional-dependency bug (npm/cli#4828): a lockfile generated on macOS makes
-        # npm skip the Linux rollup native binary tsup/rollup need on the runner.
-        # A fresh install resolves the correct platform binaries.
-        run: |
-          rm -f package-lock.json
-          npm install --no-audit --no-fund
+        # No workaround needed any more: the npm/cli#4828 hack that lived here
+        # (rm -f package-lock.json) existed because a macOS-generated lockfile
+        # made npm skip the Linux rollup binary. pnpm records every platform
+        # variant and filters at install time.
+        run: pnpm install --frozen-lockfile
 
       - name: Build @studiolxd/xapi
-        run: npm run build --workspace=packages/xapi
+        run: pnpm --filter @studiolxd/xapi run build
 
       - name: Pack the built library into the fixture
-        run: npm pack --workspace=packages/xapi --pack-destination tests/angular-smoke
+        # Deliberately `npm pack`, not `pnpm pack`: the smoke test must validate
+        # the very artefact `npm publish` will produce.
+        working-directory: packages/xapi
+        run: npm pack --pack-destination ../../tests/angular-smoke
 
       - name: Install the Angular fixture (Angular 17 + the packed tarball)
         working-directory: tests/angular-smoke

.github/workflows/ci.yml

@@ -1,7 +1,7 @@
 name: CI
 
 # Consolidates the ci.yml that used to live in packages/xapi/.github. GitHub
-# Actions only reads .github/workflows from the repository ROOT, so it never
+# Actions only reads .github/workflows from the repository root, so it never
 # ran: typecheck, tests and builds were not validated by CI at all.
 
 on:
@@ -20,31 +20,34 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [20, 22]
+        node-version: [22, 24]
 
     steps:
       - uses: actions/checkout@v4
 
+      # Must come BEFORE setup-node: `cache: pnpm` shells out to `pnpm store path`.
+      - uses: pnpm/action-setup@v4
+
       - uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: npm
+          cache: pnpm
 
-      - run: npm ci
+      - run: pnpm install --frozen-lockfile
 
       - name: Typecheck (library)
-        run: npm run typecheck --workspace=packages/xapi
+        run: pnpm run typecheck
 
       - name: Test (library)
-        run: npm run test:run --workspace=packages/xapi
+        run: pnpm run test
 
       - name: Build (library)
-        run: npm run build --workspace=packages/xapi
+        run: pnpm run build
 
       - name: Lint (example)
-        run: npm run lint --workspace=example
+        run: pnpm run lint:example
 
       # After the library build: the example resolves @studiolxd/xapi through
       # the workspace, whose `exports` point at dist/.
       - name: Build (example)
-        run: npm run build --workspace=example
+        run: pnpm run build:example

AGENTS.md

@@ -7,7 +7,7 @@ monorepo. For how to *use* the published library, see `packages/xapi/llms.txt`.
 
 `@studiolxd/xapi` — a framework-agnostic xAPI (Experience API / Tin Can) client,
 supporting xAPI 1.0.3 and xAPI 2.0 (IEEE 9274.1.1), against any standard LRS.
-npm workspaces monorepo:
+pnpm workspaces monorepo:
 
 - `packages/xapi/` — the published library (`@studiolxd/xapi`).
   - `src/` core is **framework-agnostic** (no framework imports outside `src/react`,
@@ -21,13 +21,18 @@ npm workspaces monorepo:
 
 ## Commands (run from repo root)
 
-- `npm run build` — build the library.
-- `npm run test` — run the library test suite (vitest).
-- `npm run dev:example` — run the demo at http://localhost:5173.
-- Per-package: `npm run typecheck --workspace=packages/xapi`.
+- `pnpm run build` — build the library.
+- `pnpm run test` — run the library test suite (vitest).
+- `pnpm run dev:example` — run the demo at http://localhost:5173.
+- Per-package: `pnpm --filter @studiolxd/xapi run typecheck`.
 
 Always run `typecheck` + `test:run` + `build` in `packages/xapi` before committing.
 
+Dependencies are managed with **pnpm**; publishing still goes out with `npm publish`
+from `packages/xapi`. `tests/angular-smoke/` is deliberately outside the workspace
+and installed with npm — it stands in for a real downstream consumer. Never run
+`npm install` at the repo root.
+
 ## Conventions
 
 - **TypeScript strict.** Every public symbol has JSDoc, ideally with an `@example`.

README.md

@@ -17,15 +17,15 @@ interactive demo app.
 ## Getting Started
 
 ```bash
-npm install          # install all workspaces from the root
-npm run dev:lib      # build the library in watch mode
-npm run dev:example  # start the example dev server (http://localhost:5173)
+pnpm install         # install all workspaces from the root
+pnpm run dev:lib     # build the library in watch mode
+pnpm run dev:example # start the example dev server (http://localhost:5173)
 ```
 
 Additional scripts available from the root:
 
-- `npm run build` — builds the library
-- `npm run test` — runs the library test suite
+- `pnpm run build` — builds the library
+- `pnpm run test` — runs the library test suite
 
 ## Entry points
 
@@ -45,7 +45,7 @@ The library is a single package with subpath exports — import only what you us
 
 ```
 xapi/
-├── package.json          # npm workspaces root (private)
+├── package.json          # pnpm workspaces root (private)
 ├── AGENTS.md              # guidance for AI coding agents working in this repo
 ├── PLAN.md                 # design / implementation spec
 ├── packages/

example/package.json

@@ -10,7 +10,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@studiolxd/xapi": "*",
+    "@studiolxd/xapi": "workspace:*",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },

example/vercel.json

@@ -1,5 +1,5 @@
 {
-  "installCommand": "cd .. && npm install --no-package-lock --legacy-peer-deps && npm run build",
-  "buildCommand": "npm run build",
+  "installCommand": "cd .. && pnpm install --frozen-lockfile && pnpm --filter @studiolxd/xapi run build",
+  "buildCommand": "pnpm run build",
   "outputDirectory": "dist"
 }