Install the SDK

Beta

The Web SDK is in beta and its API may change between releases.

Install

Install the headless core. Add the React package too if you are using React.

bun add @superwall/paywalls-js

# React apps
bun add @superwall/paywalls-react react

npm install @superwall/paywalls-js

# React apps
npm install @superwall/paywalls-react react

pnpm add @superwall/paywalls-js

# React apps
pnpm add @superwall/paywalls-react react

@superwall/paywalls-react re-exports everything public from @superwall/paywalls-js, so React apps can import from the React package alone and skip the second dependency if they prefer.

Requirements

ESM only. The packages ship as ES modules with an exports map. There is no CommonJS build.
React 19 for @superwall/paywalls-react, declared as a peer dependency.
A modern browser for the default presenter, which mounts the paywall in an iframe.

Server and edge runtimes

@superwall/paywalls-js holds no DOM references at module load, so it imports cleanly in Node, Bun, edge functions, workers, and during SSR. The browser-only pieces live behind a subpath:

import { createSuperwall } from "@superwall/paywalls-js";           // anywhere
import { createBrowserStorage } from "@superwall/paywalls-js/browser"; // browser-intended

The /browser subpath imports cleanly on the server. Nothing on it touches the DOM at module load, and its factories degrade gracefully. Only mounting a paywall needs a real DOM.

The SDK lazy-loads the presenter on first register(). If your bundler cannot ship dynamic chunks, or you want to avoid the chunk-load cost on the first presentation, import @superwall/paywalls-js/browser/auto once for its side effect to pull the presenter in up front.

Set up your Web app

The Web SDK uses the same Web platform app as Web Checkout, which older pages call a Stripe app. One app serves both your web checkout links and the paywalls you show on your own site. If your project already has a Web app for web checkout, use it. Otherwise, create one and connect Stripe.

During the beta, Superwall created separate applications for the Web SDK, labeled Web app in the dashboard. New ones can no longer be created. Use your project's Web app instead.

Copy the public API key

In the new dashboard, open your Web app's Settings and go to API keys. Copy the Public API key, a pk_… value. It is a publishable key and safe to ship in client code. Use the Web app's key, not the key from your iOS or Android app. The legacy dashboard does not show keys for Web apps.

Add your site's origins

Under Settings > General, add each origin that will show paywalls to Allowed origins. This is required. Checkout requests from any origin not on the list are rejected, so with no origins listed, every checkout fails.

Enter scheme, host, and port, exactly as window.location.origin reports it, with no path. For example, https://example.com. Add your local development origin too, such as http://localhost:5173.

Add an in-app placement

Paywalls reach the Web SDK through placements in a campaign. In a Web app's campaign, Add placement asks how the placement reaches users:

Option	What it does
Link	Served as a page on your Superwall domain. This is a web checkout link.
In-app placement	Triggered by an event from the Web SDK on your site.

Choose In-app placement and enter an In-app event name, such as checkout. That name is what you pass to register({ placement }).

Next, configure the SDK.