Configure

Create an instance

In React, wrap your app in SuperwallProvider once. In plain JavaScript, call createSuperwall. Both return an instance synchronously and start configuring in the background.

import { SuperwallProvider } from "@superwall/paywalls-react";

export function Root() {
  return (
    <SuperwallProvider apiKey="pk_…">
      <App />
    </SuperwallProvider>
  );
}

import { createSuperwall } from "@superwall/paywalls-js";

const sw = createSuperwall({ apiKey: "pk_…" });

Do this once, as early as your app boots. In React the provider holds the instance for you; reach it from any component with useSuperwall(). In plain JavaScript, keep the returned instance around, or use the named exports and let the SDK hold it for you.

Wait for ready before presenting

register waits for identity to hydrate, but it does not wait for configuration. Called before config lands, it returns { type: "error" } carrying a PaywallNotAvailableError.

import { use } from "react";
import { useSuperwall, usePlacement } from "@superwall/paywalls-react";

function Checkout() {
  const sw = useSuperwall();
  use(sw.ready); // suspends until configured

  const { register } = usePlacement();
  return <button onClick={() => register({ placement: "checkout" })}>Upgrade</button>;
}

const sw = createSuperwall({ apiKey: "pk_…" });

await sw.ready;

const result = await sw.register({ placement: "checkout" });

In React, use(sw.ready) suspends the component, so put a <Suspense> boundary above it. Gating render on configuration covers the boundary and its error handling.

Reads never block. sw.user.id.value and sw.subscriptionStatus.value return synchronously at any time. Before hydration lands they return defaults ("" and { status: "UNKNOWN" }). Persisted state replaces the defaults shortly after.

import { useSuperwall, useSignal } from "@superwall/paywalls-react";

function ConfigGuard({ children }: { children: React.ReactNode }) {
  const sw = useSuperwall();
  const status = useSignal(sw.configurationStatus);

  if (status === "failed") {
    // Superwall could not configure. Paywalls will not present.
    return null;
  }
  return children;
}

await sw.ready;

if (sw.configurationStatus.value === "failed") {
  // Superwall could not configure. Paywalls will not present.
}

Options

SuperwallProvider accepts every option createSuperwall does, as props. The two are the same configuration surface.

<SuperwallProvider
  apiKey="pk_…"
  options={{
    /* SuperwallOptions: logging, networking, paywall behavior */
  }}
  delegate={myDelegate}
  storage={myStorageAdapter}
  purchaseController={myPurchaseController}
  identity={{
    appUserId: "user_123",
    aliasId: "$SuperwallAlias:…",
    vendorId: "…",
    vendorIdProvider: async () => "…",
  }}
>
  <App />
</SuperwallProvider>

const sw = createSuperwall({
  apiKey: "pk_…",
  options: {
    /* SuperwallOptions: logging, networking, paywall behavior */
  },
  delegate: myDelegate,
  storage: myStorageAdapter,
  purchaseController: myPurchaseController,
  identity: {
    appUserId: "user_123",
    aliasId: "$SuperwallAlias:…",
    vendorId: "…",
    vendorIdProvider: async () => "…",
  },
});

Named exports

Instead of threading the instance through your app, import the namespaces directly. The first createSuperwall call registers the default instance, and these bind to it.

import { createSuperwall, user, register, events } from "@superwall/paywalls-js";

createSuperwall({ apiKey: "pk_…" });

await user.identify("user_42");
const result = await register({ placement: "checkout" });

Importing only user lets bundlers drop the rest as dead code.

React apps do not need this. SuperwallProvider already holds the instance, and the hooks reach it through context.

Multiple instances

Creating more than one instance is supported. Useful for tests, Storybook, and multi-tenant edge workers. The default instance is the first one created in the process, and it is the one the named exports target.

Next, present your first paywall.