@capgo/capacitor-patch

@capgo/capacitor-patch is a hook-only Capacitor package that applies selected patch files whenever Capacitor runs sync or update.

It is built for fixes that are useful before they land in an official Capacitor release. The bundled catalog tracks external upstream Capacitor PRs mirrored by Capacitor+ sync/upstream-pr-* branches.

Note

This package has no native runtime API. It works through Capacitor hooks, npm package files, and generated native project files.

What it patches

Capacitor packages

Patch @capacitor/core, @capacitor/android, @capacitor/ios, and third-party Capacitor plugins under node_modules.

Capacitor CLI

Patch shipped CLI JavaScript files. When a CLI patch is applied, the next cap command uses the patched code.

Native projects

Apply generated Android or iOS project patches after cap sync or cap update.

Safe selection

Version ranges, idempotency checks, and strict mode help prevent stale patches from applying silently.

Patch catalog

Patches are opt-in by default. List the shipped catalog, pick the patch IDs your app needs, and add them to plugins.CapacitorPatch.patches.

Each catalog entry includes:

• a stable patch ID
• the target package or native project phase
• supported version range
• the upstream Capacitor PR
• the matching Capacitor+ sync branch
• the patch file shipped with the package

Why use it

Use @capgo/capacitor-patch when:

• a Capacitor fix exists upstream but has not shipped yet
• your app needs the fix without maintaining local patch scripts
• you want patches to re-apply after every Capacitor sync/update
• you need a team-readable catalog of the fixes your app depends on

For a full catalog and contribution guide, see the capacitor-patch repository.