Integrating Superwall in React Native Expo (expo-superwall)
Why this skill exists
Superwall’s Expo SDK (expo-superwall) is *native-module based*, so Expo Go won’t work and setup mistakes often look like “Cannot find native module 'SuperwallExpo'”. This skill provides a reliable, repeatable workflow to:
- install + configure
expo-superwallcorrectly in Expo SDK 53+ - present paywalls via placements (remote campaigns) and implement feature gating
- manage users + attributes, and keep subscription status in sync (including RevenueCat)
- wire deep links / web checkout, and troubleshoot the common integration failures
Non‑negotiables (check first)
- Expo SDK 53+ is required for
expo-superwall. - Expo Go is not supported. Use an Expo Development Build (
npx expo run:ios|androidor EAS dev client). - Target minimum OS versions:
- iOS deployment target: 15.1+ - Android minSdkVersion: 21+
- Superwall config does not refetch during hot reload. After dashboard changes (paywalls/products/campaigns), fully restart the app.
Fast path checklist (copy/paste and tick)
- Confirm Expo SDK version (>=53) and you are *not* using Expo Go
- Install packages:
expo-superwall(+expo-build-propertiesif needed) - Set iOS/Android minimum versions via
expo-build-properties - Wrap app with
<SuperwallProvider>(+<SuperwallLoading/>,<SuperwallError/>,<SuperwallLoaded/>) - Register a first placement with
usePlacement().registerPlacement({placement: "…"}) - (Optional) Implement feature gating via
feature: () => …callback - (Optional) Identify user + set user attributes with
useUser() - (Optional) Sync subscription status (built-in, or manual when using RevenueCat/custom billing)
- Rebuild dev client after native changes (
npx expo prebuild --cleanif needed) - Validate with:
node {baseDir}/scripts/check-setup.mjs
Default implementation pattern (recommended)
1) Install + platform targets
Follow the Superwall install guide in references/INSTALLATION.md.
2) Configure Superwall at the root
Use <SuperwallProvider /> at the top of your app (typically in App.tsx or your root layout). Add loading/error handling components so failures are visible.
See references/CONFIGURATION.md and assets/snippets/App.tsx.
3) Present paywalls & gate features via placements
Use the usePlacement hook to register placements. This is the “one API” that powers:
- presenting paywalls
- feature gating (run
featurecallback depending on dashboard “Gated/Non‑Gated”) - tracking paywall lifecycle state in React
See references/PLACEMENTS_AND_GATING.md.
4) Manage users, attributes, and subscription state
- Identify on login with
useUser().identify(userId) - Sign out with
useUser().signOut() - Set/merge attributes with
useUser().update({…})(passnullto unset)
See:
references/USER_MANAGEMENT.mdreferences/SUBSCRIPTION_STATUS.md
5) Deep links & web checkout (optional)
If you want paywall previews from the dashboard, campaign-driven paywalls from deep links, or web checkout flows, wire deep links and forward incoming URLs to Superwall.
See references/DEEP_LINKS.md.
6) RevenueCat (optional, recommended approach)
If you want RevenueCat to own purchases while Superwall owns paywalls/experiments, use CustomPurchaseControllerProvider (hooks-based) and sync entitlement state to Superwall.
See references/REVENUECAT.md.
Troubleshooting playbook (use when things don’t work)
If you hit Cannot find native module 'SuperwallExpo', or paywalls never show:
- Run the setup checker:
- node {baseDir}/scripts/check-setup.mjs
- Confirm you’re on a dev build, not Expo Go.
- If you added
expo-superwallto an existing project, regenerate native folders:
- npx expo prebuild --clean *(backs up any manual native edits first)*
- Rebuild the dev client (EAS or local) after adding native modules.
- Clear caches and reinstall deps as needed.
Full triage checklist: references/TROUBLESHOOTING.md.
Output expectations when performing work in a repo
When applying this skill to a real codebase, prefer a small, reviewable set of changes:
package.jsondependency updatesapp.json/app.config.*plugin + platform target updates- Root provider wiring (
App.tsx/RootLayout) - A small “first placement” screen/button for verification
- Optional:
src/superwall/placements.tsconstants andsrc/superwall/sync.tsfor RevenueCat status sync
Include a short “How to test locally” note (dev build commands + which placement to trigger).
Reference map (read only when needed)
- Install + prerequisites:
references/INSTALLATION.md - Provider + options:
references/CONFIGURATION.md - Placements, gating, presentation results:
references/PLACEMENTS_AND_GATING.md - Users + attributes:
references/USER_MANAGEMENT.md - Subscription state:
references/SUBSCRIPTION_STATUS.md - Event listeners + analytics forwarding:
references/EVENTS_ANALYTICS.md - Deep links, previews, web checkout:
references/DEEP_LINKS.md - RevenueCat integration:
references/REVENUECAT.md - Debugging:
references/TROUBLESHOOTING.md - StoreKit testing:
references/STOREKIT_TESTING.md - Locale override:
references/LOCALE.md - Bare RN + Expo modules:
references/BARE_REACT_NATIVE.md - Migration / compat API:
references/MIGRATION_COMPAT.md