integrating-superwall-expo
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.
How do I install this agent skill?
npx skills add https://github.com/tristanmanchester/agent-skills --skill integrating-superwall-expoIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a secure and well-structured workflow for integrating the Superwall Expo SDK into React Native applications. It follows security best practices by recommending environment variables for sensitive API keys and includes a local validation script that safely inspects project configuration files without executing dangerous commands or making external network requests.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · No issues
- Runlayerwarn
6/18 files flagged
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/tristanmanchester/agent-skills/integrating-superwall-expo">View integrating-superwall-expo on skillZs</a>