react-native-purchases

react-native-purchases is the official React Native client for RevenueCat, a subscription and in-app-purchase backend used by tens of thousands of apps. It wraps native StoreKit (iOS), Google Play Billing (Android), and RevenueCat Web Billing behind a single JavaScript/TypeScript API, so a React Native app can fetch products, present offerings, make purchases, and check entitlement status without writing separate native purchase code for each store.

Beyond the purchase flow itself, the SDK syncs receipt validation, subscription renewals, and customer entitlements to the RevenueCat backend, which exposes webhooks, analytics (MRR, churn, conversion), and integrations to send purchase events onward to analytics and attribution tools. The library also runs in a browser/Expo Go preview mode, mocking native calls so developers can iterate on purchase UI without a native build.

What You Get

• A single Purchases singleton API (configure, getOfferings, purchasePackage, getCustomerInfo, restorePurchases) that works identically across iOS, Android, and web
• Server-side receipt validation and entitlement tracking handled by RevenueCat’s backend instead of custom server code
• A browser/Expo Go preview mode that mocks native purchase calls so purchase UI can be built and tested without a native build
• Typed models for offerings, packages, store products, customer info, and entitlements re-exported from RevenueCat’s shared internal SDK package
• Built-in support for promotional offers, win-back offers, product/plan upgrades and downgrades, and subscription management across stores

Common Use Cases

• Adding subscription paywalls to a React Native app without building separate StoreKit and Google Play Billing integrations
• Tracking subscriber entitlements and lifetime value across iOS, Android, and web from one dashboard
• Running A/B tests on pricing and paywall offerings via RevenueCat’s remotely configured offerings
• Sending real-time purchase, renewal, and cancellation events to analytics or attribution tools via webhooks
• Migrating an existing native (iOS/Android) RevenueCat integration into a shared React Native codebase

Under The Hood

Architecture This is a thin JS/TS facade layer bridging to native purchase SDKs rather than a place where purchase logic itself executes. The public API surface is a single Purchases class (src/purchases.ts) that mostly re-exports types and delegates calls through React Native’s NativeModules/NativeEventEmitter bridge to native code (RNPurchases.m/.h on iOS, Kotlin sources under android/src), which in turn wraps RevenueCat’s own native purchases-ios/purchases-android SDKs. A parallel browser code path (src/browser/nativeModule.ts, src/browser/typeGuards.ts, gated by shouldUseBrowserMode in src/utils/environment.ts) mocks the native module for web and Expo Go so the same JS API works without a native bridge. Because most types are direct re-exports from the shared @revenuecat/purchases-typescript-internal package (also used across RevenueCat’s other JS-based SDKs), changes to that shared package or to the native bridge contract propagate through this package almost immediately.

Tech Stack TypeScript compiled to CommonJS/ES5 via tsc for React Native compatibility, with native bridge code in Kotlin (Android) and Objective-C (iOS) that defers all core purchase logic to RevenueCat’s native SDKs rather than reimplementing it in JavaScript. Dependencies are pinned to @revenuecat/purchases-typescript-internal and @revenuecat/purchases-js-hybrid-mappings at matching versions. The repo is a Yarn workspaces monorepo alongside react-native-purchases-ui and several example/e2e-test packages, uses Jest for unit tests, tslint for linting, CircleCI for CI, and Fastlane plus a Dangerfile for release and PR automation; native dependencies are managed via CocoaPods (RNPurchases.podspec) and Gradle.

Code Quality Jest tests exist under __tests__/ covering alert helpers, API key validation, the offerings loader, simulated-package purchase helpers, and release-version parsing, though most native-bridge behavior is instead covered by a separate Maestro end-to-end test workspace rather than JS unit tests. Error handling is explicit and typed — PurchasesError, UninitializedPurchasesError, and UnsupportedPlatformError with a dedicated error-code enum are used consistently, and the missing-native-module case produces a detailed, actionable error message rather than failing silently. TypeScript strict mode is enabled with noUnusedLocals and noImplicitReturns, naming is consistent, and comment/JSDoc density in the core file is high; tslint (rather than modern ESLint) is comparatively dated tooling.

API Design The public API favors a familiar singleton-configure pattern (Purchases.configure() once, then promise-based getOfferings/purchasePackage/getCustomerInfo/restorePurchases calls) whose naming mirrors RevenueCat’s native SDKs closely, so knowledge transfers across platforms. Getting started requires minimal boilerplate — install, configure with an API key, fetch offerings, purchase a package — and the transparent browser/Expo Go fallback lets developers iterate on purchase UI without a native build, a genuine ergonomics win for an SDK that otherwise needs native compilation. Extensive external documentation (RevenueCat docs site, a generated TypeDoc reference, and a dedicated v4-to-v5 migration guide) supplements in-repo comments.