Guides

Local Development

Set up the Superbridge Widget for local development

In production the widget resolves your Rollie from the domain it loads into. On localhost there is no domain to resolve, so you pass a key instead.

import { Widget } from "@superbridge/widget";

<Widget localDevelopmentApiKey={import.meta.env.VITE_WIDGET_DEV_KEY} />

You can find your local development API key in the Rollie dashboard.

The localDevelopmentApiKey is intended for local development only. Do not expose it in production builds. Make sure it is excluded from your production bundle — for example, by loading it from an environment variable that is only set in development.

In production, the widget picks up your Rollie configuration from the domain it loads into, so no API key is required.

Getting to a first render

Four things, in the order they bite:

The stylesheet. @superbridge/widget/styles.css, linked before your own — see Embedding. Skip it and the widget renders as unstyled markup.
The key. Without localDevelopmentApiKey on localhost the widget has no Rollie, so no chains and no tokens.
A browser. The widget reads browser APIs during setup; if your framework server-renders by default, gate it — see Integration for your framework's way of doing that.
Room. Give it a container at least 440px wide, or its modals will clip. See Embedding.

When it looks wrong

What you see	Cause
Widget renders as plain unstyled markup	The stylesheet isn't linked, or your `portalTarget` is missing the class — see Embedding
Empty token pickers, no routes	No `localDevelopmentApiKey` on `localhost`, or the key doesn't match the Rollie you expect
Hydration errors or a blank widget on first paint	Rendered on the server; wrap it in your framework's client-only gate
Modals open inside the widget, not over the page	That's the default. Pass a `portalTarget` for full-screen overlays
Modals clipped or squeezed	The container is narrower than a 440px modal, or its height changes as the form grows
Your fonts or colors change outside the widget	Your stylesheet is linked before the widget's, so the widget's theme variables win at `:root`. Swap the order
Wallet connects in your app but the widget stays disconnected	The widget found no host provider, or found it too late — see Wallets