chore: migrate npm to pnpm across CI, Docker, and scripts (#555)

Author: Anshumancanrock

.changeset/bright-clocks-jam.md

@@ -0,0 +1,5 @@
+---
+"nostream": patch
+---
+
+Migrate project tooling from npm to pnpm across CI workflows, Docker setup, hooks, and contributor commands.

.github/workflows/changesets.yml

@@ -21,21 +21,23 @@ jobs:
         with:
           fetch-depth: 0
 
+      - uses: pnpm/action-setup@v4
+
       - uses: actions/setup-node@v3
         with:
           node-version-file: .nvmrc
-          cache: npm
+          cache: pnpm
 
       - name: Install package dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       - run: git config user.name "github-actions[bot]"
       - run: git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
       - name: Create Release Pull Request
         uses: changesets/action@v1
         with:
-          version: npm run changeset:version
+          version: pnpm run changeset:version
           createGithubReleases: true
           title: "chore: release new version 🚀"
           commit: "chore: version packages"

.github/workflows/checks.yml

@@ -20,12 +20,13 @@ jobs:
         uses: actions/checkout@v3
         with:
           fetch-depth: 0
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v3
         with:
           node-version-file: .nvmrc
-          cache: npm
+          cache: pnpm
       - name: Install package dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: Run commitlint
         uses: wagoid/commitlint-github-action@v5
   lint:
@@ -34,30 +35,32 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v3
         with:
           node-version-file: .nvmrc
-          cache: npm
+          cache: pnpm
       - name: Install package dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: Run Biome
-        run: npm run lint
+        run: pnpm run lint
       - name: Run Knip
-        run: npm run knip
+        run: pnpm run check:deps
   build-check:
     name: Build check
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v3
         with:
           node-version-file: .nvmrc
-          cache: npm
+          cache: pnpm
       - name: Install package dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: Run build check
-        run: npm run build:check
+        run: pnpm run build:check
   test-units-and-cover:
     name: Unit Tests And Coverage
     runs-on: ubuntu-latest
@@ -68,16 +71,17 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v3
         with:
           node-version-file: .nvmrc
-          cache: npm
+          cache: pnpm
       - name: Install package dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: Run unit tests
-        run: npm run test:unit
+        run: pnpm run test:unit
       - name: Run coverage for unit tests
-        run: npm run cover:unit
+        run: pnpm run cover:unit
         if: ${{ always() }}
       - uses: actions/upload-artifact@v4
         name: Upload coverage report for unit tests
@@ -103,11 +107,12 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v3
         with:
           node-version-file: .nvmrc
       - name: Run integration tests
-        run: npm run docker:test:integration
+        run: pnpm run docker:test:integration
       - name: Generate Cucumber report annotations
         uses: deblockt/cucumber-report-annotations-action@v1.7
         if: ${{ always() }}
@@ -116,7 +121,7 @@ jobs:
           access-token: ${{ secrets.GITHUB_TOKEN }}
           path: .test-reports/integration/report.json
       - name: Run coverage for integration tests
-        run: npm run docker:cover:integration
+        run: pnpm run docker:cover:integration
       - name: Coveralls
         uses: coverallsapp/github-action@master
         if: ${{ always() }}
@@ -151,11 +156,12 @@ jobs:
         uses: actions/checkout@v3
         with:
           fetch-depth: 0
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v3
         with:
           node-version-file: .nvmrc
-          cache: npm
+          cache: pnpm
       - name: Install package dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: Check for changeset
-        run: npx changeset status --since origin/${{ github.base_ref }}
+        run: pnpm exec changeset status --since origin/${{ github.base_ref }}

.gitignore

@@ -13,12 +13,15 @@ npm-debug.log*
 
 # Dependency directories
 node_modules/
+package-lock.json
 
 # TypeScript cache
 *.tsbuildinfo
 
-# Optional npm cache directory
+# Optional package manager cache directories
 .npm
+.pnpm-store
+pnpm-debug.log*
 
 # Caches
 .eslintcache

.husky/commit-msg

@@ -1,4 +1,4 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-npx --no -- commitlint --edit ${1}
+pnpm exec commitlint --edit "${1}"

.husky/pre-commit

@@ -1,6 +1,6 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-npm run lint
-npm run build:check
-npm run test:unit
+pnpm run lint
+pnpm run build:check
+pnpm run test:unit

CONFIGURATION.md

@@ -94,16 +94,16 @@ The schema ships with a small, query-driven set of indexes. The most important o
 Run the read-only benchmark against your own database to confirm the planner is using the expected indexes and to record baseline latencies:
 
 ```sh
-npm run db:benchmark
-npm run db:benchmark -- --runs 5 --kind 1 --limit 500
+pnpm db:benchmark
+pnpm db:benchmark --runs 5 --kind 1 --limit 500
 ```
 
 The `db:benchmark` script loads the local `.env` file automatically (via `node --env-file-if-exists=.env`), using the same `DB_HOST`/`DB_PORT`/`DB_USER`/`DB_PASSWORD`/`DB_NAME` variables as the relay. The benchmark issues only `EXPLAIN (ANALYZE, BUFFERS)` and `SELECT` statements — it never writes. Flags: `--runs <n>` (default 3), `--kind <n>` (default 1 / `TEXT_NOTE`; pass `0` for SET_METADATA), `--limit <n>` (default 500), `--horizon-days <n>` (default 7), `--help`.
 
 For a full before/after proof of the index impact (seeds a throwaway dataset, drops and recreates the indexes, and prints a BEFORE/AFTER table), use:
 
 ```sh
-npm run db:verify-index-impact
+pnpm db:verify-index-impact
 ```
 
 The hot-path index migration (`20260420_120000_add_hot_path_indexes.js`) uses `CREATE INDEX CONCURRENTLY`, so it can be applied to a running relay without taking `ACCESS EXCLUSIVE` locks on the `events` or `invoices` tables.

CONTRIBUTING.md

@@ -43,7 +43,8 @@ cd nostream
 Install dependencies (this also sets up Husky pre-commit hooks automatically):
 
 ```
-npm install
+corepack enable
+pnpm install
 ```
 
 > **Important:** Pre-commit hooks installed by Husky run linting and formatting checks on every
@@ -96,7 +97,7 @@ SECRET=aaabbbccc...dddeeefff
 Run migrations (at least once and after pulling new changes):
 
 ```
-NODE_OPTIONS="-r dotenv/config" npm run db:migrate
+pnpm db:migrate
 ```
 
 Create the `.nostr` folder and copy the default settings file:
@@ -109,19 +110,19 @@ cp resources/default-settings.yaml .nostr/settings.yaml
 Start in development mode:
 
 ```
-npm run dev
+pnpm dev
 ```
 
 Or start in production mode:
 
 ```
-npm run start
+pnpm start
 ```
 
 To clean up build, coverage, and test reports:
 
 ```
-npm run clean
+pnpm clean
 ```
 
 ## Tests
@@ -131,10 +132,10 @@ npm run clean
 Run code quality checks with Biome:
 
 ```
-npm run lint
-npm run lint:fix
-npm run format
-npm run format:check
+pnpm lint
+pnpm lint:fix
+pnpm format
+pnpm check:format
 ```
 
 ### Unit tests
@@ -148,19 +149,19 @@ cd /path/to/nostream
 Run unit tests:
 
 ```
-npm run test:unit
+pnpm test:unit
 ```
 
 Run unit tests in watch mode:
 
 ```
-npm run test:unit:watch
+pnpm test:unit:watch
 ```
 
 Get unit test coverage:
 
 ```
-npm run cover:unit
+pnpm cover:unit
 ```
 
 Open the unit test report:
@@ -186,13 +187,13 @@ cd /path/to/nostream
 Run integration tests:
 
 ```
-npm run docker:test:integration
+pnpm docker:test:integration
 ```
 
 Get integration test coverage:
 
 ```
-npm run docker:cover:integration
+pnpm docker:cover:integration
 ```
 
 ### Integration tests (Standalone)
@@ -222,7 +223,7 @@ DB_MAX_POOL_SIZE=2
 Run the integration tests:
 
 ```
-npm run test:integration
+pnpm test:integration
 ```
 
 Open the integration test report:
@@ -234,7 +235,7 @@ open .test-reports/integration/report.html
 Get integration test coverage:
 
 ```
-npm run cover:integration
+pnpm cover:integration
 ```
 
 Open the integration test coverage report:
@@ -252,7 +253,7 @@ event flood (spam) attacks. This is used to verify relay resilience and prevent
 
 ```bash
 # Simulates 5,000 idle "zombie" connections + 100 events/sec spam
-npm run test:load -- --zombies 5000 --spam-rate 100
+pnpm test:load --zombies 5000 --spam-rate 100
 ```
 
 ### Analyzing Memory (Heap Snapshots)
@@ -299,10 +300,10 @@ To observe client and subscription counts in real-time during a test, you can in
 Run dead code and dependency analysis before opening a pull request:
 
 ```
-npm run knip
+pnpm check:deps
 ```
 
-`npm run lint` now runs Biome.
+`pnpm lint` now runs Biome.
 
 ## Pull Request Process
 
@@ -323,7 +324,7 @@ Every pull request that changes behavior, adds a feature, or fixes a bug **must
 To add a changeset:
 
 ```bash
-npx changeset
+pnpm exec changeset
 ```
 
 This interactive prompt will ask you to:
@@ -338,7 +339,7 @@ If your PR **only** updates documentation, CI/CD configuration, or test coverage
 production source code untouched — an empty changeset is acceptable:
 
 ```bash
-npx changeset --empty
+pnpm exec changeset --empty
 ```
 
 Commit the generated `.changeset/*.md` file with your PR. This satisfies CI without producing a
@@ -362,6 +363,6 @@ This applies to PRs that exclusively contain:
 Run Biome checks before opening a pull request:
 
 ```
-npm run lint
-npm run format:check
+pnpm lint
+pnpm check:format
 ```