Install the SDK
Add the Superwall Web SDK to your browser or React app.
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 reactnpm install @superwall/paywalls-js
# React apps
npm install @superwall/paywalls-react reactpnpm 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
exportsmap. 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-intendedThe /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.
Get an app and API key
Web SDK paywalls belong to a Web App application in the Superwall dashboard. This is a separate application type from iOS, Android, and Web Checkout.
Web App applications cannot yet be created from the dashboard or the API. During the beta, Superwall creates one for you. Ask your Superwall contact.
Once you have the app, copy its public API key, a pk_… value, from the dashboard. It is a publishable key and safe to ship in client code. Use the Web App application's key, not the key from an iOS, Android, or Web Checkout app.
Next, configure the SDK.
How is this guide?