Getting Started

Copy a setup prompt with the install steps and the full markdown guide for this plugin.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-patch`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/capacitor-patch/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Install

npm install @capgo/capacitor-patch
npx cap sync

The package is a no-op until you select patches in your Capacitor config.

Select patch IDs

List all shipped patches:

npx capgo-capacitor-patch list --all

Then add the patch IDs your app needs to capacitor.config.ts:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  plugins: {
    CapacitorPatch: {
      patches: ['upstream-pr-8418-android'],
      strict: true,
    },
  },
};

export default config;

Run sync again:

npx cap sync

Package patches run before sync and update. Native project patches run after sync and update.

Dry-run before applying

Use doctor to check whether selected patches match your installed package versions:

npx capgo-capacitor-patch doctor --phase package --strict

Use apply when you want to run the selected patches manually:

npx capgo-capacitor-patch apply --phase package

Configuration options

Option	Type	Default	Description
`recommended`	`boolean`	`false`	Applies patches Capgo marks as recommended.
`patches`	`string[]`	`[]`	Applies explicit patch IDs.
`disabled`	`string[]`	`[]`	Skips selected patch IDs, even when recommended.
`strict`	`boolean`	`false`	Throws when a selected patch is incompatible or cannot apply.

CLI commands

npx capgo-capacitor-patch list --all
npx capgo-capacitor-patch doctor
npx capgo-capacitor-patch apply

Useful options:

--root <dir> sets the app root.
--phase package|native|all limits which patch phase runs.
--platform ios|android applies platform filtering outside a Capacitor hook.
--strict treats selected patch failures as errors.

Workflow

Install @capgo/capacitor-patch.
Run npx capgo-capacitor-patch list --all.
Add the selected patch IDs to plugins.CapacitorPatch.patches.
Run npx capgo-capacitor-patch doctor --strict.
Run npx cap sync.

When a selected patch targets @capacitor/cli, the patch applies to the installed CLI package and the next cap command uses the patched CLI code.