Sometimes we need to patch node_modules
that are not in our control in order to fix bugs or add features. There are a few ways to do this:
- Fork the package to the
cypress-io
org and install via Git hash - Re-publish a patched version under the
@cypress
org on NPM - Patch the package using the
patch-package
utility on install/build
In most cases, it is best to use patch-package
. Using patch-package
has a number of advantages over #1 and #2:
patch-package
avoids the need for maintaining yet another repo ornpm/
packagepatch-package
avoids the need for keeping version numbers/Git hashes synced inpackage.json
/yarn.lock
in the monorepopatch-package
makes it easy to review changes in the context of a single PR to thecypress
repo, as opposed to having to review changes in 2+ repospatch-package
side-steps a bug in Yarn that causes extremely confusing behavior when installing/caching Git dependencies
The only times where we cannot use patch-package
is if we need to make a patch that is not included in the binary. The cli
and npm/
packages have their transitive dependencies installed by the user's package manager, so we cannot use patch-package
to patch them.
For example: @cypress/request
is used in the CLI, so we maintain a separate NPM package.
Also, we cannot include Git dependencies (#1) in any NPM packages, because not all users can install Git dependencies: #6752
If your patch is general purpose, you should submit a PR to the dependency's repo and create an issue in the cypress
repo that tracks your upstream PR.
Once your upstream PR is merged, we can bump the version of the patched module in the monorepo and remove the patch, along with associated maintenance burden.
All patches require tests.
Along with regular unit/integration/etc. tests against unbuilt Cypress, there should be at least one test for the patch that uses the built version of Cypress. This prevents regressions from a patch not being applied as expected when we build Cypress.
You can add a test for your patch against the built binary in a couple of ways:
- Create a
binary-system-test
that tests that the patched behavior is correct in the built binary. - Add an expectation to
scripts/binary/util/testStaticAssets.js
that asserts the patch is applied. - Add some other test that runs against the built binary in CI.