integrating-superwall-expo

Original：🇺🇸 English

Translated

1 scriptsChecked / no sensitive code detected

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.

5installs

Sourcetristanmanchester/agent-skills

Added on2026-05-12

NPX Install

npx skill4agent add tristanmanchester/agent-skills integrating-superwall-expo

SKILL.md Content

View Translation Comparison →

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)

Expo SDK 53+ is required for
```
expo-superwall
```
.
Expo Go is not supported. Use an Expo Development Build (
```
npx expo run:ios|android
```
or 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-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:

Run the setup checker:
- ```
node {baseDir}/scripts/check-setup.mjs
```
Confirm you’re on a dev build, not Expo Go.
If you added
```
expo-superwall
```
to 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.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
```