Skip to content

Fix Generate Pages Script Deps - #245

Merged
aaparent merged 1 commit into
mainfrom
iman/generate-pages-hangs
Aug 3, 2026
Merged

Fix Generate Pages Script Deps#245
aaparent merged 1 commit into
mainfrom
iman/generate-pages-hangs

Conversation

@ihassanein

Copy link
Copy Markdown
Contributor

I investigated why it seemed to hang when generating pages.

David also had this issue last week, and mentioned scraper version 4.0.900 worked for them, so I started there. It does work, but I wasn't happy leaving it since 4.0.900 is about 35 releases behind, and pinning just means we're frozen until someone remembers to bump it. It also didn't explain anything, so we'd walk into the same wall on the next @latest bump.

I got Claude to walk through the versions to find where it breaks using the same conditions for each back to back.
The result was:

  • 4.0.921 installs in ~25s and generates pages in ~3s
  • 4.0.922 never finishes installing (killed at 5 minutes)

The only difference between those two releases is @mintlify/common went 1.0.1056 -> 1.0.1057, which bumped @mintlify/mdx from 3.0.4 -> 4.0.1. @mintlify/mdx 4.0.1 added peerDependencies on react, react-dom and
@base-ui/react. npm 7+ installs peer deps automatically... which is what was breaking. So basically, npm would never finish and we would never get to the good part (scraping).

openapi-file just reads a local JSON spec. It doesn't touch any of the React stuff, so we don't need to resolve those peers. So again with Claude we added export NPM_CONFIG_LEGACY_PEER_DEPS=true to skip resolving those peers entirely. No pinning needed we can stay on @latest and is only scoped to the script so should not affect anything else.

Claude has some tradeoffs it would like to present that I didn't address in this MR:

## What I checked

Ran the script end to end with the npx cache cleared. Exits 0, and produces the same
pages as the last known good version (76 for v2, 16 for v3, 49 for v4). None of the
existing generated pages changed, so this isn't quietly altering output format.

## Still not fast, and what we could do later

This fixes the hang but not the speed. Cold cache is about 3 minutes, roughly 50s once
npx has things cached, because each of the three calls re-resolves ~600 packages.

`pnpm dlx` does the same job in about 7 seconds and never had this bug, since it handles
peers differently. I didn't switch because it would mean everyone and CI needs pnpm, and
we only use npx today. Easy swap later if we decide the speed is worth it.```

@aaparent
aaparent merged commit 254fd79 into main Aug 3, 2026
6 checks passed
@aaparent
aaparent deleted the iman/generate-pages-hangs branch August 3, 2026 21:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants