postinstall running "npx husky install" breaks `npm i -g docsify-cli` for consumers

[rantoniuk]

Title

postinstall running npx husky install breaks npm i -g docsify-cli for consumers

Body

Describe the bug

docsify@5.0.0's package.json ships:

"postinstall": "opencollective-postinstall && npx husky install"

postinstall runs for every installer of the package, not just contributors working in this repo. Since docsify-cli depends on docsify: ^5.0.0, this now runs on every npm i -g docsify-cli as well, and can abort the whole install if npx husky install fails for any reason (see repro below). husky install only makes sense when hacking on the docsify/docsify-cli monorepo itself — it should not run for someone installing the CLI as an end user.

This regressed with the docsify-cli → monorepo merge in #2277: docsify@4.x only ever had "postinstall": "opencollective-postinstall" (which is comparatively harmless — it just prints a donation nag). npx husky install was added for v5 and is what's newly breaking installs.

To Reproduce

npm i -g docsify-cli

On my machine this fails with:

npm error code 254
npm error path .../node_modules/docsify-cli/node_modules/docsify
npm error command failed
npm error command sh -c opencollective-postinstall && npx husky install
npm error npm warn exec The following package was not found and will be installed: husky@9.1.7
npm error npm error code ENOENT
npm error npm error syscall open
npm error npm error path /Users/<me>/.npm/_npx/<hash>/package.json
npm error npm error enoent Could not read package.json: Error: ENOENT: no such file or directory, open '/Users/<me>/.npm/_npx/<hash>/package.json'

The proximate crash is an unrelated npx package-cache issue (a stale/corrupted entry under ~/.npm/_npx), but the underlying design bug is that npx husky install — and by extension any dev-only setup step — should never be reachable from a consumer's global/local npm install at all. Even without the npx cache issue, running husky install outside of a git checkout of this repo is meaningless and just adds a fragile network/exec dependency to every install of docsify.

Expected behavior

npm i -g docsify-cli (and npm i docsify) should install without attempting to run husky install. Installing docsify as a dependency should never invoke husky.

Workarounds found

• npm i -g docsify-cli --ignore-scripts
• rm -rf ~/.npm/_npx && npm i -g docsify-cli (works around the npx cache issue, but husky install still needlessly runs)
• Pin to docsify-cli@4.4.4, the last release depending on docsify@^4.12.2 (pre-husky postinstall)

Suggested fix

Move the husky setup to prepare and gate it so it's skipped for non-dev installs (npm already skips prepare scripts for packages installed as a dependency, but as a small extra safety net most projects also use something like pinst to no-op postinstall/prepare at publish time, or check process.env.CI/INIT_CWD before running). Husky's own docs recommend prepare over postinstall for exactly this reason: typicode/husky#884

Environment

• docsify 5.0.0
• docsify-cli 5.0.0
• npm 11.19.0 / node 24.19.0
• macOS

Related

• Bring docsify-cli into this repo for easier development. #2277 (docsify-cli merged into this repo — likely where the monorepo's husky postinstall leaked into the published package)
• docsify-cli#140 (older, same class of bug: a postinstall script — back then opencollective-postinstall — aborting npm i -g docsify-cli)