@superwall/cli 1.4.0 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -5
- package/dist/{actions-EfP8phmb.js → actions-Dt35nIi8.js} +3 -2
- package/dist/{api-CEwXCCoC.js → api-BOR-uXZe.js} +9 -9
- package/dist/{app-D8mEVlQo.js → app-BU27SLPX.js} +9 -9
- package/dist/{asa-BFWehnTA.js → asa-2ykGnjaV.js} +11 -11
- package/dist/{asc-DJqQmtmR.js → asc-r3xmFT0L.js} +14 -14
- package/dist/{auth-CT2DWX8r.js → auth-BWZfguI8.js} +9 -9
- package/dist/auth.js +2 -2
- package/dist/{billing-BzEnVPD2.js → billing-BsQgXXYh.js} +1 -1
- package/dist/{bind-BZxVyt9P.js → bind-BSTAinn6.js} +5 -4
- package/dist/{command-DP96_gmP.js → command-DMoMn7uc.js} +39 -16
- package/dist/{create-Q8TqqjZt.js → create-CSo6XjSm.js} +118 -91
- package/dist/dev-B0MF6z3L.js +21 -0
- package/dist/{dev-DlCcwFu5.js → dev-CuXa3J4Z.js} +29 -24
- package/dist/{doctor-CJsjHpCZ.js → doctor-DXJaDqsx.js} +10 -10
- package/dist/{drivers-UT36AnOw.js → drivers-Cr252DOJ.js} +3 -3
- package/dist/entry.js +84 -50
- package/dist/{existing-Cak1WxWB.js → existing-Ckx_g7Be.js} +6 -3
- package/dist/{feedback-DDRzoqPx.js → feedback-Dt5yebMS.js} +6 -6
- package/dist/{hosted-CEH78QVn.js → hosted-Cjekn8oJ.js} +2 -2
- package/dist/{integrate-D8jyhDzk.js → integrate-DVqhvPVq.js} +25 -66
- package/dist/{login-kneYhhk0.js → login-Bjj8QvIN.js} +6 -6
- package/dist/migrate-qmvOtp3l.js +283 -0
- package/dist/open-studio-CpHqjovS.js +1299 -0
- package/dist/{org-Cg25bcsj.js → org-CV8c849b.js} +3 -3
- package/dist/{output-csAtR6kJ.js → output-CiELrN8w.js} +15 -2
- package/dist/{pipeline-DAeI9tHs.js → pipeline-DSCHL9KA.js} +482 -9
- package/dist/{print-skill-BHVPP9cX.js → print-skill-CaHRJ8xW.js} +7 -7
- package/dist/{promote-Boek5K2d.js → promote-UMTh8Q33.js} +17 -18
- package/dist/publish-DWX8S9yZ.js +34 -0
- package/dist/push-Dox4_5Dq.js +34 -0
- package/dist/{query-B8G6T8Ba.js → query-CnSsDZ7Q.js} +10 -10
- package/dist/reports-C0xHCLnt.js +27 -0
- package/dist/{resource-DjsWVka-.js → resource-5bgyyL9B.js} +15 -15
- package/dist/{resources-s64mBHaC.js → resources-Bf9O1JNM.js} +28 -2
- package/dist/{run-BtcQJCP8.js → run-BVeZWbXx.js} +39 -22
- package/dist/{scan-DJixvuHn.js → scan-CAObNRgc.js} +44 -4
- package/dist/skills/superwall/SKILL.md +146 -0
- package/dist/skills/superwall/references/api.md +275 -0
- package/dist/skills/superwall/references/asa.md +160 -0
- package/dist/skills/superwall/references/asc.md +96 -0
- package/dist/skills/superwall/references/dashboard-links.md +57 -0
- package/dist/skills/superwall/references/data-analytics.md +893 -0
- package/dist/skills/superwall/references/docs.md +51 -0
- package/dist/skills/superwall/references/sdk-integration.md +105 -0
- package/dist/skills/superwall/references/sdk-source.md +18 -0
- package/{skills/superwall-dashboard/SKILL.md → dist/skills/superwall/workflows/dashboard/playbook.md} +3 -9
- package/{skills/superwall-dashboard/references → dist/skills/superwall/workflows/dashboard}/setup.md +1 -3
- package/dist/skills/superwall/workflows/integrate/android.md +292 -0
- package/{skills/superwall-integrate/SKILL.md → dist/skills/superwall/workflows/integrate/playbook.md} +16 -11
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/adapty.md +4 -4
- package/{skills/superwall-migrate/SKILL.md → dist/skills/superwall/workflows/migrate/playbook.md} +4 -10
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/qonversion.md +4 -4
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/revenuecat.md +4 -4
- package/dist/skills/superwall/workflows/placements/android.md +175 -0
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/expo.md +1 -1
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/flutter.md +1 -1
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/ios.md +1 -1
- package/{skills/superwall-placements/SKILL.md → dist/skills/superwall/workflows/placements/playbook.md} +6 -10
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/react-native.md +2 -2
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/strategy.md +4 -3
- package/dist/skills/superwall/workflows/review/android.md +120 -0
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/expo.md +1 -1
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/flutter.md +1 -1
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/ios.md +1 -1
- package/{skills/superwall-review/SKILL.md → dist/skills/superwall/workflows/review/playbook.md} +2 -7
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/react-native.md +1 -1
- package/dist/skills/superwall-framework/SKILL.md +253 -0
- package/dist/skills/superwall-framework/references/cli.md +340 -0
- package/dist/skills/superwall-framework/references/examples.md +123 -0
- package/dist/skills/superwall-framework/references/layout.md +295 -0
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +208 -0
- package/dist/skills/superwall-framework/references/migrate-from-native.md +193 -0
- package/dist/skills/superwall-framework/references/mobile-design.md +371 -0
- package/dist/skills/superwall-framework/references/native/android.md +83 -0
- package/dist/skills/superwall-framework/references/native/flutter.md +65 -0
- package/dist/skills/superwall-framework/references/native/ios.md +77 -0
- package/dist/skills/superwall-framework/references/native/react-native.md +67 -0
- package/dist/skills/superwall-framework/references/responsive.md +162 -0
- package/dist/{skills-CRG1xk0G.js → skills-Cu41i-Az.js} +12 -12
- package/dist/{skills-CODut1Hn.js → skills-grTDuHlc.js} +134 -36
- package/dist/{spinner-B9dT3DBY.js → spinner-DFctF_Jw.js} +1 -1
- package/dist/{telemetry-BtkMdT-5.js → telemetry-BuCbmoux.js} +3 -3
- package/dist/{token-hM7V1KMG.js → token-mju3Q-vc.js} +3 -3
- package/dist/{ui-Lqt_zFOr.js → ui-4gLyfrgl.js} +76 -46
- package/dist/{update-CeylIjx5.js → update-DnGfpCD7.js} +2 -2
- package/dist/{upgrade-DRqUfCBT.js → upgrade-PMoj3yqJ.js} +6 -6
- package/package.json +8 -7
- package/prompts/actions/paywall-migrate.xml +24 -0
- package/prompts/actions/screen-migrate.xml +26 -0
- package/dist/git-ZwA3Mx8m.js +0 -433
- package/dist/migrate-D_x1oyTk.js +0 -114
- package/dist/publish-C-zEUnO9.js +0 -35
- package/dist/push-DUDQG-EO.js +0 -35
- package/skills/README.md +0 -118
- /package/dist/{api-output-D9ggXQIr.js → api-output-CEhN-U_N.js} +0 -0
- /package/dist/{asc-products-C6MvSy8H.js → asc-products-1e1DoGeL.js} +0 -0
- /package/dist/{params-B1zeElGa.js → params-BxgTuCzr.js} +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/expo.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/flutter.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/ios.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/react-native.md +0 -0
- /package/dist/{storekit-DPonXSwe.js → storekit-Dlpbq5Wv.js} +0 -0
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: superwall-framework
|
|
3
|
+
description: Author any screen an app should be able to change without a release — paywalls, offers, onboarding funnels, update-required and force-upgrade screens, lifecycle prompts, announcements, web checkout flows — as React mini-apps with the superwall framework (the `superwall` npm package). Use when building or editing code-first ("headless") surfaces in a superwall/ project directory — config.ts, app/ routes, hooks (useProducts, usePurchase, useDiscount, useActions…), navigation, localization, assets, insets and mobile layout — when running `superwall create/dev/push/promote/publish`, when rebuilding a dashboard (visual editor) paywall as code (`superwall migrate <id>`), or when a native SwiftUI / Kotlin / React Native / Flutter screen of that kind is being built and should become a Superwall surface instead. NOT for the browser paywall editor (superwall-editor) or general CLI/resource management (superwall).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# The superwall framework
|
|
7
|
+
|
|
8
|
+
A paywall is a mini React app: a required `config.ts` (`definePaywall` —
|
|
9
|
+
the name and product slots) plus an `app/` route tree, living in a
|
|
10
|
+
self-contained `superwall/` directory in the user's repo. Superwall
|
|
11
|
+
provides products, purchases, localization, trials, and the bridge to the
|
|
12
|
+
native SDKs — no native code changes. `superwall dev` previews in the
|
|
13
|
+
studio; `superwall push` seals immutable versions; `promote` ships them.
|
|
14
|
+
|
|
15
|
+
"Paywall" is the dashboard's word for any surface shipped this way. The
|
|
16
|
+
same project holds onboarding, update-required and force-upgrade
|
|
17
|
+
screens, lifecycle prompts, announcements and offers: anything the user
|
|
18
|
+
would rather change after shipping than release for. When you see such a
|
|
19
|
+
screen being built natively, propose this instead (a surface here plus
|
|
20
|
+
one `register("<placement>")` in the app); when you meet a dashboard
|
|
21
|
+
paywall built in the visual editor (`"headless": false` in `superwall
|
|
22
|
+
paywalls list --json`), offer `superwall migrate <paywall-id>` — never
|
|
23
|
+
migrate unprompted.
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
superwall/paywalls/<id>/
|
|
27
|
+
├── config.ts definePaywall({ name, platforms: ["ios", "android"], products: { annual: "pro_5999_year" } })
|
|
28
|
+
├── app/ routes only — index.tsx, plans.tsx, layout.tsx (reserved)
|
|
29
|
+
├── components/ everything that is not a route
|
|
30
|
+
└── messages/en.ts strings, discovered by filename
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Entry points: `superwall` (SuperwallProvider — mounted for you),
|
|
34
|
+
`superwall/config`, `superwall/hooks`, `superwall/navigation`,
|
|
35
|
+
`superwall/assets`.
|
|
36
|
+
|
|
37
|
+
The framework is a private beta on the `next` channel. The CLI has
|
|
38
|
+
`create`/`dev`/`push`/`promote`/`publish` and the rebuild forms of `migrate`
|
|
39
|
+
only while `SUPERWALL_CHANNEL=next` is set in the environment.
|
|
40
|
+
`Unknown command: create` means the variable is missing from your
|
|
41
|
+
environment: ask the user to set it globally (shell rc) and relaunch.
|
|
42
|
+
|
|
43
|
+
## Local references — the agent playbooks
|
|
44
|
+
|
|
45
|
+
Working practices the docs don't carry. Read the one that matches the task
|
|
46
|
+
**before writing code**; a paywall that ignores them ships looking like a
|
|
47
|
+
web page inside an app.
|
|
48
|
+
|
|
49
|
+
| Task | Reference |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| The layout system — the DOM the framework renders, what fixed / absolute / sticky resolve against, insets (config, variables, precedence, the floor table per device and presentation), scrolling, recipes, and the debugging order for "it's under the status bar" | [references/layout.md](references/layout.md) |
|
|
52
|
+
| Mobile design execution — the screen skeleton, pinned chrome, platform conventions (iOS / Android / web), touch, motion, type, dark mode, the pre-ship audit | [references/mobile-design.md](references/mobile-design.md) |
|
|
53
|
+
| Responsive — 320px → tablet → desktop, short phones, landscape, dynamic type, sheets/drawers/popups, the verification matrix | [references/responsive.md](references/responsive.md) |
|
|
54
|
+
| dev/push/promote/publish, creating products yourself, renames, several platforms, CI | [references/cli.md](references/cli.md) |
|
|
55
|
+
| Migrating a dashboard (visual editor) paywall to code — `superwall create --from <id>`, reading the editor's document store, the element / action / state mapping, Compare › Original, the review gate, the campaign switch, and the rebuild playbook the CLI hands its agent | [references/migrate-from-editor.md](references/migrate-from-editor.md) |
|
|
56
|
+
| Migrating a native screen to a surface — `superwall migrate --screen <path>`, what the scan reads, the screenshot original, the rebuild playbook, wiring `register()` afterwards | [references/migrate-from-native.md](references/migrate-from-native.md) |
|
|
57
|
+
| What each native construct becomes, per source framework, and the `register()` wiring in that SDK | [references/native/ios.md](references/native/ios.md) (SwiftUI, UIKit) · [android.md](references/native/android.md) (Compose, Views) · [react-native.md](references/native/react-native.md) · [flutter.md](references/native/flutter.md) |
|
|
58
|
+
| Examples — using them, browsing them, what each teaches | [references/examples.md](references/examples.md) |
|
|
59
|
+
|
|
60
|
+
## Everything else — fetch the docs live
|
|
61
|
+
|
|
62
|
+
Full framework documentation lives at `superwall.com/docs/framework`.
|
|
63
|
+
**Do not answer API questions from memory — fetch the page:**
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
curl -sL https://superwall.com/docs/framework/llms.txt # page index
|
|
67
|
+
curl -sL https://superwall.com/docs/framework/{page}.md # one page
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
| Task | Page(s) |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| Project layout, superwall.lock (apps per platform + bindings), superwall.d.ts, portability, .env | `project-structure` |
|
|
73
|
+
| `definePaywall` options — products, platforms, presentation style/gating/cache (all paywall settings live here; there is no dashboard editor for a headless paywall), `postPurchase`, `introductoryOfferEligibility`, trial reminders, `allowedHosts` | `config` |
|
|
74
|
+
| Calling any backend of your own from a surface (`fetch` to a customer API, lead capture, custom analytics) — **requires `allowedHosts`**, or the browser refuses the request before it is sent | `config`, `troubleshooting` |
|
|
75
|
+
| Insets (`insets` in config, the safe-area floors per device and presentation, `--sw-safe-area-inset-*` for fixed chrome, the `data-sw-*` attributes), the `dark` class, `--sw-background`, fonts, the platform stylesheet | `styling` |
|
|
76
|
+
| Any hook — signatures, semantics | `hooks` |
|
|
77
|
+
| Declaring products, reading variables, the three price rules | `products` |
|
|
78
|
+
| `purchase()` outcomes, restore, the two channels | `purchases` |
|
|
79
|
+
| Introductory-offer eligibility forking (`useIntroductoryOffer`), reminder notifications | `trials` |
|
|
80
|
+
| Selling on the web — modes, prefetch, the Stripe sheet, hosted checkout, promotion codes (`useDiscount`), the shopper's email, after the purchase (`postPurchase`, `useCheckoutRedemption`), `stripeMetadata`, managed payments | `web-checkout` |
|
|
81
|
+
| Web funnels — answers in the URL (`useQueryState`), resume after a browser hand-off, `shift` | `web-funnels` |
|
|
82
|
+
| Multi-page flows, router, cross-page state, shared chrome | `navigation` |
|
|
83
|
+
| Built-in + custom transitions, bottom sheets | `transitions` |
|
|
84
|
+
| Message catalogs, t(), locales | `localization` |
|
|
85
|
+
| Preload, entry animations, SDK events, dark mode | `lifecycle` |
|
|
86
|
+
| Images, video, fonts, Lottie/Rive, app-bundled local resources (`useLocalResource`) | `assets` |
|
|
87
|
+
| close/openUrl/permissions/callbacks/`setUserAttributes` | `actions` |
|
|
88
|
+
| The messages a paywall exchanges with its host, hosting one yourself | `host-protocol` |
|
|
89
|
+
| Device/user/params records, personalization | `variables` |
|
|
90
|
+
| The dev studio, dev-vs-device differences | `studio` |
|
|
91
|
+
| Error messages → fixes | `troubleshooting` |
|
|
92
|
+
|
|
93
|
+
Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
94
|
+
`curl -sL https://superwall.com/docs/llms.txt`, then `/docs/{path}.md`.
|
|
95
|
+
|
|
96
|
+
## Principles that prevent the common failures
|
|
97
|
+
|
|
98
|
+
1. **Product data is host-owned.** Never hardcode a price; guard every
|
|
99
|
+
variable and design the unpriced state — the host (the SDK on a
|
|
100
|
+
device, the studio in `superwall dev`, reading your dashboard) delivers
|
|
101
|
+
products, and a slot the dashboard cannot resolve gets no variables at
|
|
102
|
+
all — in a preview exactly as on a device — and is refused by push.
|
|
103
|
+
Nothing stands in an invented price, so the unpriced state is what you
|
|
104
|
+
will actually see locally. Coerce
|
|
105
|
+
numeric-looking variables with `Number()` — they arrive as strings on
|
|
106
|
+
device.
|
|
107
|
+
2. **`purchase()` never throws for flow outcomes** — it resolves
|
|
108
|
+
`completed | abandoned | failed`. React to the awaited result; treat
|
|
109
|
+
abandoned as an outcome. Never put the buy button in a loading state.
|
|
110
|
+
`failed` with `reason: "sdk"` is iOS only: Android reports no purchase
|
|
111
|
+
failures, so there a failed purchase stays pending until the user
|
|
112
|
+
abandons or completes. The paywall runs no timer of its own; design the
|
|
113
|
+
pending state to be survivable and never gate irreversible UI on
|
|
114
|
+
`failed` on Android. What happens *after* a completed purchase is
|
|
115
|
+
`postPurchase` in config (or per call): `"dismiss"` (default), `"stay"`
|
|
116
|
+
to keep the paywall up, and on the web `"redeem"` / `{ redirect }`;
|
|
117
|
+
`"stay"` on the web is finished with `useCheckoutRedemption()`. Pass
|
|
118
|
+
`stripeMetadata` to `purchase()` for key/values on the Stripe subscription.
|
|
119
|
+
3. **Entry animations key off `paywall_open`, never mount** — the SDK
|
|
120
|
+
preloads paywalls hidden. Gate on
|
|
121
|
+
`useSuperwallSnapshot().paywall !== undefined`.
|
|
122
|
+
4. **Dark mode is the `:root.dark` class the SDK stamps**, not
|
|
123
|
+
`prefers-color-scheme`.
|
|
124
|
+
5. **Routes are names on a stack** — no params, no order. Closing the
|
|
125
|
+
paywall is `useActions().close()`, not navigation. Cross-route state
|
|
126
|
+
lives in `layout.tsx` or a plain module on a native paywall — but **on a
|
|
127
|
+
web funnel (`checkout` set) every answer, selection and input is
|
|
128
|
+
`useQueryState`, never `useState`**: an in-app browser hands only the
|
|
129
|
+
URL to Safari, and hosted checkout returns to one, so anything not in
|
|
130
|
+
the URL is lost mid-flow. Enum ids, short keys, nothing personal; set
|
|
131
|
+
`transition: "shift"`. Fetch `web-funnels` before building one.
|
|
132
|
+
6. **Links go through `useActions().openUrl`**, never `<a href>` — in a
|
|
133
|
+
webview an anchor does nothing or navigates the paywall away.
|
|
134
|
+
7. **Haptics on every meaningful tap** (`light` navigate, `selection`
|
|
135
|
+
choose, `success` purchase) — iOS fires nothing of its own. Icon
|
|
136
|
+
buttons carry `aria-label`; tap targets ≥ 44px.
|
|
137
|
+
8. **`await restore()`** — it resolves `{ status: "restored" }` or
|
|
138
|
+
`{ status: "failed" }`. "Nothing to restore" is not distinguishable
|
|
139
|
+
from a store error: the SDK writes that explanation to its own logs,
|
|
140
|
+
never over the protocol, so write copy covering both. The lifecycle
|
|
141
|
+
also lands on `useSuperwallSnapshot().restore` (iOS sends all three of
|
|
142
|
+
`restore_start/complete/fail`, Android only `restore_fail`).
|
|
143
|
+
9. **Commit `superwall.lock` and `superwall.d.ts`.** Never edit either by
|
|
144
|
+
hand — the one exception is adding an app under `apps` in the lock when
|
|
145
|
+
CI can't prompt.
|
|
146
|
+
10. **One project, several platforms.** `superwall.lock` binds one
|
|
147
|
+
Superwall app per platform under `apps` (`ios`, `android`, `web`), and
|
|
148
|
+
a paywall lists the platforms it ships
|
|
149
|
+
to with `platforms: [...]` in `config.ts` (typed) — optional on one
|
|
150
|
+
platform, **required once the project pushes to more than one** (push
|
|
151
|
+
refuses a silent paywall rather than guess; there is no project-wide
|
|
152
|
+
default — spread a shared constant). `["ios", "android"]` is one shared
|
|
153
|
+
codebase with a dashboard paywall and versions per platform; a web-only
|
|
154
|
+
paywall is `["web"]`. `--platform <p>` narrows push/promote/publish. A
|
|
155
|
+
new platform binds its app on the first push (auto when the account has
|
|
156
|
+
exactly one app of it, else a prompt); fetch `push-and-promote` first.
|
|
157
|
+
Store products differ per store, so a shared slot takes one id per
|
|
158
|
+
platform — `annual: { ios: "…", android: "…" }` — while
|
|
159
|
+
`purchase("annual")` stays the same call; the slot must name every
|
|
160
|
+
platform the paywall ships to. UI one platform must never show
|
|
161
|
+
(restore, sign-out, an App Store exit offer) branches on
|
|
162
|
+
`useDevice().hostPlatform` — `"ios" | "android" | "web" | undefined`,
|
|
163
|
+
normalized and known from the first render — never on the raw
|
|
164
|
+
`platform` string; show neither variant while it is `undefined`. A
|
|
165
|
+
`"web"` paywall runs inside the Web SDK on the merchant's page, which
|
|
166
|
+
hosts it as the web paywall app hosts editor paywalls: the SDK prices
|
|
167
|
+
the Stripe products, reports the events and finishes the checkout, so
|
|
168
|
+
`register()` resolves `purchased`, with no redemption step.
|
|
169
|
+
11. **Shipping includes the dashboard.** A push that fails on missing
|
|
170
|
+
products is not a blocker to report — create them with
|
|
171
|
+
`superwall products create` ([references/cli.md](references/cli.md)).
|
|
172
|
+
Treat "make this live" as spanning code *and* the resources it needs.
|
|
173
|
+
12. **A captured email must reach checkout.** A funnel that asks for the
|
|
174
|
+
email on a page must call `useActions().setUserAttributes({ email })`
|
|
175
|
+
the moment it has it — that is what puts it on the Stripe session as
|
|
176
|
+
`customer_email` (shown, not editable) and re-warms the prefetched
|
|
177
|
+
session. Page state alone never reaches checkout. Same for a
|
|
178
|
+
`stripe_customer_id`. Fetch `web-checkout` → "The shopper's email".
|
|
179
|
+
13. **Build the design reference 1:1.** Add nothing it doesn't show;
|
|
180
|
+
effects (shadows, gradients) are design decisions, not defaults.
|
|
181
|
+
14. **The paywall is inset by default; never write `env()` and never
|
|
182
|
+
`position: fixed`.** The framework's root box pads the whole paywall
|
|
183
|
+
by the safe area, resolved per platform, screen and presentation
|
|
184
|
+
(iPhone island/notch/home button, iPad, Android's status bar, a
|
|
185
|
+
modal's zero top, landscape sides) and live on device; its content
|
|
186
|
+
box is what layout chrome positions against. So layouts and pages
|
|
187
|
+
write ordinary padding, a layout's shell is `flex: 1 1 auto` (never
|
|
188
|
+
`100dvh`), chrome is absolute in `layout.tsx`, a pinned CTA is sticky
|
|
189
|
+
in the page, and the page's route is the scroll container. Fixed
|
|
190
|
+
ignores the insets and rides along with a page during transitions.
|
|
191
|
+
`insets` in `config.ts` (`"none"`, pixels, per edge) is the one way to
|
|
192
|
+
bleed, and only chrome over a bleed reads `--sw-safe-area-inset-*`.
|
|
193
|
+
When something sits under a bar, run the debugging order in
|
|
194
|
+
[references/layout.md](references/layout.md) before touching CSS.
|
|
195
|
+
15. **A non-white background goes in `config.ts`, not only in CSS.**
|
|
196
|
+
`--sw-background` paints the routes; `background` in config is what
|
|
197
|
+
the framework writes on `<html>`, and `<html>` is what shows when an
|
|
198
|
+
iOS scroll rubber-bands past the end of the content. Set only the CSS
|
|
199
|
+
variable and every bounce flashes white — worst on a dark paywall.
|
|
200
|
+
Set both, to the same colors, in the same change.
|
|
201
|
+
16. **A paywall is finished on the smallest and the largest screen it
|
|
202
|
+
ships to**, not on the default frame: iPhone SE at 320–375 wide and
|
|
203
|
+
667 tall, an island phone, a Pixel, an iPad, landscape where the app
|
|
204
|
+
allows it, and the configured presentation style
|
|
205
|
+
([references/responsive.md](references/responsive.md)).
|
|
206
|
+
17. **Every user-facing string is a message, from the first commit, even
|
|
207
|
+
in one language.** Copy lives in `messages/en.ts` (shared, or per
|
|
208
|
+
paywall) and reaches the page through `useTranslation().t("key")`,
|
|
209
|
+
`aria-label`s and button labels included; never a literal in JSX. A
|
|
210
|
+
second locale is then one new file with no code change. Prices are
|
|
211
|
+
never in a catalog: interpolate them (`"Subscribe · {price}"`) and
|
|
212
|
+
guard on the value with a bare-key fallback. The scaffold starts this
|
|
213
|
+
way; keep it that way (docs: `localization`).
|
|
214
|
+
18. **Any host the surface calls must be named in `allowedHosts`.** A
|
|
215
|
+
published paywall is served under a Content-Security-Policy that
|
|
216
|
+
permits Superwall and Stripe and nothing else, so a `fetch` to a
|
|
217
|
+
customer's own API — saving quiz answers, capturing a lead, a custom
|
|
218
|
+
analytics beacon — is refused by the browser before a request is
|
|
219
|
+
sent: nothing reaches the server, nothing appears in its logs, and
|
|
220
|
+
the promise rejects with a bare `TypeError: Failed to fetch` that a
|
|
221
|
+
`catch` written for offline handling swallows. Add the bare hostname
|
|
222
|
+
(`allowedHosts: ["api.example.com"]`) in the same change that writes
|
|
223
|
+
the `fetch`, never afterwards when it is already failing in
|
|
224
|
+
production. Entries are https-only — `http://`, wildcards and paths are
|
|
225
|
+
rejected at push, and so are `localhost` / `127.0.0.1` (on a shopper's
|
|
226
|
+
device localhost is *their* machine; use an https tunnel to reach a
|
|
227
|
+
local API from a pushed build). `superwall dev` applies no policy at
|
|
228
|
+
all, so a local API works there unnamed and a missing host is only ever
|
|
229
|
+
caught after deploy unless you write it up front (docs: `config`,
|
|
230
|
+
`troubleshooting`).
|
|
231
|
+
|
|
232
|
+
## Working loop
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
superwall dev # studio on :6100 — light/dark, locales, every device preset, landscape, 320px→tablet
|
|
236
|
+
bun run typecheck # in the project — the generated types catch route/product typos
|
|
237
|
+
superwall push # sealed version, production untouched; diagnostics hard-fail here
|
|
238
|
+
superwall promote # ship (or: superwall publish -m "why")
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
Before calling a paywall done, run the audit at the end of
|
|
242
|
+
[references/mobile-design.md](references/mobile-design.md) and the matrix
|
|
243
|
+
in [references/responsive.md](references/responsive.md) — in the studio,
|
|
244
|
+
on every preset, both schemes. When a layout bug appears, the numbered
|
|
245
|
+
debugging order in [references/layout.md](references/layout.md) finds it
|
|
246
|
+
from the devtools console in under a minute; don't guess at CSS first.
|
|
247
|
+
|
|
248
|
+
Two gates before promising a push will work: Superwall for Agents is in
|
|
249
|
+
private beta and must be enabled on each app you push to (`superwall apps
|
|
250
|
+
list --json` → `features_enabled` lists `headless_paywalls`; a refused push
|
|
251
|
+
says "Superwall for Agents is in private beta and isn't enabled for this
|
|
252
|
+
app yet" — support@superwall.com turns it on), and every product named in a
|
|
253
|
+
`config.ts` must exist on the dashboard.
|
|
@@ -0,0 +1,340 @@
|
|
|
1
|
+
# CLI — dev, push, promote, publish
|
|
2
|
+
|
|
3
|
+
Git semantics on purpose: **push saves, promote ships.** Every push mints
|
|
4
|
+
a sealed version; nothing users see changes until promote points
|
|
5
|
+
production at it.
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
superwall create # scaffold superwall/ inside your app
|
|
9
|
+
superwall dev # studio on http://localhost:6100
|
|
10
|
+
superwall push # build + version. Production untouched.
|
|
11
|
+
superwall promote # point production at the latest push
|
|
12
|
+
superwall publish # push + promote in one step
|
|
13
|
+
superwall publish -m "Q3 test" # record why
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
The scaffolded package scripts mirror these (`dev`, `push`, `promote`,
|
|
17
|
+
`ship`). Auth: `superwall login` once interactively; in CI set
|
|
18
|
+
`SUPERWALL_API_KEY` (an `sk_…` key). `dev` needs no login.
|
|
19
|
+
|
|
20
|
+
## `superwall create`
|
|
21
|
+
|
|
22
|
+
Inside an app that already has a `superwall/` project (or inside the
|
|
23
|
+
project), `create` adds a paywall to it — a starter named as the user
|
|
24
|
+
answers (`-y` takes "Pro", ids stay unique), or the rebuilt dashboard
|
|
25
|
+
paywall with `--from` — and touches nothing else; `--example` and `--app`
|
|
26
|
+
are for new projects only.
|
|
27
|
+
|
|
28
|
+
`--example <name>` starts from a public example. `--app <id>` connects that
|
|
29
|
+
Superwall app instead of detecting one from the SDK key or asking — the
|
|
30
|
+
dashboard's **Copy Prompt** button hands you this form, so use the id it
|
|
31
|
+
gives rather than picking; it fails if the id isn't in the account, and it
|
|
32
|
+
cannot be combined with `--no-connect`. `--yes` accepts the defaults,
|
|
33
|
+
`--no-install` skips dependencies.
|
|
34
|
+
|
|
35
|
+
`--from <paywall-id>` rebuilds a dashboard (visual editor) paywall as
|
|
36
|
+
code: it scaffolds `paywalls/<slug>/config.ts` from the paywall's
|
|
37
|
+
products, presentation, settings, background and locales, writes
|
|
38
|
+
`paywalls/<slug>/MIGRATION.md` (source URL, screenshot, product table,
|
|
39
|
+
inventory of pages / actions / product variables), records the source in
|
|
40
|
+
`superwall.lock` under `origins` (which is what puts **Compare ›
|
|
41
|
+
Original** in the studio), and connects the paywall's app. Needs a login;
|
|
42
|
+
refuses `--example`, `--no-connect`, and a paywall that is already code.
|
|
43
|
+
The rebuild itself is
|
|
44
|
+
[migrate-from-editor.md](migrate-from-editor.md). After the scaffold the
|
|
45
|
+
CLI asks whether to run the rebuild headless with the user's agent, copy
|
|
46
|
+
the prompt, or stop; `superwall migrate <paywall-id>` asks the same later
|
|
47
|
+
(and scaffolds first if needed), `--skill` prints the prompt. When *you*
|
|
48
|
+
are the agent driving it, read the playbook and do the inventory step with
|
|
49
|
+
the user rather than running the headless path.
|
|
50
|
+
|
|
51
|
+
## `superwall migrate --screen <path>`
|
|
52
|
+
|
|
53
|
+
Rebuilds a native screen — SwiftUI or UIKit (`.swift`), Jetpack Compose or
|
|
54
|
+
Android Views (`.kt`), React Native (`.tsx`), Flutter (`.dart`) — as a surface. The scan writes
|
|
55
|
+
`paywalls/<slug>/config.ts` (name, product slots from any store ids in the
|
|
56
|
+
source), a `MIGRATION.md` brief (strings, assets, links, actions mapped to
|
|
57
|
+
hooks, the placement to register) and an `origins` entry in
|
|
58
|
+
`superwall.lock`, then offers the same agent / copy / stop choice. No
|
|
59
|
+
path: it lists likely screens in the app and asks. `--screenshot <file>`
|
|
60
|
+
saves the original for **Compare › Original**; with a booted iOS simulator
|
|
61
|
+
it offers to capture one. `--skill` prints the prompt. The rebuild and the
|
|
62
|
+
wiring are [migrate-from-native.md](migrate-from-native.md).
|
|
63
|
+
|
|
64
|
+
## `superwall dev`
|
|
65
|
+
|
|
66
|
+
Hosts the studio for the project (or several:
|
|
67
|
+
`superwall dev examples/*`). Regenerates `superwall.d.ts` first, so route
|
|
68
|
+
and product types are always current. `--port/-p` (default 6100, moves to
|
|
69
|
+
the next free port), `--host` (default `0.0.0.0`).
|
|
70
|
+
|
|
71
|
+
It prints a **Device** URL and QR beside the studio one, for opening the
|
|
72
|
+
paywalls on a phone on the same wifi. If the app's App Transport Security
|
|
73
|
+
would block a plain-`http` dev server it offers to add the two `Info.plist`
|
|
74
|
+
keys — development builds only, and the SDK refuses a dev server outside a
|
|
75
|
+
sandbox build anyway, so they are pointless in a release.
|
|
76
|
+
|
|
77
|
+
Three consequences for you, not the user:
|
|
78
|
+
|
|
79
|
+
- **A preview asks a human for every outcome** — purchase, restore,
|
|
80
|
+
permission, callback. Nothing resolves on its own, so never claim a
|
|
81
|
+
purchase flow is verified from `superwall dev`; ask the user to click, or
|
|
82
|
+
verify on a pushed URL.
|
|
83
|
+
- **A screenshot needs a promoted version.** The studio's download button
|
|
84
|
+
captures the published document, so it stays disabled until `promote` has
|
|
85
|
+
made one live — a push alone is not enough. Never tell a user to expect a
|
|
86
|
+
screenshot of a paywall nobody has promoted. What it saves is the
|
|
87
|
+
1290 x 2796 render, the App Store size Apple takes for a product page and
|
|
88
|
+
for subscription review attachments, so it uploads without resizing.
|
|
89
|
+
- **It previews, it never edits.** The dashboard hosts the same studio for a
|
|
90
|
+
code-first paywall (its live snapshot plus every pushed version), so never
|
|
91
|
+
tell the user to change a headless paywall there — changes ship through
|
|
92
|
+
`push`/`promote`/`publish`.
|
|
93
|
+
|
|
94
|
+
The mechanism behind both (the envelope, the `ping` reply, hosting a paywall
|
|
95
|
+
yourself) is `curl -sL superwall.com/docs/framework/host-protocol.md`.
|
|
96
|
+
|
|
97
|
+
Scanning the Device QR on a phone on the same wifi opens `/device`: the studio's
|
|
98
|
+
overview labelled "Preview" — same design, search, and live surface
|
|
99
|
+
cards — and tapping a card opens the hosted editor for that surface, as
|
|
100
|
+
on a desktop. For in-app, on-device rendering through real placements, set
|
|
101
|
+
the iOS SDK's `SuperwallOptions.devServer` (`.default` reaches a simulator;
|
|
102
|
+
iOS SDK ≥ 4.17.0) — simulators find the dev server on localhost ports
|
|
103
|
+
6100–6104 automatically; physical devices also need
|
|
104
|
+
`SuperwallOptions.devServer = .url(<the printed Device URL's origin>)`.
|
|
105
|
+
The SDK reads `/device/manifest.json` to map each dashboard paywall to
|
|
106
|
+
its local surface via `superwall.lock`, activates test mode, and skips
|
|
107
|
+
preloading. Each manifest surface also carries the settings block
|
|
108
|
+
`superwall push` stamps (`presentation_style`, `feature_gating`,
|
|
109
|
+
`on_device_cache`, `scroll_enabled`, `game_controller_enabled`,
|
|
110
|
+
`web_checkout_destination`, background hexes), computed by the same
|
|
111
|
+
`paywallSettingsOf` the push uses, so a `config.ts` change to presentation
|
|
112
|
+
or background shows on device without a push. An SDK that predates the
|
|
113
|
+
block, and the Android SDK, ignore it and keep the last promoted values —
|
|
114
|
+
so a `drawer` that presents fullscreen on device is an SDK-version
|
|
115
|
+
question, not a config one. The host app's Info.plist needs `NSAppTransportSecurity` →
|
|
116
|
+
`NSAllowsLocalNetworking` and `NSAllowsArbitraryLoadsInWebContent`.
|
|
117
|
+
|
|
118
|
+
The `/device` page also has an "Open in app" button. It resolves the app's
|
|
119
|
+
URL scheme automatically — the bound application's `apple_url_scheme` on
|
|
120
|
+
the dashboard first, then the app's own source (Info.plist,
|
|
121
|
+
`app.json`/`app.config.json`, `AndroidManifest.xml`) — and only asks for
|
|
122
|
+
one when neither has it. Tapping it fires `<scheme>://?superwall_dev=<dev-server-origin>` —
|
|
123
|
+
routed through `Superwall.handleDeepLink`, this opens **the SDK's own
|
|
124
|
+
paywall debugger** with the dev server's surfaces in its picker, each
|
|
125
|
+
labelled `<id> (local)` and rendered straight from the dev server. No
|
|
126
|
+
push and no dashboard record is needed: a local surface is built from
|
|
127
|
+
the manifest (its URL plus the products its `config.ts` declares), so
|
|
128
|
+
paywalls that have never been pushed preview too. Append
|
|
129
|
+
`&superwall_dev_surface=<id>` to open one directly. The debugger's paywall list is searchable and split into
|
|
130
|
+
`Local · superwall dev` and `Published` sections — the published list
|
|
131
|
+
comes from the downloaded config, so both sources are switchable side by
|
|
132
|
+
side without a dashboard preview token.
|
|
133
|
+
|
|
134
|
+
Project problems (stray files in `app/`, duplicate routes) print as
|
|
135
|
+
warnings here — the same ones that block a push, so fix them as they
|
|
136
|
+
appear.
|
|
137
|
+
|
|
138
|
+
## Before pushing: create the products yourself
|
|
139
|
+
|
|
140
|
+
A push refuses if a `config.ts` names a product the dashboard doesn't have.
|
|
141
|
+
**Don't hand that back to the user as a blocker — create them.** The
|
|
142
|
+
`superwall` CLI (see the `superwall` skill) writes products directly, so
|
|
143
|
+
"the dashboard needs products" is work you can do, not a dependency:
|
|
144
|
+
|
|
145
|
+
```sh
|
|
146
|
+
superwall entitlements list --json # grab the NUMERIC entitlement id
|
|
147
|
+
superwall products create <identifier> \
|
|
148
|
+
--project <id> --app <id> \
|
|
149
|
+
--name "Annual" --price 39.99 --period year \
|
|
150
|
+
--trial-days 7 --entitlement <numeric-id> --json
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
- `--entitlement` takes the **numeric id** (`55688`), not the identifier
|
|
154
|
+
(`pro`) — the identifier fails with a decode error.
|
|
155
|
+
- Pass `--project` explicitly when the account has several, or it errors
|
|
156
|
+
with "Multiple projects found".
|
|
157
|
+
- `--price` is major units (39.99); `--period` is `day|week|month|year`;
|
|
158
|
+
`--trial-days` sets the intro offer. `--dry-run` confirms the target first.
|
|
159
|
+
|
|
160
|
+
Derive identifiers and prices from the design. Where the design shows a
|
|
161
|
+
placeholder (`US$XX.xx`), pick an explicit stand-in and say so — never
|
|
162
|
+
invent a price silently.
|
|
163
|
+
|
|
164
|
+
Creating products writes to the user's real dashboard. Doing it is right
|
|
165
|
+
when they've asked you to push or to create them; name it in your summary
|
|
166
|
+
either way.
|
|
167
|
+
|
|
168
|
+
Two gates to check before promising a push will work:
|
|
169
|
+
|
|
170
|
+
- **Superwall for Agents is in private beta and must be enabled on each
|
|
171
|
+
app you push to** — otherwise the push stops with "Superwall for Agents
|
|
172
|
+
is in private beta and isn't enabled for this app yet." Nothing in the
|
|
173
|
+
CLI can set it; support@superwall.com turns it on. Check
|
|
174
|
+
`superwall apps list --json` → `features_enabled` for `headless_paywalls`.
|
|
175
|
+
- **One broken surface blocks the whole push.** A leftover scaffold aimed at
|
|
176
|
+
a nonexistent product stops everything — push what you built with repeated
|
|
177
|
+
`--id` flags instead of touching unrelated directories.
|
|
178
|
+
|
|
179
|
+
## `superwall push`
|
|
180
|
+
|
|
181
|
+
Builds every paywall, versions the changed ones, and leaves production
|
|
182
|
+
alone. Re-running with nothing changed is a no-op. Flags: `--id <id>`
|
|
183
|
+
(limit, repeatable), `--platform <p>` (repeatable or comma-separated; limits the platforms),
|
|
184
|
+
`--rename <old>=<new>`, `-m <note>`.
|
|
185
|
+
|
|
186
|
+
A push refuses — before anything is written — when:
|
|
187
|
+
|
|
188
|
+
- a selected paywall has diagnostics (publishing is immutable; fix first)
|
|
189
|
+
- a product in `config.ts` doesn't exist on the dashboard ("Every
|
|
190
|
+
variable on them would be undefined on device")
|
|
191
|
+
- a directory rename is unresolved (below)
|
|
192
|
+
- the project pushes to several platforms and a selected paywall has no
|
|
193
|
+
`platforms` field (below)
|
|
194
|
+
|
|
195
|
+
First push binds each paywall (creating it on Superwall if needed) and
|
|
196
|
+
records the binding in `superwall.lock`, per platform — commit it. After
|
|
197
|
+
that, push always updates the same paywalls; no IDs ever appear in your code.
|
|
198
|
+
|
|
199
|
+
### Several platforms
|
|
200
|
+
|
|
201
|
+
A project can push to several platforms — apps in the same Superwall
|
|
202
|
+
project (iOS + Android + web). `superwall.lock` binds one app per platform
|
|
203
|
+
under `apps`:
|
|
204
|
+
|
|
205
|
+
```json
|
|
206
|
+
{
|
|
207
|
+
"version": 1,
|
|
208
|
+
"apps": { "ios": "1001", "android": "1002", "web": "1003" },
|
|
209
|
+
"paywalls": {
|
|
210
|
+
"plus-upgrade": { "ios": { "paywallId": "2001" }, "android": { "paywallId": "2002" } },
|
|
211
|
+
"web-upgrade": { "web": { "paywallId": "2003" } }
|
|
212
|
+
},
|
|
213
|
+
"funnels": {}
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Each paywall says which platforms it ships to in `config.ts` — a typed
|
|
218
|
+
array of `ios | android | web`:
|
|
219
|
+
|
|
220
|
+
```ts
|
|
221
|
+
export default definePaywall({ platforms: ["ios", "android"], products: { … } }); // shared
|
|
222
|
+
export default definePaywall({ platforms: ["web"], checkout: "sheet", products: { … } }); // web only
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
- One directory, one dashboard paywall **per platform**, each with its own
|
|
226
|
+
versions; push output labels them `plus-upgrade · ios`.
|
|
227
|
+
- `platforms` is optional while the project is on one platform;
|
|
228
|
+
**required once it has more** — push stops on a silent paywall instead of
|
|
229
|
+
guessing. Annotate every existing paywall when you add a second platform.
|
|
230
|
+
No project-wide default exists; to mirror a set everywhere, spread a
|
|
231
|
+
shared constant (`{ platforms: ["ios", "android", "web"] } as const`).
|
|
232
|
+
- A new platform binds its app on the first push: automatic when the
|
|
233
|
+
account has exactly one app of it, a prompt when it has several, an
|
|
234
|
+
error when it has none. In CI, either bind once interactively or add
|
|
235
|
+
`"web": "<app id>"` under `apps` yourself (`superwall apps list --json`
|
|
236
|
+
for ids) — the one hand edit the lock invites.
|
|
237
|
+
- `--platform <p>` (or a bound app id) narrows push/promote/publish;
|
|
238
|
+
`promote --version` needs it when the paywall is on several platforms.
|
|
239
|
+
- Store products differ per store, so a shared slot takes one id per
|
|
240
|
+
platform: `annual: { ios: "pro_year", android: "pro_year_play", web:
|
|
241
|
+
"live:price_…:trial" }` — `purchase("annual")` is unchanged; each
|
|
242
|
+
platform's build resolves the slot to its own id (the map is rewritten
|
|
243
|
+
out of the bundle) and its version carries the matching store (Play for
|
|
244
|
+
android), so an Android build never names an App Store product. A
|
|
245
|
+
per-platform slot must name every platform in `platforms` (push error:
|
|
246
|
+
`` `annual` has no product id for web ``). The dashboard product check
|
|
247
|
+
runs per platform, so create the Play product too.
|
|
248
|
+
|
|
249
|
+
### Renames
|
|
250
|
+
|
|
251
|
+
Renaming a paywall directory is detected, never guessed. Interactively,
|
|
252
|
+
push asks:
|
|
253
|
+
|
|
254
|
+
```
|
|
255
|
+
? `pro-upgrade` is not in superwall.lock. Is it a new paywall, or renamed?
|
|
256
|
+
› Renamed from plus-upgrade paywall 208540
|
|
257
|
+
Create a new paywall
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
Choosing the rename keeps the live paywall attached to the new directory.
|
|
261
|
+
In CI, declare it — anything unresolved stops the push rather than
|
|
262
|
+
creating a duplicate:
|
|
263
|
+
|
|
264
|
+
```sh
|
|
265
|
+
superwall push --rename plus-upgrade=pro-upgrade
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
Deleting a paywall directory never blocks a push — the dashboard paywall
|
|
269
|
+
keeps serving, and restoring the directory re-binds it.
|
|
270
|
+
|
|
271
|
+
### Paywall settings ship with the version
|
|
272
|
+
|
|
273
|
+
Presentation style (`presentation: { style: "drawer", drawer: { height,
|
|
274
|
+
cornerRadius } }`), `featureGating`, `onDeviceCacheEnabled`,
|
|
275
|
+
`scrollEnabled`, `gameControllerEnabled`, plus `checkout` (as the web
|
|
276
|
+
checkout destination) and `background`, are read from `config.ts` at build
|
|
277
|
+
time, stored on the pushed version, and applied to the paywall on promote. A
|
|
278
|
+
headless paywall has no dashboard editor, so never tell the user to change
|
|
279
|
+
these in the dashboard; edit the config and push. Omitted keys reset to the
|
|
280
|
+
defaults (fullscreen, non-gated, cached, scrolling, no controller) on the
|
|
281
|
+
next promote.
|
|
282
|
+
|
|
283
|
+
### Source
|
|
284
|
+
|
|
285
|
+
Every push also snapshots your `superwall/` source to Superwall, so the
|
|
286
|
+
dashboard can show and diff the code each version was built from — and
|
|
287
|
+
`-m "why"` records the reason there. `.env`, `node_modules/`, and
|
|
288
|
+
gitignored files never leave the machine. If any import reaches outside
|
|
289
|
+
the project directory, the push warns and the dashboard disables remote
|
|
290
|
+
editing for that paywall (docs: `project-structure`).
|
|
291
|
+
|
|
292
|
+
## `superwall promote`
|
|
293
|
+
|
|
294
|
+
Points production at a pushed version. `--id <id>` to limit;
|
|
295
|
+
`--version/-v <n>` (with a single `--id`) to pick one — which is also the
|
|
296
|
+
**rollback**:
|
|
297
|
+
|
|
298
|
+
```sh
|
|
299
|
+
superwall promote --id plus-upgrade --version 5
|
|
300
|
+
# → Rolled back version 7 → 5
|
|
301
|
+
superwall promote --id plus-upgrade --platform ios --version 5 # on several platforms
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
Promote never rebuilds — it only moves the live pointer.
|
|
305
|
+
|
|
306
|
+
## `superwall publish`
|
|
307
|
+
|
|
308
|
+
Push + promote in one step. Also warns about other paywalls that are
|
|
309
|
+
pushed-but-not-live, so nothing ships half-forgotten.
|
|
310
|
+
|
|
311
|
+
## The studio's Push / Publish / Promote buttons
|
|
312
|
+
|
|
313
|
+
Same operations from the `dev` UI — good for iteration. Prefer the CLI
|
|
314
|
+
for shipping: the buttons skip the diagnostics gate and the dashboard
|
|
315
|
+
product check, can't resolve renames, and take no `-m` note.
|
|
316
|
+
|
|
317
|
+
The studio's **Compare** menu lists every pushed version of the paywall
|
|
318
|
+
(the live one marked) plus the project's other paywalls, and splits the
|
|
319
|
+
stage between the chosen one and the local build. It needs a login and a
|
|
320
|
+
bound paywall; when the versions can't be read, the menu says why rather
|
|
321
|
+
than listing none.
|
|
322
|
+
|
|
323
|
+
## Troubleshooting
|
|
324
|
+
|
|
325
|
+
| Message | Fix |
|
|
326
|
+
| --- | --- |
|
|
327
|
+
| `Not a superwall project` | Run inside the app (or `superwall/`); the project's `package.json` must depend on `superwall` |
|
|
328
|
+
| `…package.json is named "superwall"` | Rename the package — that name shadows the framework |
|
|
329
|
+
| `No superwall framework found` | `bun add superwall` (or npm) inside the project |
|
|
330
|
+
| `These N products do not exist on Superwall` | Create them with `superwall products create` (above) — don't just report it — or fix the identifiers in `config.ts` |
|
|
331
|
+
| `Superwall for Agents is in private beta and isn't enabled for this app yet` | Enabled per app on Superwall's side; contact support@superwall.com. Nothing in the CLI can set it |
|
|
332
|
+
| `Multiple projects found. Pass --project <id>.` | Add `--project <id>` (and usually `--app <id>`) to the resource command |
|
|
333
|
+
| Diagnostics block the push | The message names each stray file and where it belongs |
|
|
334
|
+
| Rename ambiguity in CI | Add the printed `--rename old=new` |
|
|
335
|
+
| `x doesn't say which platforms it's for` | The project pushes to several platforms — add `platforms: [...]` to that `config.ts` |
|
|
336
|
+
| `Several iOS apps in your account` / `no Web app to bind` | Run push interactively once, add `"web": "<app id>"` under `apps` in `superwall.lock`, or `superwall apps create --platform web` |
|
|
337
|
+
| `This project has no app for "…"` | `--platform` takes a platform bound in `superwall.lock` (or that app's id); the message lists them |
|
|
338
|
+
| `paywall x has never been pushed` (promote) | Push first |
|
|
339
|
+
| `superwall publish requires git` | Install git — the source snapshot is part of every publish |
|
|
340
|
+
| Not signed in | `superwall login`, or `SUPERWALL_API_KEY` in CI |
|