Installation Failure in pnpm Monorepo due to docusaurus-openapi-docs Transitive Dependency (postman-code-generators)

[winstonknippenberg]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

When adding the docusaurus-openapi-docs plugin to a Docusaurus site within a pnpm-managed monorepo, the pnpm install command fails. The failure is not in Docusaurus itself, but is caused by a transitive dependency, postman-code-generators, which is pulled in by docusaurus-openapi-docs to generate code snippets.  

The postman-code-generators package contains a postinstall script that attempts to run yarn to install its own sub-dependencies. This creates a fundamental conflict when pnpm is the package manager, as two different package managers try to manage the node_modules directory simultaneously. This leads to a race condition, filesystem instability, and ultimately causes the installation to crash with an Error: Callback was already called from the async library.  

.../node_modules/postman-code-generators postinstall$ node npm/deepinstall.js
│ Detected package manager: yarn
│...
│ Failed to run yarn install on codegen csharp-httpclient, here is the error:
│...
│ Error: Callback was already called.
│ at /path/to/project/node_modules/.pnpm/async@3.2.2/node_modules/async/dist/async.js...
└─ Failed in... at /path/to/project/node_modules/.pnpm/postman-code-generators@1.14.2/node_modules/postman-code-generators
ELIFECYCLE Command failed with exit code 1.
Root Cause and Ecosystem Impact:
The core issue lies with the design of the postman-code-generators package, which executes a different package manager within its installation script—an anti-pattern that is incompatible with pnpm's strict dependency management.  

Reproducible demo

No response

Steps to reproduce

Steps to Reproduce:

1. Set up a new monorepo managed by pnpm.

2. Scaffold a new Docusaurus site within the monorepo (pnpm create docusaurus).

3. Add the docusaurus-openapi-docs package as a dependency to the Docusaurus site.

4. Run pnpm install from the root of the monorepo.

Expected behavior

The pnpm install command should complete successfully, installing all dependencies for the Docusaurus site and the docusaurus-openapi-docs plugin.

Actual behavior

The installation fails during the postinstall script execution for postman-code-generators. The error log shows the script attempting to run yarn, followed by a fatal error:

Your environment

• Docusaurus version used: 3.8.1
• Plugin: docusaurus-plugin-openapi-docs: ^4.5.1
• node 20
• pnpm 9.9.0

Self-service

• I'd be willing to fix this bug myself.

[slorber]

It's not really a bug for this repo. We don't maintain the openapi plugin nor the postman code generator package.

Looks like there's already a bug open in the relevant repo: postmanlabs/postman-code-generators#792