Skip to main content
A preview runs your local dev server on the Wonder canvas. When the app inside it sends you to sign in, Wonder does not let the preview leave localhost: it opens the sign-in in its own window, and hands you back into the preview signed in. Most apps need nothing for this to work. Some need one setting, and Wonder names it on the card. A few cannot finish inside a preview at all, and this page says which and what to do instead.

​
How it works

  1. Your app starts sign-in — a redirect, or a popup it opens itself.
  2. Wonder cancels the hop and opens the same address in a Wonder sign-in window. The window shows the site you are signing in to at the top, so you can always see where your password is going.
  3. You sign in there.
  4. Wonder hands the result back into the preview, which carries on signed in. When the result cannot be handed back — some flows finish in the window itself — the preview reloads to pick up the session instead. Either way, the address saved on the canvas never records anything from the sign-in.

​
”This app needs one setting to sign in here”

Wonder shows this card when it can name the one thing your app is missing. It never changes anything in your project — you make the change, then sign in again.

​
Add the callback URL

If the card names an address like http://localhost:3000/api/auth/callback, your identity provider refused it. Add that exact address to your app’s allowed callback URLs — the same entry you would add to run the app locally outside Wonder.
Copy it exactly
localhost and 127.0.0.1 are different entries at every identity provider, so add the spelling the card shows rather than the one you usually type.

​
Change one SDK setting

Two SDKs block their own redirect sign-in inside any embedded page. Both have a development-only option, and neither changes anything in production:

​
What cannot sign in inside a preview

For these, open the preview in your browser from the title bar and sign in there. Your app is unchanged either way.
  • Passkeys and Touch ID. The Wonder desktop app has no platform authenticator, so a login that requires a passkey cannot complete. Use a password or another factor, or sign in in your browser.
  • A login page your app shows in its own iframe. Hosted login pages — Auth0, Okta, Google, WorkOS and the rest — refuse to be displayed inside another page, and that refusal is enforced by the provider, not something you can switch off. Nothing appears and no card explains it, because that iframe belongs to your app rather than to Wonder. Start sign-in with a redirect or a popup instead.
  • Previews in a browser tab. Signing in from a preview needs the Wonder desktop app, which is where the sign-in window lives.
  • Sign-in that finishes with a form POST or SAML. Wonder cannot read a response that arrives in a POST body, so the sign-in completes in the Wonder window and your preview reloads to pick up the session. Anything the page had not saved is lost in that reload.
  • IdP-initiated SAML. A sign-in that starts at your identity provider, rather than in your app, has nothing for the preview to pick up. Start it from the app.
  • Sign-in links that open a plain new tab. A target="_blank" link is browsing, so Wonder opens it in your browser and the session stays there. Open sign-in with a popup (or your SDK’s popup method) to keep it in Wonder.
  • Dev servers on anything but localhost. A preview only accepts localhost, 127.0.0.1 and [::1]. A LAN address, a .local name, a custom hosts-file alias, or 0.0.0.0 cannot be previewed at all — so there is no sign-in to hand back. Your server can still bind to 0.0.0.0; point the preview at localhost.
  • A callback that returns to a different port. Wonder hands the result back to the app that asked for it. If your redirect_uri points at another local server — an auth service on its own port, say — that app gets the session and the preview does not.
  • A sign-in that lands back on an /auth or /login route. When a flow finishes in the Wonder window, Wonder refreshes the preview once the window reaches a page outside your sign-in routes. If your app’s post-login destination is itself under /auth or /login, that refresh does not happen — reload the preview from the title bar and the session is there.
  • Published previews. A published preview is a shared link, not your local session, so sign-in stays outside it by design.

​
If the sign-in did not take

You signed in, the window closed, and the preview is still signed out — usually with a card saying the sign-in didn’t finish. Two common causes, both fixed by signing in again:
  • The preview reloaded while you were signing in. Wonder hands the result back to the exact page that asked for it, so saving a file and letting hot reload swap the page out loses the hand-off. Finish the sign-in before you edit.
  • It took longer than ten minutes. A sign-in step is held for ten minutes — long enough for MFA, not for stepping away mid-flow.

​
Two worktrees, one login

Browsers scope cookies to the hostname, not the port, so every worktree’s dev server shares one localhost jar. If your app keeps its session in a cookie, signing into a preview of one worktree signs you into previews of the others — and signing out signs you out everywhere. If it keeps its token in local storage instead, the opposite holds: each port is its own origin, so every worktree signs in separately. Either way, only the preview you signed in from refreshes itself. A preview of another worktree keeps showing its signed-out page until you reload it from the title bar.

​
Still stuck?

Every card offers Open in browser, which carries the exact step Wonder stopped over to your browser so you can finish it there and see what the provider says.