ci: deploy docs via Workers Builds with pnpm workspace (#263)

Author: dimitropoulos

.github/workflows/deploy-docs.yml

@@ -12,16 +12,20 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 1
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
       - uses: actions/setup-node@v6
         with:
           node-version: "24"
-          cache: "npm"
+          cache: "pnpm"
 
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       - name: Build packages
-        run: npm run build
+        run: pnpm run build
 
       - name: Publish to pkg.pr.new
-        run: npx pkg-pr-new publish . ./packages/*
+        run: pnpm exec pkg-pr-new publish . ./packages/capnweb-validate

.github/workflows/pkg-pr-new.yml

@@ -24,14 +24,17 @@ jobs:
         with:
           fetch-depth: 1
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
       - uses: actions/setup-node@v6
         with:
           node-version: "24" # includes npm 11.5.1 or later, needed for trusted publishing
-          cache: "npm"
+          cache: "pnpm"
 
-      - run: npm ci
+      - run: pnpm install --frozen-lockfile
       # we explicitly run here because changesets might not be running the build step https://github.com/changesets/changesets/issues/860#issuecomment-1316398728
-      - run: npm run build
+      - run: pnpm run build
 
       - id: changesets
         uses: changesets/action@v1
@@ -40,7 +43,7 @@ jobs:
           # split on whitespace and then passed directly to execvp(). Hence the need to indirect
           # through a shell script, ugh. :(
           version: ./.github/changeset-version.sh
-          publish: npx changeset publish
+          publish: pnpm exec changeset publish
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -63,7 +66,7 @@ jobs:
             exit 1
           fi
 
-          gh workflow run cla.yml --ref "$head_ref" -f "pull_request=${PR_NUMBER}"
+          gh workflow run cla.yml --ref "$head_ref" --raw-field "pull_request=${PR_NUMBER}"
 
   prerelease:
     if: ${{ github.event.workflow_run.conclusion == 'success' && github.repository_owner == 'cloudflare' }}
@@ -76,15 +79,18 @@ jobs:
         with:
           fetch-depth: 1
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
       - uses: actions/setup-node@v6
         with:
           node-version: "24" # includes npm 11.5.1 or later, needed for trusted publishing
-          cache: "npm"
+          cache: "pnpm"
 
-      - run: npm ci
-      - run: npm run build
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
 
       - name: Modify package.json version
-        run: npx tsx .github/version-script.ts
+        run: pnpm exec tsx .github/version-script.ts
 
-      - run: npm publish --workspaces --include-workspace-root --tag beta
+      - run: pnpm publish --recursive --filter capnweb --filter capnweb-validate --tag beta --access public --no-git-checks

.github/workflows/preview-docs.yml

@@ -15,60 +15,51 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
           node-version: "24"
-          cache: "npm"
+          cache: "pnpm"
 
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       - name: Lint Markdown
-        run: npm run lint:md
+        run: pnpm run lint:md
 
-  # The docs site is deployed from main by deploy-docs.yml, so without this the
-  # first place its build ever runs is the deploy. Fail it on the pull request
-  # instead.
+  # Production deploys via Workers Builds. Fail the docs build on the PR rather
+  # than discovering it only after merge.
   build-docs:
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v7
         with:
-          # Same full history the deploy uses. Each page's "Updated" date comes from
-          # `git log -1 --format=%at <file>`, and in a shallow clone that resolves to
-          # the one commit that was fetched -- so every page would claim to have been
-          # updated at the same moment, and this job would be checking a build that is
-          # not the one main deploys.
+          # Same full history production builds use. Each page's "Updated" date
+          # comes from `git log -1 --format=%at <file>`, and in a shallow clone
+          # that resolves to the one commit that was fetched.
           fetch-depth: 0
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
           node-version: "24"
-          cache: "npm"
-          # packages/docs is excluded from the workspaces and the React example's
-          # client is its own install, so both have lockfiles the root one does not
-          # cover.
-          cache-dependency-path: |
-            package-lock.json
-            packages/docs/package-lock.json
-            examples/worker-react/client/package-lock.json
-
-      # The docs build bundles each example's real source, so the React example's
-      # client needs its own node_modules for esbuild to resolve react out of.
+          cache: "pnpm"
+
       - name: Install dependencies
-        run: |
-          npm ci
-          npm ci --prefix packages/docs
-          npm ci --prefix examples/worker-react/client
+        run: pnpm install --frozen-lockfile
 
       - name: Build docs
-        run: npm run build:docs
+        run: pnpm --filter capnweb-docs build
 
       - name: Check docs
-        run: npm --prefix packages/docs run check
+        run: pnpm --filter capnweb-docs check
 
   test:
     runs-on: ubuntu-latest
@@ -79,23 +70,26 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
           node-version: "24"
-          cache: "npm"
+          cache: "pnpm"
 
       - name: Setup Bun
-        run: npm install -g bun
+        run: npm install --global bun
 
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       - name: Build project
-        run: npm run build
+        run: pnpm run build
 
       - name: Run tests
-        run: npm run test:ci
+        run: pnpm run test:ci
 
       - name: Run type tests
-        run: npm run test:types
+        run: pnpm run test:types

.github/workflows/release.yml

@@ -0,0 +1,3 @@
+# This repo only depends on public @cloudflare packages. Override any local
+# npmrc that maps the scope to an internal registry so installs work everywhere.
+@cloudflare:registry=https://registry.npmjs.org

.github/workflows/test.yml

@@ -156,7 +156,7 @@ Guides and reference:
 To run the site locally, with both examples embedded as live in-browser playgrounds:
 
 ```sh
-cd packages/docs && npm install && npm run dev
+pnpm install && pnpm run dev:docs
 ```
 
 ## Examples