Use `pnpm patch` for a Temporary Dependency Fix You Can Reproduce

A patch should explain why an upgrade is not enough

Sometimes a dependency bug blocks a release and no fixed version is available. pnpm's patch workflow can edit a package copy and save a reproducible patch in the repository. This is preferable to manually editing node_modules, where the change disappears on the next install and cannot be reviewed.

Start with pnpm patch package-name@version, make the smallest correction in the temporary directory, and finish with pnpm patch-commit. Review the resulting patch file and lockfile changes. The patch should not include unrelated formatting or generated artifacts.

Test the consumer contract

Add a test that fails without the patch and passes with it. Run the affected package's test suite and at least one consumer integration path. A patch that only avoids an error message but changes behavior may create a harder regression later.

Record the upstream issue or pull request, the affected package version, and what event permits removal: a released version, a specific fixed commit, or a verified compatibility range. Check the patch during dependency upgrades because a context-free patch can stop applying or become unnecessary.

Do not use patches as a substitute for maintaining a long-lived fork when the change is large or security-sensitive. Keep the patch visible in code review and ensure CI installs from a clean checkout. If the patch is required for every install, a clean CI run is the proof that it is part of the dependency contract rather than a local accident.

Keep the patch focused and reviewable

Before patching, reproduce the defect with the dependency version that the lockfile actually installs. Write a regression test or minimal failing example, and check whether a supported configuration option or upstream fixed release already exists. A local patch is justified when it closes a concrete gap while an upgrade or upstream release is unavailable; it should not carry an undocumented fork indefinitely.

Make the smallest source change possible and inspect the generated patch file line by line. Remove editor metadata, build output, and unrelated formatting. If the dependency ships compiled files, determine whether the patch should target source, generated output, or both, and document the build process that keeps them consistent. A patch that modifies a minified bundle without a reproducible source change is difficult to maintain and review.

Test installation and removal as part of the fix

Run a clean install from a fresh checkout to confirm the patch is applied automatically. Then run the regression test, the dependency's relevant test suite if available, and one consumer path. Check that the patch applies to the exact locked version and does not silently affect a different version after an update. If it stops applying, fail the build rather than skipping it and continuing with broken behavior.

Track the upstream issue, affected version, local rationale, and removal condition near the patch or in a linked issue. During an upgrade, re-evaluate whether the upstream release contains the fix; do not carry an obsolete patch just because it still applies. Security-sensitive or broad changes deserve a maintained fork with a release process instead of a long patch file. A patch is healthy when its scope is small, its behavior is tested, and the team knows who will remove it and when.

Review the patch whenever the dependency version changes, even if the patch still applies cleanly. A context match does not prove the behavior remains correct. Keep a clean-checkout job that fails when the patch is skipped or the expected regression test is absent. This makes the temporary repair part of a visible dependency contract rather than a hidden mutation of one developer's node_modules.

If the patch becomes large, touches security boundaries, or needs repeated conflict resolution, stop and evaluate a maintained fork or an upstream contribution. The low ceremony of a patch is useful only while its ownership remains clear. A named removal issue and a test that demonstrates the original defect keep that decision honest.

Keep patch files free of generated bundles and editor metadata, and review them whenever the locked dependency changes. If the patch cannot be applied in a clean checkout, fail loudly instead of silently installing the unpatched package. That failure is preferable to a green build whose runtime behavior depends on one developer's modified installation.