integrating-superwall-expo

name	integrating-superwall-expo
description	Integrates Superwall paywalls and subscription gating in React Native Expo apps using the expo-superwall SDK. Use when adding Superwall to an Expo (SDK 53+) project, wiring placements/feature gating, managing users and subscription status, handling deep links/web checkout, integrating RevenueCat, or debugging native-module issues.
allowed-tools	Read,Write,Bash(git:*),Bash(node:*),Bash(npm:*),Bash(npx:*),Bash(yarn:*),Bash(pnpm:*),Bash(bun:*),Bash(expo:*),Bash(eas:*),Bash(watchman:*),Bash(pod:*),Bash(xed:*)

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-superwall correctly 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)

1. Expo SDK 53+ is required for expo-superwall.
2. Expo Go is not supported. Use an Expo Development Build (npx expo run:ios|android or EAS dev client).
3. Target minimum OS versions:
   • iOS deployment target: 15.1+
   • Android minSdkVersion: 21+
4. 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-properties if 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 --clean if 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 feature callback 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({ … }) (pass null to unset)

See:

• references/USER_MANAGEMENT.md
• references/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:

1. Run the setup checker:
   • node {baseDir}/scripts/check-setup.mjs
2. Confirm you’re on a dev build, not Expo Go.
3. If you added expo-superwall to an existing project, regenerate native folders:
   • npx expo prebuild --clean (backs up any manual native edits first)
4. Rebuild the dev client (EAS or local) after adding native modules.
5. 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.json dependency updates
• app.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.ts constants and src/superwall/sync.ts for 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