How to Check Ionic and Capacitor Plugin Compatibility

Inventory implementations, wrappers and usage

Start with the installed dependency tree, lockfile and native projects. For each feature, identify the native implementation and any wrapper used by application code. An @awesome-cordova-plugins wrapper and a cordova-plugin-* implementation are separate packages with separate constraints.

npm ls --depth=0
npx cap ls
rg '@capacitor/|@awesome-cordova-plugins/|@ionic-native/|cordova' src

Run against your trusted project using the installed CLI. Search output is incomplete evidence: dynamic calls and native-only usage may not appear in JavaScript imports. Include custom plugins, local packages, Git dependencies, forks and plugins only used in production paths.

Use a worksheet with columns for feature, implementation/version, wrapper/version, target runtime, Android result, iOS result, evidence URL, required action and runtime test. A single green status for both platforms conceals platform-specific gaps.

Read exact-release metadata, not only the latest README

For a public package, inspect its released metadata before installing it:

# Example public package and version; substitute your actual release.
npm view @capacitor/camera@8.0.0 peerDependencies engines repository --json

This queries the registry and sends a package name/version; it does not upload source or execute the plugin. Do not use this public query for an internal package name. Alternatively, inspect the installed package manifest locally.

npm's package metadata reference defines peer dependencies and engines. Compare the peer range with the target core/framework version, and check optional peers. An absent range means no declared constraint; an open-ended range means the maintainer allowed that range. Neither is a native test result.

Read the changelog for the exact release, not a README on an unreleased default branch. Identify removed methods, response-shape changes and permission changes used by your app. Record the source and version alongside the conclusion.

Apply different evidence checks to each plugin family

Official Capacitor plugins

Use the relevant versioned API documentation and migration notes. Review changed application call sites, permission configuration and native requirements even when the major matches core. “Official” describes maintenance; it does not certify your integration.

Third-party Capacitor plugins

Look for a target-version support statement, peer metadata and release notes. Inspect Android Gradle dependencies and the iOS podspec or Package.swift. If you maintain a fork, the Capacitor 8 plugin-author migration guide is a useful diff checklist, not permission to assume an upstream package already migrated.

Cordova plugins

Review plugin.xml, platform source, configuration expectations and the official incompatible-plugin list. Apply the retain/replace/remove review before treating a JavaScript wrapper as an upgrade path.

Check the native constraint intersection

A plugin can accept the npm version while its native dependency rejects the app's toolchain. On Android, inspect minimum/compile SDK requirements, Java/Kotlin targets, AGP assumptions, Maven dependencies and manifest entries. Compare them with the chosen Capacitor 8 toolchain.

On iOS, check deployment targets, Swift dependencies, CocoaPods/SPM support, entitlements and usage descriptions. Include app extensions if they use the same library. Check whether a replacement changes stored data, callback ordering or background behavior. These are project-level investigations, not conclusions obtainable from a peer range.

Classify evidence without overstating it

Compatible within a stated scope

The exact release has support evidence for the target stack, constraints intersect and your relevant checks passed. Say whether evidence is documented, build-verified or runtime-verified, and name the platform. Do not generalize beyond it.

Incompatible

A documented exclusion, unsatisfied required range, removed API in use or reproduced failure blocks the selected combination. Record the blocker and whether another release resolves it.

Unknown

The target combination has insufficient evidence. Missing peer metadata or no target-version release is a research gap, not automatic incompatibility.

Manual review

The integration needs a human decision or device test: a fork, custom native code, ambiguous documentation, data migration or a permission-sensitive workflow. This is an action flag; it can coexist with a known build result.

Example: a peer range that excludes core 8 is a documented package mismatch. A broad range with no native testing is unknown. A plugin that builds on Android but has not been exercised on iOS has separate evidence for those platforms, not blanket compatibility.

Treat inactivity as maintenance risk

Inspect release cadence, archived status, open upgrade issues, maintainer responses and CI evidence. A recent commit can be a documentation edit; an old stable plugin can still work. Neither age nor popularity decides compatibility.

For an abandoned package, decide who will own future platform updates and permission/API changes. If nobody can maintain the integration, evaluate replacement scope now. For a maintained fork, document what differs from upstream and how it will be tested.

Prove the integration you actually ship

1. Resolve dependencies and build the web application without hiding conflicts.
2. Sync the native projects and inspect what was added, changed or skipped.
3. Build both platforms with the selected toolchains.
4. Test real call paths on devices: grant/deny permissions, return from background and exercise failure callbacks.
5. Test an upgrade installation where the plugin owns persistent data or identifiers.

Keep a short result per plugin with version, platform, test and remaining uncertainty. This is the useful output of an audit: a list of justified actions and unresolved items. Carry it into the migration readiness plan.