fix(cli): lazy-load @puppeteer/browsers to prevent debug package crash (#1185)

* fix(cli): lazy-load @puppeteer/browsers to prevent debug package crash

Convert the static `import { ... } from "@puppeteer/browsers"` in
browser/manager.ts to dynamic imports inside the async functions that
use them. This eliminates a module-load-time crash when the transitive
`debug` dependency is missing or corrupted.

Previously, every CLI command (including init, lint, docs, help) would
crash with "Cannot find package debug" if the debug package was absent —
even though only browser-related commands need @puppeteer/browsers.

Also add `debug` as a direct dependency so npm/bun always installs it
explicitly rather than relying on transitive resolution.

PostHog data: ~3,955 total-CLI-crash occurrences since May 29.

* fix(cli): simplify isLinuxArm to sync inline check and surface real load error

isLinuxArm() was async only to call detectBrowserPlatform() from
@puppeteer/browsers, but that function just checks process.platform +
process.arch under the hood. Replace with a direct inline check and make
the function sync — no behavioral change, removes an unnecessary async
boundary and an eager load of the package we're trying to lazy-load.

Also surface the real error from loadPuppeteerBrowsers() catch block instead
of hard-coding 'likely missing transitive dependency "debug"' — the actual
cause could be anything (missing package, corrupt install, wrong Node ABI).
This commit is contained in:
Miguel Ángel
2026-06-03 22:53:16 -04:00
committed by GitHub
parent cabd0616ea
commit 8c6faa45b5
4 changed files with 32 additions and 10 deletions
+4
View File
@@ -99,6 +99,10 @@
// dynamic require() resolution, peer/static-file consumption in tests,
// and bun-hoisted workspace devDeps (e.g. happy-dom in root package.json
// resolves for every workspace, so workspaces don't redeclare it).
// Required by @puppeteer/browsers and puppeteer-core at runtime; listed
// as a direct dep to guarantee installation even when transitive
// resolution fails (corrupted cache, dedup edge cases).
"debug",
"puppeteer",
"puppeteer-core",
"esbuild",