From de7d03fa20cbb732d36c5f00d92737764ec5aeca Mon Sep 17 00:00:00 2001
From: Chris Campbell <ccampbell@climateinteractive.org>
Date: Fri, 4 Sep 2026 10:07:17 -0700
Subject: [PATCH] deps: make puppeteer a peer dependency

Puppeteer is only used for generating PDF files, and most projects that use
docs-builder already have their own puppeteer dependency (for running e2e
tests), so declare it as a peer dependency and let those projects choose the
version.
---
 examples/sample-docs/package.json    | 3 ++-
 packages/docs-builder/README.md      | 9 +++++++++
 packages/docs-builder/package.json   | 7 +++++--
 packages/docs-builder/src/gen-pdf.ts | 5 +++++
 pnpm-lock.yaml                       | 9 ++++++---
 5 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/examples/sample-docs/package.json b/examples/sample-docs/package.json
index 97cdd26..d1c8796 100644
--- a/examples/sample-docs/package.json
+++ b/examples/sample-docs/package.json
@@ -10,6 +10,7 @@
     "ci:build": "run-s clean build"
   },
   "devDependencies": {
-    "@climateinteractive/docs-builder": "workspace:*"
+    "@climateinteractive/docs-builder": "workspace:*",
+    "puppeteer": "^25.10.0"
   }
 }
diff --git a/packages/docs-builder/README.md b/packages/docs-builder/README.md
index d9291bd..842447c 100644
--- a/packages/docs-builder/README.md
+++ b/packages/docs-builder/README.md
@@ -27,6 +27,15 @@ Once the `.npmrc` file is updated, you can install the package the usual way:
 npm install @climateinteractive/docs-builder
 ```
 
+Note that PDF files are generated using [Puppeteer](https://pptr.dev), which is
+declared as a peer dependency so that your project can control which version is
+used (many projects already depend on Puppeteer for end-to-end tests), so you
+will need to install it alongside `docs-builder`:
+
+```sh
+npm install --save-dev puppeteer
+```
+
 ## Usage
 
 ### Command Line
diff --git a/packages/docs-builder/package.json b/packages/docs-builder/package.json
index 21d0f79..1c3ea78 100644
--- a/packages/docs-builder/package.json
+++ b/packages/docs-builder/package.json
@@ -48,16 +48,19 @@
     "open": "^11.0.2",
     "postcss": "^8.5.6",
     "postcss-rtlcss": "^5.7.1",
-    "puppeteer": "^25.10.0",
     "rev-hash": "^3.0.0",
     "semver-compare": "^1.0.0",
     "sirv": "^3.0.2",
     "tinyglobby": "^0.2.15"
   },
+  "peerDependencies": {
+    "puppeteer": ">=24.0.0"
+  },
   "devDependencies": {
     "@types/lunr": "^2.3.4",
     "@types/marked": "^4.0.1",
-    "@types/node": "^22.20.1"
+    "@types/node": "^22.20.1",
+    "puppeteer": "^25.10.0"
   },
   "author": "Climate Interactive",
   "license": "MIT",
diff --git a/packages/docs-builder/src/gen-pdf.ts b/packages/docs-builder/src/gen-pdf.ts
index fb296c0..cb65141 100644
--- a/packages/docs-builder/src/gen-pdf.ts
+++ b/packages/docs-builder/src/gen-pdf.ts
@@ -7,6 +7,11 @@ import puppeteer from 'puppeteer'
 
 import type { Context } from './context'
 
+/**
+ * Generate a PDF file from the complete HTML page for the project.
+ *
+ * @param context The language-specific context.
+ */
 export async function writePdfFile(context: Context): Promise<void> {
   // Launch a headless browser instance
   const browser = await puppeteer.launch({ headless: true })
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4111b3a..e183e25 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -47,6 +47,9 @@ importers:
       '@climateinteractive/docs-builder':
         specifier: workspace:*
         version: link:../../packages/docs-builder
+      puppeteer:
+        specifier: ^25.10.0
+        version: 25.10.0
 
   packages/docs-builder:
     dependencies:
@@ -83,9 +86,6 @@ importers:
       postcss-rtlcss:
         specifier: ^5.7.1
         version: 5.7.1(postcss@8.5.6)
-      puppeteer:
-        specifier: ^25.10.0
-        version: 25.10.0
       rev-hash:
         specifier: ^3.0.0
         version: 3.0.0
@@ -108,6 +108,9 @@ importers:
       '@types/node':
         specifier: ^22.20.1
         version: 22.20.1
+      puppeteer:
+        specifier: ^25.10.0
+        version: 25.10.0
 
 packages: