chore: switch to pnpm and fix peer dependencies (#345)

A somewhat reoccurring issue has been dependency updates introducing
`peerDependency` misalignment that causes installation / run errors with
tools like `npx`.

Originally I was planning to address this by introducing new CI steps
that checked for this, but instead I've decided to give `pnpm` a go. As
far as I understand it has the strictest rules of the common package
managers around dependency resolution, and therefore if it works with
`pnpm` it'll probably work with everything else.

Making this change surfaced a number of implicit dependency issues
across the repository, and unintentional reliance on `jest` globals.

I'd be fairly keen to additionally do away with the `lerna` dependency,
as its now only used for publishing the packages, but that's probably a
job for another day.

Author: mnahkies

.github/workflows/ci.yml

@@ -21,41 +21,37 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           registry-url: "https://registry.npmjs.org"
           node-version: ${{ matrix.node-version }}
-
-      - uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
-        id: yarn-cache
-        with:
-          path: .yarn
-          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
+          cache: 'pnpm'
 
       - uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
         id: nextjs-cache
         with:
           path: packages/documentation/.next/cache
-          key: ${{ runner.os }}-nextjs-${{ hashFiles('yarn.lock') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
+          key: ${{ runner.os }}-nextjs-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
           restore-keys: |
-            ${{ runner.os }}-nextjs-${{ hashFiles('yarn.lock') }}-
+            ${{ runner.os }}-nextjs-${{ hashFiles('pnpm-lock.yaml') }}-
 
-      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
 
-      - run: yarn --immutable
+      - run: pnpm ci-build
+      - run: pnpm ci-test
+      - run: pnpm ci-lint
 
-      - run: yarn ci-build
-      - run: yarn ci-test
-      - run: yarn ci-lint
+      - run: pnpm install --frozen-lockfile
 
-      - run: yarn integration:generate
-      - run: yarn integration:validate
+      - run: pnpm integration:generate
+      - run: pnpm integration:validate
 
-      - run: yarn e2e:generate
-      - run: yarn e2e:validate
+      - run: pnpm e2e:generate
+      - run: pnpm e2e:validate
 
       - name: Check for uncommitted changes
         run: ./scripts/assert-clean-working-directory.sh
@@ -71,13 +67,13 @@ jobs:
 #        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 #
 #    - name: Publish to NPM
-#      run: echo 'publish release' #yarn lerna publish --no-private --force-publish --yes --conventional-commits
+#      run: echo 'publish release' #pnpm lerna publish --no-private --force-publish --yes --conventional-commits
 #      if: github.ref == 'refs/heads/main'
 #      env:
 #        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 #
 #    - name: Publish to NPM (Alpha)
-#      run: echo 'publish alpha release' #yarn lerna publish --no-private --force-publish --yes --conventional-commits --canary
+#      run: echo 'publish alpha release' #pnpm lerna publish --no-private --force-publish --yes --conventional-commits --canary
 #      if: github.ref != 'refs/heads/main'
 #      env:
 #        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/publish-docs.yml

@@ -42,7 +42,7 @@ jobs:
 
       - run: corepack enable
 
-      - run: yarn --immutable
+      - run: pnpm install --frozen-lockfile
       - run: yarn ci-build
       - name: Publish documentation
         if: github.ref == 'refs/heads/main'

.husky/pre-commit

@@ -1 +1 @@
-yarn lint-staged
+pnpm lint-staged

.yarnrc.yml

@@ -28,7 +28,7 @@ PR with a detailed description is fine too.
    [fnm](https://github.com/Schniz/fnm)
 2. Enable [corepack](https://nodejs.org/api/corepack.html) using `corepack
 enable`
-3. Install `devDependencies` using `yarn`
+3. Install `devDependencies` using `pnpm`
 
 ## Workflow
 
@@ -37,34 +37,34 @@ See [package.json](./package.json) for available scripts.
 Main ones of interest are `build`, `test`, `lint`. E.g:
 
 ```shell
-yarn build
-yarn test
-yarn lint
-yarn format
+pnpm build
+pnpm test
+pnpm lint
+pnpm format
 ```
 
 To regenerate the integration tests:
 
 ```shell
-yarn integration:generate
+pnpm integration:generate
 ```
 
 And to build them / check the code output is valid:
 
 ```shell
-yarn integration:validate
+pnpm integration:validate
 ```
 
 There's also a `ci-pipeline` script that can be used as a pre-push check, e.g:
 
 ```shell
-yarn ci-pipeline && git push --force-with-lease
+pnpm ci-pipeline && git push --force-with-lease
 ```
 
 ## Typescript Conventions
 
 ```shell
-yarn build
+pnpm build
 ```
 
 We strive for robust type safety, both in the library and the code it outputs.
@@ -77,8 +77,8 @@ in the fetch runtime [here][ts-ignore-example]
 ## Linting / Formatting
 
 ```shell
-yarn lint
-yarn format
+pnpm lint
+pnpm format
 ```
 
 We use `biome` for formatting, and linting, largely sticking to the recommended rules.
@@ -87,8 +87,8 @@ The config can be seen here [./biome.json](./biome.json)
 ## Testing
 
 ```shell
-yarn test
-yarn integration:generate && yarn integration:validate
+pnpm test
+pnpm integration:generate && pnpm integration:validate
 ```
 
 We have two types of testing in play:
@@ -123,9 +123,9 @@ assist:
 
 ```shell
 # Publish a pre-release, eg: 0.0.2-alpha.107
-yarn publish:alpha
+pnpm publish:alpha
 # Publish a release, eg: 0.0.1
-yarn publish:release
+pnpm publish:release
 ```
 
 These will build and test before asking for publish confirmation.

CONTRIBUTING.md

@@ -14,14 +14,22 @@
   },
   "dependencies": {
     "@koa/router": "^13.1.1",
-    "@nahkies/typescript-koa-runtime": "*",
+    "@nahkies/typescript-axios-runtime": "workspace:*",
+    "@nahkies/typescript-express-runtime": "workspace:*",
+    "@nahkies/typescript-fetch-runtime": "workspace:*",
+    "@nahkies/typescript-koa-runtime": "workspace:*",
+    "axios": "^1.10.0",
+    "express": "^5.1.0",
     "koa": "^3.0.0",
-    "zod": "^3.25.74"
+    "zod": "3.25.74"
   },
   "devDependencies": {
-    "@nahkies/openapi-code-generator": "*",
+    "@jest/globals": "^30.0.4",
+    "@nahkies/openapi-code-generator": "workspace:*",
+    "@types/express": "^5.0.3",
     "@types/koa": "^2.15.0",
     "@types/koa__router": "^12.0.4",
+    "expect": "^30.0.4",
     "jest": "^30.0.4",
     "typescript": "~5.8.3"
   }

e2e/package.json

@@ -4,23 +4,23 @@ set -e
 
 SCHEMA_BUILDER=zod
 
-yarn openapi-code-generator \
+pnpm openapi-code-generator \
   --input ./openapi.yaml \
   --output ./src/generated/server/koa \
   --template typescript-koa \
   --schema-builder "$SCHEMA_BUILDER" \
   --extract-inline-schemas \
   --grouping-strategy first-tag
 
-yarn openapi-code-generator \
+pnpm openapi-code-generator \
   --input ./openapi.yaml \
   --output ./src/generated/server/express \
   --template typescript-express \
   --schema-builder "$SCHEMA_BUILDER" \
   --extract-inline-schemas \
   --grouping-strategy first-tag
 
-yarn openapi-code-generator \
+pnpm openapi-code-generator \
   --input ./openapi.yaml \
   --output ./src/generated/client/fetch \
   --template typescript-fetch \
@@ -29,7 +29,7 @@ yarn openapi-code-generator \
   --enable-runtime-response-validation \
   --override-specification-title "E2E Test Client"
 
-yarn openapi-code-generator \
+pnpm openapi-code-generator \
   --input ./openapi.yaml \
   --output ./src/generated/client/axios \
   --template typescript-axios \

e2e/scripts/generate.sh

@@ -1,5 +1,5 @@
 import type {Server} from "node:http"
-import {beforeAll, describe, expect, it} from "@jest/globals"
+import {afterAll, beforeAll, describe, expect, it} from "@jest/globals"
 import type {AxiosError} from "axios"
 import {ApiClient} from "./generated/client/axios/client"
 import {E2ETestClientServers} from "./generated/client/fetch/client"

e2e/src/index.axios.spec.ts

@@ -1,5 +1,5 @@
 import type {Server} from "node:http"
-import {beforeAll, describe, expect, it} from "@jest/globals"
+import {afterAll, beforeAll, describe, expect, it} from "@jest/globals"
 import {ApiClient, E2ETestClientServers} from "./generated/client/fetch/client"
 import {startServerFunctions} from "./index"
 import {numberBetween} from "./test-utils"

e2e/src/index.fetch.spec.ts

@@ -2,7 +2,7 @@
   "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
   "version": 1,
   "cli": {
-    "packageManager": "yarn"
+    "packageManager": "pnpm"
   },
   "newProjectRoot": "projects",
   "projects": {