docs(web): add the Web SDK section - #263
Merged
Merged
Conversation
New Web SDK docs covering install, configure, placements, identity, feature gating, subscription state, the React provider and hooks, server-side entitlement gating, purchases, and events. Registers the section in the SDKs nav after Unity. Written against Superwall-Web HEAD (0.2.4). npm is still at 0.2.1, so this documents unreleased behavior by design and should not merge until the packages are published. Every page carries a beta warning per the standup ask. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Lets the preview tooling start `bun run dev` on port 3000 without a manual setup step. Dev-only; no effect on the built site. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three clean-context reviewers audited all 13 pages against Superwall-Web
0.2.4; every finding was independently re-verified before applying.
Corrections of note:
- feature() also runs on skipped placements (placementNotFound,
noAudienceMatch, holdout), so a typo'd placement name grants the feature.
The page implied the opposite.
- Entitlement's field is `id`, not `identifier`. @superwall/verify defines a
separate type of the same name that does use `identifier`; the two were
conflated in four places.
- userHas takes (userId, spec). The reversed form typechecks and denies
every entitled user.
- verifyEntitlements throws by design; the sample now catches VerifyError.
- useCustomPaywall returns { register, paywall }; SuperwallCustomPaywall
does not exist. Replaced with SuperwallPaywall, which does.
- onCustomPaywallAction takes a bare string and is never invoked by the SDK;
custom actions arrive as the custom_placement event.
- register does not await configuration — await sw.ready first. A failed
config fetch resolves ready and only shows in configurationStatus.
- preloadAll/preloadFor, customerInfo, refreshCustomerInfo, and
entitlements.inactive/all are unimplemented in the beta and now say so.
Also documents the userId extractor as the trust boundary, allowAnonymous,
the 60s cache TTL, and register's overrides/paywall/presenter arguments.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Ian shipped fixes for most of what the audit surfaced, so several of the beta caveats added in the last commit are no longer true. Re-verified against Superwall-Web 0.2.5 (edaf79a), which is now published to npm. Now working, caveats removed: - customerInfo / getCustomerInfo / refreshCustomerInfo are implemented - entitlements.inactive and .all are populated for real - onCustomPaywallAction is wired to the legacy custom action Still true, kept: - register does not await configuration; the README was corrected to match the code rather than the other way around - the entitlements token refreshes on a ten-minute poll Changed: - preloadAll / preloadFor are being removed from the API, not implemented - @superwall/verify's helpers now check per-entitlement expiresAt, so the gating guide recommends them over iterating the array Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
0.2.5 did not only fix bugs, it added public API the pages did not cover. - identify() now honors IdentityOptions. Documents restorePaywallAssignments, which re-runs experiment assignment for the identified user so they do not get a paywall chosen from their anonymous identity's stale assignments. - Adds the new customPaywallAction event to the event table. - browser/auto is implemented now (it was an empty module); documents it as the opt-in for bundlers that cannot ship dynamic chunks. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
superwall-docs | 158f061 | Commit Preview URL Branch Preview URL |
Aug 14 2026, 07:19 PM |
Uses the pixel-grid Globe icon. Web SDK was the only section rendering without a mark in the top nav. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Adds the share blurb to the Chats section with a screenshot of the share control. Image resized to 2000px wide per repo convention. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Salvages the two pieces of the parked SW-5608 branch that the merged discount-codes page (#254) did not cover: the Redeem Discount vs Redeem Purchase note, and a pointer to the Web SDK's programmatic redeemDiscount(). The rest of that branch is superseded — its WEBAPP-only claims predate the STRIPE gate fix. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…shots SVG placeholders carrying the final filenames, placed at the steps the real captures belong to. Swapped for JPEGs when the screenshots arrive; the SVGs are deleted at that point per the docs workflow. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Style pass over the Web SDK section and the discount-codes page. Every em dash replaced with a period, comma, or colon. Rhetorical framing cut in favor of plain statements of behavior. No factual content changed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…wall The Web SDK runs against the Web App application type. The dashboard's add-app Web option creates a STRIPE (Web Checkout) application instead (createApplicationInTx.ts maps web to STRIPE), and the public API marks the webapp platform "read-only - cannot be created via API". The install page now says to ask Superwall for one during the beta, instead of pointing readers at a dashboard flow that hands them the wrong key. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…k-docs # Conflicts: # content/docs/web-checkout/web-checkout-discount-codes.mdx
Renames the remaining Redeem Discount references the merge did not cover: the purchases guide note, both placeholder SVGs, and the frame alt text. Also drops the stale dev-environment capture caveat from the placeholders, since the editor action reached production on 2026-08-13. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…reenshot The old steps told readers to bind the input to a state variable. No such step exists in the editor: an Input's value is exposed automatically under Element in the variable picker, and the Apply Discount action's code field has a picker button that inserts the reference. The steps now describe that flow: add an input, add a button, give it Apply Discount, pick the input. One screenshot now covers the whole setup (paywall, action, picker open on Element), replacing both placeholder SVGs. Converted to JPEG at 2000px. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds documentation for the Superwall Web SDK, written against 0.2.5, the version on npm. Closes SW-5720.
Requested by Jake in the 2026-08-10 roadmap call, alongside KMP and MMP docs: "nothing gets launched till it's documented, even the beta." Every page carries a beta warning.
The Web SDK section
13 new pages under
content/docs/web/, registered in the SDKs nav after Unity with a Globe icon:Notes for reviewers:
@superwall/verify's own source says the gate "MUST run on the server." The index and Feature gating pages both warn toward that guide.webappplatform read-only). During the beta, Superwall provisions them. Verified in paywall-next.Also on this branch
Verification
Three clean-context reviewers audited every falsifiable claim against SDK source, split by area, with each finding independently re-verified before applying. That caught ~24 defects in the first draft, including:
feature()also runs on skipped placements (placementNotFound,noAudienceMatch,holdout). A typo'd placement name grants the feature. The draft implied the opposite.userHas(userId, spec): the reversed form typechecks and denies every entitled user.verifyEntitlementsthrows by design: the original sample had notry/catch, so a forged token crashed the route instead of returning 402.Entitlementis two different types:@superwall/coreusesid,@superwall/verifyusesidentifier. The draft conflated them in four places.registerdoes not await configuration: it throwsPaywallNotAvailableError("no_config"). The SDK README claimed otherwise and was corrected to match the code.Findings went to @ianrumac, who fixed most of them in 0.2.5. The docs were then re-verified against 0.2.5 and the obsolete caveats removed. Still true and documented as such:
preloadAll/preloadFordo nothing and are being removed from the API.bun run build:cf(614 pages prerendered, no broken links) andbun test(64 pass, 0 fail) both green.🤖 Generated with Claude Code