The Patch Was Small. The Package Manager Was the Architecture

A build watcher kept following tool directories and rebuilding a Figma plugin for changes that had nothing to do with the plugin.

The dependency needed a tiny patch: ignore .trunk, .remember, and .claude.

The interesting decision was not how to write that diff. It was how to make the repository's existing package manager own it.

patch-package is a familiar answer in many npm and Yarn repositories. This project already used pnpm, which had its own patch lifecycle. Adding a second patching system would have created overlapping machinery without adding a missing capability (more tools, same tiny diff).

A patch file becomes durable only when the active installation path registers and reapplies it.

The bug was outside the application source

The project built with @create-figma-plugin/build 4.0.3. Its watcher could traverse tool-owned directories near the repository root. Those directories changed for reasons unrelated to application development, so the build restarted unnecessarily.

The required dependency edit was small. The durable workflow was the real design choice.

Editing node_modules could prove the change but could not preserve it. A separate post-install script would add another custom application path. Adding patch-package would introduce a second patching system beside the canonical pnpm-lock.yaml flow.

The repository already had a native mechanism: pnpm's patchedDependencies.

Use the package manager's patch lifecycle

The pnpm patch documentation defines a two-step workflow:

pnpm patch "@create-figma-plugin/build@4.0.3"
# Edit the extracted temporary copy.
pnpm patch-commit <temporary-directory>

pnpm patch creates an editable copy. pnpm patch-commit generates the patch file and registers it through patchedDependencies.

In the current repository, that registration lives in pnpm-workspace.yaml, while pnpm-lock.yaml records the patch hash. The patch itself adds watcher exclusions for the three tool directories.

Those three artifacts form one contract:

pnpm-workspace.yaml registration
  -> patches/@create-figma-plugin__build@4.0.3.patch
  -> pnpm-lock.yaml patch hash

Moving only the patch file is incomplete. Editing only the manifest without regenerating the lockfile is incomplete too.

“The file exists” is the wrong verification

It is easy to review a patch, see the intended lines, and declare the dependency fixed.

That verifies content, not application.

For a dependency patch, I want evidence from a clean installation path:

1. The manifest registers the exact package and version.
2. The lockfile contains the corresponding patch hash.
3. A fresh pnpm install applies the patch without an unused-patch error.
4. The installed dependency contains the expected change.
5. The original failing behavior no longer occurs.

The fifth step matters most. A watcher patch is successful when editing .trunk, .remember, or .claude no longer triggers the plugin rebuild, while editing actual source still does.

If both changes are ignored, the watcher is broken. If both cause rebuilds, the patch is not effective. The test needs one positive and one negative event.

Match the tool to the lockfile

Dependency patching is not a generic text-file feature. The patch mechanism needs to know which package instance it targets, when to apply the diff, and how to encode the result in the reproducible install graph.

That ownership belongs to the active package manager.

Before adding a patching dependency, inspect the repository:

• pnpm-lock.yaml points to pnpm's patch workflow.
• yarn.lock requires checking the Yarn version and its supported patch mechanism.
• package-lock.json may justify a different tool.

Do not install a familiar tool until you know the current one lacks the capability. In this case, adding patch-package would have created overlapping machinery for a problem pnpm already solved.

Patch the smallest surface and keep an exit condition

The patch changes a dependency's watcher exclusions. It does not fork the entire build tool or replace its file-watching stack.

That makes the patch reviewable, but it still creates maintenance work. The exact dependency version is part of the patch key. An upgrade must recheck whether the upstream package fixed the behavior, whether the diff still applies, and whether the exclusions remain appropriate.

The ideal future for a dependency patch is deletion.

Until then, make the package manager own it, make the lockfile prove it, and make the original behavior test it.

Otherwise, code review can prove that the diff looks correct while leaving the installation contract unexamined (a very tidy half-result).