pnpm side effects cache not compatible with Cypress postinstall script

[MikeMcC399]

Issue

pnpm implements a side-effects-cache that uses and caches the results of (pre/post)-install hooks. This does not work if the effects of running the hook are outside the package's module. This is the case for the Cypress postinstall hook which installs the Cypress binary in a separate cache location (see Binary cache). pnpm believes that it is unnecessary to run the Cypress postinstall hook and skips it if the Cypress npm module is already present in the pnpm store cache.

This is not documented on https://docs.cypress.io/ and it is only briefly referred to on https://pnpm.io/settings#sideeffectscache.

This can cause Cypress to report the error:

The cypress npm package is installed, but the Cypress binary is missing.

Suggestion

Add configuration and troubleshooting information for the pnpm side effects cache.

Ideally pnpm would convert to consistently support using pnpm-workspace.yaml, so that Cypress could recommend using:

pnpm config set side-effects-cache false --location project
pnpm --allow-build cypress add --save-dev cypress

There are however multiple related issues (see below) concerning configuration and pnpm 10.x is still evolving in this respect.

I will hold back before attempting to submit any documentation change PRs for this.

Related issues

• postinstall script not run if project restored pnpm/pnpm#9123
• postinstall not run after config set side-effects-cache in 10.7.0 and above pnpm/pnpm#9394
• config set writes to pnpm-workspace.yaml pnpm/pnpm#9396
• --allow-build still writes onlyBuiltDependencies to package.json pnpm/pnpm#9399

[MikeMcC399]

pnpm@10.8.1, released Apr 14, 2025 has resolved several configuration issues, so this Cypress documentation enhancement can now be moved forward.

[MikeMcC399]

• PR extend pnpm config instructions #6149 is submitted to add the side effects cache instructions to the installation configuration
• A separate PR will follow to add related troubleshooting steps

[MikeMcC399]

The main part of this issue is resolved through PR #6149

https://docs.cypress.io/app/get-started/install-cypress#pnpm-Configuration

Troubleshooting should be handled separately if necessary.