Library Compatibility

Every number Peach publishes about a library answers one question: will this work in my app? This page explains how those numbers are produced, so you can read them correctly, and what to do when a library you depend on is not covered yet.

The per-library data lives on generated pages:

• +
  React Native core APIs
• +
  Essential libraries
• +
  Every scanned library
• +
  Conformance, where each library has a page with its visual proof against a real device

To check your own app, run peach doctor, or drop your package.json or lockfile (bun.lock, package-lock.json or yarn.lock) on the Conformance page.

#What Peach implements, and what runs from your bundle

A library has two halves. Its JavaScript always runs from your bundle, unchanged. Its native half, the Swift, Objective-C, Kotlin or Java code it calls through TurboModules, NativeModules, Expo modules or native views, is what Peach has to implement. A pure JavaScript library has no native half, so it runs as long as React Native itself does, and it never needs a stub.

So library compatibility is a question about native behavior: when your app calls into a library’s native side, does Peach do what the device would do?

#Two measures: implementation and proof

Peach keeps two numbers apart because they answer different halves of that question.

Implementation says how much of a package’s app-facing API surface Peach implements for a given version range. It is the percent you see beside a package in peach doctor and on the Conformance page. It moves when Peach gains or fixes behavior.

Implementation is computed from a feature tree. Each feature of a package is rated for how much real apps use it and how much it matters, and the two ratings weight it against its siblings. Every declared feature stays in the denominator, so an unimplemented feature always counts against the score. A deduction names a behavior that is absent or differs from native, sized by how much real application usage that behavior is worth.

Proof says how much of that behavior has been demonstrated by running the same scenario on a real iPhone and in Peach and comparing the results. Where a library has paired measurements, its measured score is passing API usage divided by assessed API usage, on iOS, with the share of usage assessed shown beside it. A measured score covers its declared scenarios. It is not a claim of exhaustive API parity, and it is not the probability that your whole app works.

The number of proof cases a library has is counted separately and never presented as coverage. Many cases on a small corner of an API say little about the rest of it.

#What is excluded

Only app-facing capability counts. Internal plumbing, private bridge seams, unstable_ exports, development tooling and transitive dependencies that apps never import are left out, each with a recorded reason. Nothing is excluded for being rare, hard to test or currently failing.

Some native capability has nothing to do in a simulator: over-the-air update delivery, dev-client launching, build tooling reached at runtime. For those, the bar is that your app imports them cleanly, gets the unavailable or no-op result the API documents, and never throws. Meeting that bar is full marks.

#Version ranges

Every implementation figure belongs to a version range of the package. If your installed version falls outside every range Peach tracks, the package has no score for your app, and peach doctor marks it as an unverified version with the ranges it does cover. It may still work.

#The headline scores

The Conformance bar on peachsim.com and on Conformance rolls libraries up into five segments:

Each segment shows its score weighted by weekly downloads, so the packages more apps install count more. The ecosystem segments leave out build-time tools and pure JavaScript packages, since neither has a native side to implement.

#Light packages

Some packages are admitted so an app that imports them loads, without Peach implementing what they do. Their native side is an inert stand-in generated from the package’s own published source: every method exists and does nothing.

A light package is never presented as supported, measured or proven, and it never enters a score. Wherever its status appears, it reads as light: it loads, its native side is inert, and it has not been validated against the real native build. In peach doctor it reads loads; its native side is inert.

A light package is a good outcome for code your app only needs to import, such as an SDK whose effects you do not need in the simulator. It is the wrong outcome for a library your screens depend on. If one of those is light, tell us with peach doctor --report.

#Unsupported packages

A package that needs a native SDK Peach cannot run, and that Peach neither implements nor admits as light, is unsupported. peach doctor marks it ✗, says why in one clause, and names a replacement Peach does track when there is an obvious one.

#When a library is missing

1. +
   Run peach doctor. It tells you whether the library is partial, unverified for your version, light, unsupported, or unknown to Peach.
2. +
   If doctor marks it unknown native (?), it prints the native module and view names the library’s JavaScript asks for, already keyed for peach.config.ts. Answer them with 'noop' if you do not need the library in the simulator, or with files that do what the native side does. See Custom stubs.
3. +
   Check for a published stub. A peach-stub-<package> on npm answers the library as soon as you install it, with no config. Doctor marks stub packages as third-party.
4. +
   If the library is partial or unsupported, check whether your app uses the missing part. peach doctor <package> --verbose prints the full note. You can stub out a feature you do not need with modules in peach.config.ts.
5. +
   Tell us. peach doctor --report sends your findings with no login, carrying package names, versions and findings, never source or app data. Reports decide which libraries are implemented next.

To get a whole app running end to end, follow Wrap an existing app. For a standalone Swift or Compose project, use peach swift or peach kotlin.

#Related

• +
  Conformance: how Peach compares its output against a real iPhone, pixel by pixel
• +
  Diagnosing your project: every peach doctor finding and what to do about it