@superwall/cli 1.6.2 → 2.0.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 +281 -34
- package/dist/apple-CkKlHBZ9.js +195 -0
- package/dist/auth.d.ts +4 -19
- package/dist/auth.js +4 -2
- package/dist/{actions-H7f6knyY.js → billing-XCZU_T46.js} +98 -28
- package/dist/{bind-BIzaGq8K.js → bind-drne__Ys.js} +38 -33
- package/dist/{build-B7BS1rF2.js → build-Gpdq5QXP.js} +20 -26
- package/dist/client-BZ1UbpXz.js +66 -0
- package/dist/client-DP6Rc0t_.js +176 -0
- package/dist/config-BO1Y87kV.js +105 -0
- package/dist/create-BBrtgUgS.js +969 -0
- package/dist/{create-CwnnNqv4.js → create-Cwc3SRWJ.js} +194 -168
- package/dist/create-Yvf2gStM.js +19 -0
- package/dist/doctor-C9ldpPFC.js +83 -0
- package/dist/{drivers-6RMOPIdn.js → drivers-DNrx4LWA.js} +185 -172
- package/dist/entry.d.ts +0 -5
- package/dist/entry.js +28083 -801
- package/dist/environment-DF1qKlny.js +58 -0
- package/dist/{existing-DHpPn1y6.js → existing-78LWSsqS.js} +12 -6
- package/dist/held-Cy8Wl4D1.js +1112 -0
- package/dist/held-Ddw1XSsr.js +16 -0
- package/dist/input-vi0bou04.js +42 -0
- package/dist/{integrate-BR2LR-EK.js → integrate-DcJhpXy8.js} +277 -253
- package/dist/kinds-GFXB3sYu.js +11 -0
- package/dist/log-NVhVe_oe.js +62 -0
- package/dist/login-B2TsCE2H.js +53 -0
- package/dist/login-BoBe8Psl.js +16 -0
- package/dist/{login-Bhxgqwtm.js → login-D0lh3_JI.js} +144 -66
- package/dist/lookup-D-nmmAbw.js +71 -0
- package/dist/migrate-Cfec564E.js +274 -0
- package/dist/notification-url-YDbq6FMA.js +100 -0
- package/dist/{open-studio-BnVD6tJ9.js → open-Ba2vBl1_.js} +34 -43
- package/dist/org-D0g_q3mv.js +35 -0
- package/dist/output-Ggzq5_-t.js +122 -0
- package/dist/paths-DxSLdpOI.js +29 -0
- package/dist/playbook-DIeb7hne.js +53 -0
- package/dist/{asc-products-Dvcyef3_.js → products-DH_fK9tY.js} +6 -39
- package/dist/promote-COD4fYdz.js +91 -0
- package/dist/push-CncywhkQ.js +482 -0
- package/dist/push-CtD4FZQV.js +22 -0
- package/dist/registry-DSrosOYs.js +10228 -0
- package/dist/{reports-DqMs9xNR.js → reports-DdPq4blM.js} +7 -6
- package/dist/{resources-Bf9O1JNM.js → resources-Dqr01Dep.js} +150 -55
- package/dist/{run-D-NbZLpj.js → run-C9qg_QlC.js} +16 -22
- package/dist/scan-Cv5uOwVY.js +4 -0
- package/dist/{scan-BmAW413l.js → scan-DLrsrFS9.js} +48 -37
- package/dist/scope-V336uz8j.js +198 -0
- package/dist/screenshot-file-0UETadF8.js +16 -0
- package/dist/{selection-BGi6GyxC.js → selection-Rdw-ZUoG.js} +94 -51
- package/dist/send-BxD9yf6F.js +150 -0
- package/dist/{dev-CgGAb5Al.js → server-D0tGG8C4.js} +82 -87
- package/dist/server-z1LH94R_.js +22 -0
- package/dist/session-1AV_Bs_d.js +6 -0
- package/dist/session-CFAmMhem.js +40 -0
- package/dist/session-D_nEWKXT.js +768 -0
- package/dist/skills/animate-onboarding/SKILL.md +467 -0
- package/dist/skills/animate-onboarding/references/engine.md +494 -0
- package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
- package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
- package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
- package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
- package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
- package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
- package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
- package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
- package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
- package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
- package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
- package/dist/skills/animate-onboarding/references/performance.md +41 -0
- package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
- package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
- package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
- package/dist/skills/index.json +37 -0
- package/dist/skills/mobile-design/SKILL.md +447 -0
- package/dist/skills/mobile-design/references/responsive.md +162 -0
- package/dist/skills/onboarding-questions/SKILL.md +231 -0
- package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
- package/dist/skills/onboarding-questions/references/craft.md +142 -0
- package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
- package/dist/skills/superwall/SKILL.md +82 -9
- package/dist/skills/superwall/references/api.md +153 -37
- package/dist/skills/superwall/references/apple-setup.md +316 -0
- package/dist/skills/superwall/references/asc.md +74 -38
- package/dist/skills/superwall/references/data-analytics.md +55 -21
- package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
- package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
- package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
- package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
- package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
- package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
- package/dist/skills/superwall/workflows/placements/android.md +2 -2
- package/dist/skills/superwall/workflows/placements/expo.md +2 -2
- package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
- package/dist/skills/superwall/workflows/placements/ios.md +2 -2
- package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
- package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
- package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
- package/dist/skills/superwall/workflows/review/playbook.md +1 -1
- package/dist/skills/superwall-editor/SKILL.md +61 -0
- package/dist/skills/superwall-editor/references/cli.md +135 -0
- package/dist/skills/superwall-editor/references/design.md +51 -0
- package/dist/skills/superwall-editor/references/native-elements.md +171 -0
- package/dist/skills/superwall-editor/references/workflow.md +65 -0
- package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
- package/dist/skills/superwall-framework/SKILL.md +78 -28
- package/dist/skills/superwall-framework/references/cli.md +58 -28
- package/dist/skills/superwall-framework/references/examples.md +4 -3
- package/dist/skills/superwall-framework/references/layout.md +30 -8
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
- package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
- package/dist/skills/wwdc/SKILL.md +22 -0
- package/dist/skills/wwdc/references/docs.md +52 -0
- package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
- package/dist/{skills-AxAf7bDB.js → skills-BvFOa4y6.js} +99 -122
- package/dist/skills-DMG4bpKk.js +14 -0
- package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
- package/dist/spinner-CneRK5rk.js +294 -0
- package/dist/storage-DYvmIOHa.d.ts +16 -0
- package/dist/storage-s2Dnz-yl.js +31 -0
- package/dist/storekit-DafAnGkM.js +16 -0
- package/dist/storekit-yY_kS2iR.js +47 -0
- package/dist/telemetry-DtG92m5O.js +56 -0
- package/dist/theme-DUsCh-Vd.js +25 -0
- package/dist/timing-BVxPrYq3.js +5 -0
- package/dist/{token-BGAVPSQc.js → token-DzRh7dI1.js} +6 -38
- package/dist/tools.d.ts +96 -0
- package/dist/tools.js +11178 -0
- package/dist/ui-D_qf3Gvw.js +53 -0
- package/dist/upgrade-Bt4Ouw1y.js +117 -0
- package/dist/upgrade-Cqy5orjb.js +7 -0
- package/package.json +10 -5
- package/dist/api-Dv3LyZ5m.js +0 -151
- package/dist/api-output-aJNw7Syy.js +0 -20
- package/dist/app-mJC5NDtW.js +0 -189
- package/dist/asa-D6H7Pjae.js +0 -1194
- package/dist/asc-xCin0akG.js +0 -539
- package/dist/auth-ZlLL-Gko.js +0 -139
- package/dist/billing-C8kBge_S.js +0 -80
- package/dist/command-3fGYyC8r.js +0 -301
- package/dist/dev-Dx99K183.js +0 -22
- package/dist/doctor-CyUvut31.js +0 -88
- package/dist/feedback-RKyGuQ8_.js +0 -152
- package/dist/hosted-BeGVAntr.js +0 -32
- package/dist/migrate-C-4ISELN.js +0 -284
- package/dist/org-CQduIOic.js +0 -40
- package/dist/output-C-4UKMot.js +0 -136
- package/dist/params-l3CrvRtR.js +0 -51
- package/dist/pipeline-CHX0Syre.js +0 -977
- package/dist/print-skill-BiZLdCKv.js +0 -74
- package/dist/promote-Pgpz-3xl.js +0 -88
- package/dist/publish-BPeuc3lq.js +0 -35
- package/dist/push-DcSQ4odB.js +0 -35
- package/dist/query-CWLaZkdm.js +0 -53
- package/dist/resource-jwASPCrw.js +0 -483
- package/dist/skills-FK5aDuNV.js +0 -64
- package/dist/spinner-DFctF_Jw.js +0 -18
- package/dist/storekit-CC4gnTI6.js +0 -29
- package/dist/telemetry-Ch9cCTI-.js +0 -169
- package/dist/ui-4gLyfrgl.js +0 -27737
- package/dist/update-DIXbL-H9.js +0 -59
- package/dist/upgrade-De7JMI1g.js +0 -72
- /package/dist/{devtools-8EgLo86w.js → devtools-ByZ6XYnn.js} +0 -0
|
@@ -34,7 +34,7 @@ dashboard paywall built in the visual editor (`"headless": false` in
|
|
|
34
34
|
```
|
|
35
35
|
superwall/paywalls/<id>/
|
|
36
36
|
├── config.ts definePaywall({ name, platforms: ["ios", "android"], products: { annual: "pro_5999_year" } })
|
|
37
|
-
├── app/ routes only — index.tsx, plans.tsx, layout.tsx (reserved)
|
|
37
|
+
├── app/ routes only — index.tsx, plans.tsx, layout.tsx (reserved; may export `entry`, the stack to open on)
|
|
38
38
|
├── components/ everything that is not a route
|
|
39
39
|
└── messages/en.ts strings, discovered by filename
|
|
40
40
|
```
|
|
@@ -43,7 +43,7 @@ Entry points: `superwall` (SuperwallProvider — mounted for you),
|
|
|
43
43
|
`superwall/config`, `superwall/hooks`, `superwall/navigation`,
|
|
44
44
|
`superwall/assets`.
|
|
45
45
|
|
|
46
|
-
The framework
|
|
46
|
+
The framework ships on the `next` channel. The CLI has
|
|
47
47
|
`create`/`dev`/`push`/`promote`/`publish` and the rebuild forms of `migrate`
|
|
48
48
|
only while `SUPERWALL_CHANNEL=next` is set in the environment.
|
|
49
49
|
`Unknown command: create` means the variable is missing from your
|
|
@@ -57,6 +57,7 @@ web page inside an app.
|
|
|
57
57
|
|
|
58
58
|
| Task | Reference |
|
|
59
59
|
| --- | --- |
|
|
60
|
+
| **Any onboarding, quiz, survey or multi-page funnel that asks questions — must-follow.** Every answer a typed user attribute (`useUserAttribute`) saved the moment it is given, one `next` for the buttons and `entry`, `replayStack` resuming at the first unanswered question of the user's branch, attribute naming, back and "Start over" after resuming | [references/onboarding-state.md](references/onboarding-state.md) |
|
|
60
61
|
| 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) |
|
|
61
62
|
| Mobile design craft — press feedback, hover gating, inputs and the keyboard, motion values, type, worst-case content, dark mode, platform conventions, the pre-ship audit. **Read it for every new screen, and especially when there is no design reference: its values are then the design.** | the **`mobile-design`** skill (install: `npx skills add https://github.com/superwall/skills/tree/next --skill mobile-design --global --yes --agent claude-code universal --full-depth`); what the framework adds to it (the skeleton, insets, scrolling, its hooks) is [references/mobile-design.md](references/mobile-design.md) |
|
|
62
63
|
| Writing the questions of an onboarding or web2app funnel — what to ask, in what order, the branching, the statements, which answers predict revenue | the **`onboarding-questions`** skill (install: `npx skills add https://github.com/superwall/skills/tree/next --skill onboarding-questions --global --yes --agent claude-code universal --full-depth`) |
|
|
@@ -95,7 +96,8 @@ curl -sL https://superwall.com/docs/framework/{page}.md # one page
|
|
|
95
96
|
| Message catalogs, t(), locales | `localization` |
|
|
96
97
|
| Preload, entry animations, SDK events, dark mode | `lifecycle` |
|
|
97
98
|
| Images, video, fonts, Lottie/Rive, app-bundled local resources (`useLocalResource`) | `assets` |
|
|
98
|
-
| close/openUrl/permissions/callbacks
|
|
99
|
+
| close/openUrl/permissions/callbacks (`setUserAttributes` is deprecated: `useUserAttribute`) | `actions` |
|
|
100
|
+
| `useUserAttribute` / `readAttribute`, parsers | `hooks` |
|
|
99
101
|
| The messages a paywall exchanges with its host, hosting one yourself | `host-protocol` |
|
|
100
102
|
| Device/user/params records, personalization | `variables` |
|
|
101
103
|
| The dev studio, dev-vs-device differences | `studio` |
|
|
@@ -143,7 +145,8 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
143
145
|
4. **Dark mode is the `:root.dark` class the SDK stamps**, not
|
|
144
146
|
`prefers-color-scheme`.
|
|
145
147
|
5. **Routes are names on a stack** — no params, no order. Closing the
|
|
146
|
-
paywall is `useActions().close()`, not navigation.
|
|
148
|
+
paywall is `useActions().close()`, not navigation. Answers a flow
|
|
149
|
+
collects are user attributes (principle 6); other cross-route UI state
|
|
147
150
|
lives in `layout.tsx` or a plain module on a native paywall — but **on a
|
|
148
151
|
web funnel (`checkout` set) every answer, selection and input is
|
|
149
152
|
`useQueryState`, never `useState`**: an in-app browser hands only the
|
|
@@ -162,16 +165,47 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
162
165
|
bar) rides on top of the router's transition in a layout-level layer,
|
|
163
166
|
never instead of it. The `transitions` example and the
|
|
164
167
|
`animate-onboarding` skill show both halves.
|
|
165
|
-
6. **
|
|
168
|
+
6. **An onboarding remembers every answer, so a user who quits halfway
|
|
169
|
+
resumes where they left off.** Every answer is a user attribute, read and
|
|
170
|
+
written with `useUserAttribute(key, parser)` — `useQueryState`'s API with
|
|
171
|
+
the same parsers, kept by the host SDK across presentations and launches,
|
|
172
|
+
re-rendering at once. Keep the flow in one `next(route, user)` function:
|
|
173
|
+
the buttons push what it returns, and `app/layout.tsx` exports `entry`,
|
|
174
|
+
which replays it with `replayStack` (every answered page, then the first
|
|
175
|
+
unanswered one, down the branch the user actually took). `entry` runs
|
|
176
|
+
once with the host's attributes already in, so that page is the first
|
|
177
|
+
thing that paints. Never keep answers only in React state, a module or
|
|
178
|
+
`layout.tsx` (they die with the paywall), and never store the step or
|
|
179
|
+
page index: store the answers. Keys are stable snake_case meant to be
|
|
180
|
+
queried (`onboarding_goal`), values are enum ids read through
|
|
181
|
+
`parseAsStringEnum`, so an unknown or garbage value reads as `null`
|
|
182
|
+
(unanswered). Read
|
|
183
|
+
[references/onboarding-state.md](references/onboarding-state.md) before
|
|
184
|
+
building any multi-page question flow.
|
|
185
|
+
|
|
186
|
+
```tsx
|
|
187
|
+
const goals = parseAsStringEnum(["lose", "build", "endure"]);
|
|
188
|
+
const [goal, setGoal] = useUserAttribute("onboarding_goal", goals); // Goal | null
|
|
189
|
+
const choose = (value: Goal) => {
|
|
190
|
+
haptics.selection();
|
|
191
|
+
setGoal(value); // persisted by the host SDK
|
|
192
|
+
const to = next("goal", { ...user, onboarding_goal: value });
|
|
193
|
+
if (to) router.push(to);
|
|
194
|
+
};
|
|
195
|
+
// app/layout.tsx: the stack to open on, replayed once from the attributes
|
|
196
|
+
export const entry: Entry = ({ user }) =>
|
|
197
|
+
replayStack("index", (route) => next(route, user), (route) => answered(route, user));
|
|
198
|
+
```
|
|
199
|
+
7. **Links go through `useActions().openUrl`**, never `<a href>` — in a
|
|
166
200
|
webview an anchor does nothing or navigates the paywall away.
|
|
167
|
-
|
|
201
|
+
8. **Haptics on every meaningful tap** (`light` navigate, `selection`
|
|
168
202
|
choose, `success` purchase) — iOS fires nothing of its own. Icon
|
|
169
203
|
buttons carry `aria-label`; tap targets ≥ 44px. Every control answers
|
|
170
204
|
the press itself (`:active`, ~0.96 scale), every `:hover` sits inside
|
|
171
205
|
`@media (hover: hover) and (pointer: fine)` (a webview keeps a fake
|
|
172
206
|
hover after a tap), and inputs are 16px or larger (iOS zooms the page
|
|
173
207
|
on anything smaller).
|
|
174
|
-
|
|
208
|
+
9. **Motion is `transform` and `opacity`, nothing else, and UI feedback is
|
|
175
209
|
under 300ms.** This is the rule every first paywall breaks: a plan card
|
|
176
210
|
whose selection animates `border-color`, `background` or `box-shadow`,
|
|
177
211
|
and a 450ms staggered entrance. Transitions name their properties on a
|
|
@@ -191,16 +225,18 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
191
225
|
```
|
|
192
226
|
|
|
193
227
|
The tokens, durations and the audit are in the `mobile-design` skill.
|
|
194
|
-
|
|
228
|
+
10. **`await restore()`** — it resolves `{ status: "restored" }` or
|
|
195
229
|
`{ status: "failed" }`. "Nothing to restore" is not distinguishable
|
|
196
230
|
from a store error: the SDK writes that explanation to its own logs,
|
|
197
231
|
never over the protocol, so write copy covering both. The lifecycle
|
|
198
232
|
also lands on `useSuperwallSnapshot().restore` (iOS sends all three of
|
|
199
233
|
`restore_start/complete/fail`, Android only `restore_fail`).
|
|
200
|
-
|
|
201
|
-
hand — the
|
|
202
|
-
|
|
203
|
-
|
|
234
|
+
11. **Commit `superwall.lock` and `superwall.d.ts`.** Never edit either by
|
|
235
|
+
hand — the exceptions are adding an app under `apps` when CI can't
|
|
236
|
+
prompt, and the binding line a push prints for a paywall the user
|
|
237
|
+
confirms is theirs. The lock also records the source commit each app was
|
|
238
|
+
last synced to, the base the next push merges from.
|
|
239
|
+
12. **One project, several platforms.** `superwall.lock` binds one
|
|
204
240
|
Superwall app per platform under `apps` (`ios`, `android`, `web`), and
|
|
205
241
|
a paywall lists the platforms it ships
|
|
206
242
|
to with `platforms: [...]` in `config.ts` (typed) — optional on one
|
|
@@ -223,19 +259,19 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
223
259
|
hosts it as the web paywall app hosts editor paywalls: the SDK prices
|
|
224
260
|
the Stripe products, reports the events and finishes the checkout, so
|
|
225
261
|
`register()` resolves `purchased`, with no redemption step.
|
|
226
|
-
|
|
262
|
+
13. **Shipping includes the dashboard.** A push that fails on missing
|
|
227
263
|
products is not a blocker to report — create them with
|
|
228
264
|
`superwall products create` ([references/cli.md](references/cli.md)).
|
|
229
265
|
Treat "make this live" as spanning code *and* the resources it needs.
|
|
230
|
-
|
|
231
|
-
email on a page must
|
|
232
|
-
the moment it has it — that is what puts it on the Stripe session as
|
|
266
|
+
14. **A captured email must reach checkout.** A funnel that asks for the
|
|
267
|
+
email on a page must save it as the `email` user attribute
|
|
268
|
+
(`useUserAttribute("email")`'s setter) the moment it has it — that is what puts it on the Stripe session as
|
|
233
269
|
`customer_email` (shown, not editable) and re-warms the prefetched
|
|
234
270
|
session. Page state alone never reaches checkout. Same for a
|
|
235
271
|
`stripe_customer_id`. Fetch `web-checkout` → "The shopper's email".
|
|
236
|
-
|
|
272
|
+
15. **Build the design reference 1:1.** Add nothing it doesn't show;
|
|
237
273
|
effects (shadows, gradients) are design decisions, not defaults.
|
|
238
|
-
|
|
274
|
+
16. **The paywall is inset by default; never write `env()` and never
|
|
239
275
|
`position: fixed`.** The framework's root box pads the whole paywall
|
|
240
276
|
by the safe area, resolved per platform, screen and presentation
|
|
241
277
|
(iPhone island/notch/home button, iPad, Android's status bar, a
|
|
@@ -249,18 +285,18 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
249
285
|
bleed, and only chrome over a bleed reads `--sw-safe-area-inset-*`.
|
|
250
286
|
When something sits under a bar, run the debugging order in
|
|
251
287
|
[references/layout.md](references/layout.md) before touching CSS.
|
|
252
|
-
|
|
288
|
+
17. **A non-white background goes in `config.ts`, not only in CSS.**
|
|
253
289
|
`--sw-background` paints the routes; `background` in config is what
|
|
254
290
|
the framework writes on `<html>`, and `<html>` is what shows when an
|
|
255
291
|
iOS scroll rubber-bands past the end of the content. Set only the CSS
|
|
256
292
|
variable and every bounce flashes white — worst on a dark paywall.
|
|
257
293
|
Set both, to the same colors, in the same change.
|
|
258
|
-
|
|
294
|
+
18. **A paywall is finished on the smallest and the largest screen it
|
|
259
295
|
ships to**, not on the default frame: iPhone SE at 320–375 wide and
|
|
260
296
|
667 tall, an island phone, a Pixel, an iPad, landscape where the app
|
|
261
297
|
allows it, and the configured presentation style
|
|
262
298
|
(`responsive.md` in the `mobile-design` skill).
|
|
263
|
-
|
|
299
|
+
19. **Every user-facing string is a message, from the first commit, even
|
|
264
300
|
in one language.** Copy lives in `messages/en.ts` (shared, or per
|
|
265
301
|
paywall) and reaches the page through `useTranslation().t("key")`,
|
|
266
302
|
`aria-label`s and button labels included; never a literal in JSX. A
|
|
@@ -268,7 +304,7 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
268
304
|
never in a catalog: interpolate them (`"Subscribe · {price}"`) and
|
|
269
305
|
guard on the value with a bare-key fallback. The scaffold starts this
|
|
270
306
|
way; keep it that way (docs: `localization`).
|
|
271
|
-
|
|
307
|
+
20. **Any host the surface calls must be named in `allowedHosts`.** A
|
|
272
308
|
published paywall is served under a Content-Security-Policy that
|
|
273
309
|
permits Superwall and Stripe and nothing else, so a `fetch` to a
|
|
274
310
|
customer's own API — saving quiz answers, capturing a lead, a custom
|
|
@@ -285,6 +321,14 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
|
|
|
285
321
|
all, so a local API works there unnamed and a missing host is only ever
|
|
286
322
|
caught after deploy unless you write it up front (docs: `config`,
|
|
287
323
|
`troubleshooting`).
|
|
324
|
+
21. **Never require `localStorage` or `sessionStorage`.** In the Android
|
|
325
|
+
SDK's WebView both are `null`. They aren't `undefined`, so a `typeof`
|
|
326
|
+
guard passes and the call throws. An unguarded read in a render or an
|
|
327
|
+
effect unmounts the whole paywall and leaves a blank screen the user
|
|
328
|
+
can't leave. Keep state that spans pages in React (it lives for the
|
|
329
|
+
whole presentation), and state that must outlast it in a user
|
|
330
|
+
attribute (`useUserAttribute`), which the host persists. Use storage only for something optional, inside a
|
|
331
|
+
`try`/`catch` that treats a failure as unset (docs: `troubleshooting`).
|
|
288
332
|
|
|
289
333
|
## Working loop
|
|
290
334
|
|
|
@@ -303,12 +347,11 @@ on every preset, both schemes. When a layout bug appears, the numbered
|
|
|
303
347
|
debugging order in [references/layout.md](references/layout.md) finds it
|
|
304
348
|
from the devtools console in under a minute; don't guess at CSS first.
|
|
305
349
|
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
`config.ts` must exist on the dashboard.
|
|
350
|
+
Before promising a push will work, check that every product named in a
|
|
351
|
+
`config.ts` exists on the dashboard. A push merges onto teammates' source
|
|
352
|
+
and stops naming the files when it can't; `--overwrite-source` discards
|
|
353
|
+
their work, so pass it only when the user says to
|
|
354
|
+
([references/cli.md](references/cli.md)).
|
|
312
355
|
|
|
313
356
|
## Report what's broken
|
|
314
357
|
|
|
@@ -319,6 +362,13 @@ on, however small. Write it with every ID needed to reproduce it, tell the
|
|
|
319
362
|
user in one line, send on their yes (or straight away if they've said you
|
|
320
363
|
may). Strip secrets and customer data.
|
|
321
364
|
|
|
365
|
+
First make sure it still happens on the latest release, since it may already be
|
|
366
|
+
fixed: compare `superwall --version` and the project's `superwall` dependency
|
|
367
|
+
with `npm view superwall version`. If either is older, run `superwall upgrade`
|
|
368
|
+
and `bun add superwall@latest` (or npm) in the project, then repeat what
|
|
369
|
+
failed. Fixed → tell the user which version fixed it and send nothing. Still
|
|
370
|
+
broken → report it with the versions you reproduced it on.
|
|
371
|
+
|
|
322
372
|
```bash
|
|
323
373
|
superwall feedback "Ran X; expected Y; got Z. Steps: …" --title "..." --kind bug \
|
|
324
374
|
--command "superwall push" --app <id> --context paywall=<id> \
|
|
@@ -15,7 +15,8 @@ superwall publish -m "Q3 test" # record why
|
|
|
15
15
|
|
|
16
16
|
The scaffolded package scripts mirror these (`dev`, `push`, `promote`,
|
|
17
17
|
`ship`). Auth: `superwall login` once interactively; in CI set
|
|
18
|
-
`SUPERWALL_API_KEY
|
|
18
|
+
`SUPERWALL_API_KEY`, which is only ever the organization's secret key
|
|
19
|
+
(`sk_…`), never an app's public `pk_…` key. `dev` needs no login.
|
|
19
20
|
|
|
20
21
|
## `superwall create`
|
|
21
22
|
|
|
@@ -66,12 +67,7 @@ wiring are [migrate-from-native.md](migrate-from-native.md).
|
|
|
66
67
|
Hosts the studio for the project (or several:
|
|
67
68
|
`superwall dev examples/*`). Regenerates `superwall.d.ts` first, so route
|
|
68
69
|
and product types are always current. `--port/-p` (default 6100, moves to
|
|
69
|
-
the next free port), `--host` (default `0.0.0.0`)
|
|
70
|
-
(development only: a chat worker's origin, default
|
|
71
|
-
`$SUPERWALL_STUDIO_AI_URL`, needs `superwall login` — an `sk_` key is
|
|
72
|
-
refused). `--chat` opens the studio's AI chat locally, and that chat edits
|
|
73
|
-
the source the app last pushed, inside a cloud sandbox — never the working
|
|
74
|
-
tree it is running in.
|
|
70
|
+
the next free port), `--host` (default `0.0.0.0`).
|
|
75
71
|
|
|
76
72
|
It prints a **Device** URL and QR beside the studio one, for opening the
|
|
77
73
|
paywalls on a phone on the same wifi. If the app's App Transport Security
|
|
@@ -157,16 +153,17 @@ A push refuses if a `config.ts` names a product the dashboard doesn't have.
|
|
|
157
153
|
|
|
158
154
|
```sh
|
|
159
155
|
superwall entitlements list --json # grab the NUMERIC entitlement id
|
|
160
|
-
superwall products create <identifier> \
|
|
161
|
-
--
|
|
156
|
+
superwall products create --identifier <identifier> \
|
|
157
|
+
--app <id|dashboard link> \
|
|
162
158
|
--name "Annual" --price 39.99 --period year \
|
|
163
159
|
--trial-days 7 --entitlement <numeric-id> --json
|
|
164
160
|
```
|
|
165
161
|
|
|
166
162
|
- `--entitlement` takes the **numeric id** (`55688`), not the identifier
|
|
167
163
|
(`pro`) — the identifier fails with a decode error.
|
|
168
|
-
- Pass `--project
|
|
169
|
-
with "
|
|
164
|
+
- Pass `--app <id|dashboard link>` (or `--project <id>`) when the account
|
|
165
|
+
has several projects, or it stops with "You can open N projects" and
|
|
166
|
+
lists them.
|
|
170
167
|
- `--price` is major units (39.99); `--period` is `day|week|month|year`;
|
|
171
168
|
`--trial-days` sets the intro offer. `--dry-run` confirms the target first.
|
|
172
169
|
|
|
@@ -178,13 +175,8 @@ Creating products writes to the user's real dashboard. Doing it is right
|
|
|
178
175
|
when they've asked you to push or to create them; name it in your summary
|
|
179
176
|
either way.
|
|
180
177
|
|
|
181
|
-
|
|
178
|
+
One more gate to check before promising a push will work:
|
|
182
179
|
|
|
183
|
-
- **Superwall for Agents is in private beta and must be enabled on each
|
|
184
|
-
app you push to** — otherwise the push stops with "Superwall for Agents
|
|
185
|
-
is in private beta and isn't enabled for this app yet." Nothing in the
|
|
186
|
-
CLI can set it; support@superwall.com turns it on. Check
|
|
187
|
-
`superwall apps list --json` → `features_enabled` for `headless_paywalls`.
|
|
188
180
|
- **One broken surface blocks the whole push.** A leftover scaffold aimed at
|
|
189
181
|
a nonexistent product stops everything — push what you built with repeated
|
|
190
182
|
`--id` flags instead of touching unrelated directories.
|
|
@@ -207,7 +199,8 @@ The hosted studio's chat runs this at the end of every turn for its preview.
|
|
|
207
199
|
Builds every paywall, versions the changed ones, and leaves production
|
|
208
200
|
alone. Re-running with nothing changed is a no-op. Flags: `--id <id>`
|
|
209
201
|
(limit, repeatable), `--platform <p>` (repeatable or comma-separated; limits the platforms),
|
|
210
|
-
`--rename <old>=<new>`, `-m <note
|
|
202
|
+
`--rename <old>=<new>`, `-m <note>`, `--overwrite-source` (below; `publish`
|
|
203
|
+
takes it too).
|
|
211
204
|
|
|
212
205
|
A push refuses — before anything is written — when:
|
|
213
206
|
|
|
@@ -221,6 +214,11 @@ A push refuses — before anything is written — when:
|
|
|
221
214
|
First push binds each paywall (creating it on Superwall if needed) and
|
|
222
215
|
records the binding in `superwall.lock`, per platform — commit it. After
|
|
223
216
|
that, push always updates the same paywalls; no IDs ever appear in your code.
|
|
217
|
+
An existing headless paywall with the same id that the lock doesn't bind is
|
|
218
|
+
never taken over on a name alone: interactively push asks, otherwise it
|
|
219
|
+
stops and prints the lock line to add if the paywall is this project's.
|
|
220
|
+
Never add that line without the user confirming the paywall is theirs;
|
|
221
|
+
renaming the directory creates a new one instead.
|
|
224
222
|
|
|
225
223
|
### Several platforms
|
|
226
224
|
|
|
@@ -236,10 +234,14 @@ under `apps`:
|
|
|
236
234
|
"plus-upgrade": { "ios": { "paywallId": "2001" }, "android": { "paywallId": "2002" } },
|
|
237
235
|
"web-upgrade": { "web": { "paywallId": "2003" } }
|
|
238
236
|
},
|
|
239
|
-
"funnels": {}
|
|
237
|
+
"funnels": {},
|
|
238
|
+
"sources": { "…": "<commit sha>" }
|
|
240
239
|
}
|
|
241
240
|
```
|
|
242
241
|
|
|
242
|
+
`sources` is the commit each app's source repo was last synced to (see
|
|
243
|
+
Source, below). Never edit it.
|
|
244
|
+
|
|
243
245
|
Each paywall says which platforms it ships to in `config.ts` — a typed
|
|
244
246
|
array of `ios | android | web`:
|
|
245
247
|
|
|
@@ -308,12 +310,36 @@ next promote.
|
|
|
308
310
|
|
|
309
311
|
### Source
|
|
310
312
|
|
|
311
|
-
Every push also
|
|
312
|
-
dashboard can show and diff the code each version was
|
|
313
|
-
`-m "why"` records the reason there.
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
313
|
+
Every push also saves the `superwall/` source to the app's source repo on
|
|
314
|
+
Superwall, so the dashboard can show and diff the code each version was
|
|
315
|
+
built from — and `-m "why"` records the reason there.
|
|
316
|
+
|
|
317
|
+
- **Teammates' work is kept.** The repo is shared by everyone who pushes to
|
|
318
|
+
the app. A push applies this project's changes on top of whatever others
|
|
319
|
+
published since its last push, from the commit `superwall.lock` records
|
|
320
|
+
under `sources` (commit the lock). It stops and names the files rather
|
|
321
|
+
than overwrite: `Someone else published changes to …` (the same files
|
|
322
|
+
changed on both sides: pull their commits, push again) or `The source
|
|
323
|
+
repo differs from this project in …` (no sync point recorded: pull the
|
|
324
|
+
latest `superwall.lock`). `--overwrite-source` replaces the remote
|
|
325
|
+
source with this project's. It discards a teammate's work, so it is the
|
|
326
|
+
user's decision, never a fix you reach for on your own.
|
|
327
|
+
- **No version ships without its source.** A version whose source didn't
|
|
328
|
+
land is recorded in `superwall.lock` (`sourcePending`); the next push
|
|
329
|
+
finishes its source before anything else, `promote` refuses it (`version
|
|
330
|
+
N has no source yet`), and `publish` finishes the source before
|
|
331
|
+
promoting.
|
|
332
|
+
- **What never leaves the machine:** `.env*`, `node_modules/`,
|
|
333
|
+
`.superwall/`, `.git/`, key and credential files (`*.p8`, `*.p12`,
|
|
334
|
+
`*.pem`, `*.key`, keystores, `.npmrc`, `.netrc`, `google-services.json`,
|
|
335
|
+
`GoogleService-Info.plist`), and gitignored files. A source tree over
|
|
336
|
+
250 MB stops the push before any version exists, naming the largest
|
|
337
|
+
files.
|
|
338
|
+
- **Git is required.** Without it nothing is created.
|
|
339
|
+
|
|
340
|
+
If any import reaches outside the project directory, the push warns and
|
|
341
|
+
the dashboard disables remote editing for that paywall (docs:
|
|
342
|
+
`project-structure`).
|
|
317
343
|
|
|
318
344
|
## `superwall promote`
|
|
319
345
|
|
|
@@ -368,13 +394,17 @@ than listing none.
|
|
|
368
394
|
| `…package.json is named "superwall"` | Rename the package — that name shadows the framework |
|
|
369
395
|
| `No superwall framework found` | `bun add superwall` (or npm) inside the project |
|
|
370
396
|
| `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` |
|
|
371
|
-
| `
|
|
372
|
-
| `
|
|
397
|
+
| `You can open N projects - pass --app <id\|dashboard link> or --project <id>` | Add `--app <id\|dashboard link>` to the resource command |
|
|
398
|
+
| `App <id> already has a paywall … that superwall.lock doesn't bind` | Ask the user whether it's this project's; if so add the printed line under `paywalls`, if not rename the directory |
|
|
373
399
|
| Diagnostics block the push | The message names each stray file and where it belongs |
|
|
374
400
|
| Rename ambiguity in CI | Add the printed `--rename old=new` |
|
|
375
401
|
| `x doesn't say which platforms it's for` | The project pushes to several platforms — add `platforms: [...]` to that `config.ts` |
|
|
376
|
-
| `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` |
|
|
402
|
+
| `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 --name <name> --platform web` |
|
|
377
403
|
| `This project has no app for "…"` | `--platform` takes a platform bound in `superwall.lock` (or that app's id); the message lists them |
|
|
378
404
|
| `paywall x has never been pushed` (promote) | Push first |
|
|
379
405
|
| `superwall publish requires git` | Install git — the source snapshot is part of every publish |
|
|
406
|
+
| `… version N has no source yet` (promote) | Run `superwall push` to finish that version's source, then promote |
|
|
407
|
+
| `Someone else published changes to …` | Pull their commits, push again; `--overwrite-source` only on the user's say-so |
|
|
408
|
+
| `The source repo differs from this project in …` | Pull the latest `superwall.lock`, push again; `--overwrite-source` only on the user's say-so |
|
|
409
|
+
| `The source in … is N MB, over the 250 MB limit` | Gitignore what doesn't belong in the source, push again |
|
|
380
410
|
| Not signed in | `superwall login`, or `SUPERWALL_API_KEY` in CI |
|
|
@@ -44,11 +44,12 @@ never arithmetic), and a designed unpriced state.
|
|
|
44
44
|
| --- | --- |
|
|
45
45
|
| `multi-page` | `router.push/back`, the route stack, chrome in `layout.tsx` that reads router state (`canGoBack()`, `depth + 1`) |
|
|
46
46
|
| `transitions` | All four built-ins plus a custom `zoom` — proof a transition is just CSS on two attributes |
|
|
47
|
-
| `onboarding-quiz` |
|
|
47
|
+
| `onboarding-quiz` | Every answer a typed user attribute (`useUserAttribute`), one `next` for the buttons and `entry`, so a branching quiz closed halfway resumes on its branch at the first unanswered question (`replayStack`, [onboarding-state.md](onboarding-state.md)) |
|
|
48
48
|
|
|
49
49
|
`onboarding-quiz`'s terminal route defends every read — a replayed route
|
|
50
|
-
never crashes on a missing answer. Its step labels
|
|
51
|
-
because a branching flow's depth is not its step
|
|
50
|
+
never crashes on a missing answer. Its step labels come from walking `next`
|
|
51
|
+
over the user's branch, because a branching flow's depth is not its step
|
|
52
|
+
number.
|
|
52
53
|
|
|
53
54
|
## Purchases
|
|
54
55
|
|
|
@@ -55,7 +55,9 @@ Six consequences, each the answer to a common bug:
|
|
|
55
55
|
and the home indicator and rests clear of them; nothing you render
|
|
56
56
|
sits under a bar at rest unless you put it there. The moment you add
|
|
57
57
|
`env()` or `--sw-inset-*` to a page or a layout, that edge is padded
|
|
58
|
-
twice.
|
|
58
|
+
twice. The insets are padding, never a black bar: `--sw-background`
|
|
59
|
+
still paints every edge of the screen, under the status bar and around
|
|
60
|
+
the camera, and only content is inset.
|
|
59
61
|
4. **Sticky honours the scroll container's padding.** `position: sticky;
|
|
60
62
|
bottom: 0` in a page sticks at the inset, above the home indicator,
|
|
61
63
|
while the content scrolls under it to the screen edge. `top: 0` sticks
|
|
@@ -162,6 +164,7 @@ the attributes the framework stamps on `<html>`:
|
|
|
162
164
|
| ios · none (home button) · fullscreen | 20 | 0 | 0 |
|
|
163
165
|
| ios · phone, cutout unknown · fullscreen | 59 | 34 | 0 |
|
|
164
166
|
| ios · island/notch · landscape | 0 | 21 | 59/44 both sides |
|
|
167
|
+
| ios · strip (iPhone Duo) · any | 0 | 0 | 0 — `env()` only, see below |
|
|
165
168
|
| ios · tablet · fullscreen | 24 | 20 | 0 |
|
|
166
169
|
| ios · phone · modal or drawer | 0 (sheet starts below the bar) | 34 (island/notch), 0 (home button) | 0 |
|
|
167
170
|
| ios · tablet · modal or drawer | 0 | 0 (the sheet floats) | 0 |
|
|
@@ -170,13 +173,32 @@ the attributes the framework stamps on `<html>`:
|
|
|
170
173
|
| any · popup | 0 | 0 | 0 (the SDK insets it) |
|
|
171
174
|
| web | 0 | 0 | 0 (the browser owns its chrome) |
|
|
172
175
|
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
176
|
+
A **simulator** reports its host architecture (`arm64`) as `deviceModel`,
|
|
177
|
+
not an `iPhone17,1`. SDKs that know it also report the simulated phone as
|
|
178
|
+
`device.simulatorModel`, and the framework reads that first everywhere it
|
|
179
|
+
needs the model (`data-sw-cutout`, `data-sw-idiom`, `useDevice().cutout`,
|
|
180
|
+
the checkout sheet), so the simulator lands on the phone's own row. An
|
|
181
|
+
older SDK sends no `simulatorModel`: the cutout can't be derived and the
|
|
182
|
+
"cutout unknown" row assumes a modern phone. That is why a paywall can look
|
|
183
|
+
right in the studio, which sets the attributes from the preset, and sit
|
|
184
|
+
under the island in the simulator — if you see that, check
|
|
185
|
+
`document.documentElement.dataset.swCutout` first. Branching on the model
|
|
186
|
+
yourself: `device.simulatorModel || device.deviceModel`.
|
|
187
|
+
|
|
188
|
+
**iPhone Duo** (`iPhone19,4`) is `data-sw-cutout="strip"`, and
|
|
189
|
+
`useDevice().cutout` is `"strip"`. Its camera strip sits on the right when
|
|
190
|
+
the phone is closed or in landscape and on top when it is open in portrait,
|
|
191
|
+
and a host app built with an older iOS SDK runs beside the strip rather
|
|
192
|
+
than under it, so no floor is right: only `env()` knows the inset. Nothing
|
|
193
|
+
changes for you: lay out with `--sw-safe-area-inset-*` and the defaults,
|
|
194
|
+
and the paywall follows the strip. Use `cutout` only for a design choice
|
|
195
|
+
the insets can't make.
|
|
196
|
+
|
|
197
|
+
**Insets the host reports.** A host can send the safe area itself as
|
|
198
|
+
`device.safeAreaInsets` (`{ top, right, bottom, left }`); the framework
|
|
199
|
+
writes those as the `--sw-safe-area-floor-*`, so they stand in where
|
|
200
|
+
`env()` reads 0. The studio's iPhone Duo (Closed) and (Open) presets do
|
|
201
|
+
this with the insets measured in Apple's Duo simulator.
|
|
180
202
|
|
|
181
203
|
`push` and `noAnimation` are fullscreen. The attributes come from the
|
|
182
204
|
device the host reports and are absent, never guessed, until the host's
|
|
@@ -65,7 +65,7 @@ is whichever slot the selection state points at.
|
|
|
65
65
|
| `navigate-page` (`next` / `back`) | `useRouter().push("<next route>")` / `router.back()` |
|
|
66
66
|
| `set-product-index` | set your selection state |
|
|
67
67
|
| `set-state` | set the matching React state |
|
|
68
|
-
| `set-attribute` | `useActions().setUserAttributes
|
|
68
|
+
| `set-attribute` | the setter of `useUserAttribute(key, parser)`, one hook per attribute (`useActions().setUserAttributes` is deprecated) |
|
|
69
69
|
| `custom-placement` | `useActions().customPlacement(name, params)` |
|
|
70
70
|
| `custom-in-app` | `useActions().requestCallback(...)` (docs: `actions`) |
|
|
71
71
|
| `request-permission` | `useActions().requestPermission(type)`; `onGranted`/`onDenied` become the resolved status |
|