Skip to content

Add an emulator playground to the website and a combined example app - #412

Open
lahfir wants to merge 7 commits into
mainfrom
laf/playground
Open

lahfir wants to merge 7 commits into
mainfrom
laf/playground

Conversation

@lahfir

@lahfir lahfir commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor
  1. There was nowhere to try an emulator without installing it, and a file uploaded to an embedded emulator could run script in the host app's origin.
  2. The website gets a /playground with five guided flows and a request console per emulator, all running in the visitor's browser, examples/playground combines the server-side flows in one app, and emulators now serve uploaded files sandboxed.
  3. No related issues.

Demo

Everything runs in the tab: an OAuth sign-in, a Stripe checkout through to a paid order, then a GitHub console request.

demo.mp4

Preview

Page Before After
/playground new page preview
/playground/flows/oauth-sign-in new page preview
/playground/github new page preview
Playground (Light, 1440) Flow (Light, 1440)
Playground, light Flow, light
Playground (Dark, 1440) Flow (Dark, 1440)
Playground, dark Flow, dark

examples/playground is one Next.js app that serves every emulator under
/emulate/<name> and lets you switch between playgrounds from a sidebar.

- Flows ported from the existing examples, each under its own path with
  its own cookies: OAuth sign-in, Resend magic link, Stripe checkout,
  Twilio SMS verification, and Vercel Blob sharing.
- OAuth sign-in also covers Vercel, Microsoft, Okta, Clerk, and Apple.
- AWS, Linear, MongoDB Atlas, and Slack have no example flow, so each
  gets a request console with presets at /services/<name>.

The existing examples are unchanged.
Each emulator now has a console at /services/<name> with a catalog of
ready-made requests: 746 across the 14 emulators, grouped by area, with
the method, path, headers, and body filled in.

- Values that only exist at runtime (a token, an id) are {{name}}
  placeholders. The console asks for each one once and fills it in when
  an earlier request returns it.
- Signing in at /oauth fills in the access token for that provider.
- The seeds gain a few fixed resources the requests rely on.
- The sidebar gets its links from the layout, so the catalogs stay out
  of the browser bundle on pages that do not use them.

Checked by sending every request in catalog order against a fresh
server: all succeed except the ones that need a value only a browser
sign-in can produce.
A button beside the sidebar title switches between light and dark. The
choice is remembered, and the first visit follows the system setting.
The store section gets dark colors of its own.

The request console now scrolls to the response when it arrives, since
the form can push it below the fold.
@vercel

vercel Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
emulate Ready Ready Preview, v0 Nov 16, 2026 8:29pm UTC

@vercel-internal-security-reviewer

Copy link
Copy Markdown

Security review details

</div>

<form action="/oauth/api/auth/signout" method="post">
<Button variant="destructive" className="w-full">

@vercel vercel Bot Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The OAuth dashboard's Sign Out control still renders as type="button", so clicking it never submits the sign-out form and leaves the session active.

Fix on Vercel

An embedded emulator shares its host app's origin, so an HTML file
uploaded to Vercel Blob could be opened at its raw URL and run script
there. S3 objects, Drive downloads, and Slack files had the same gap.

Those four routes now send files through one core helper, `c.file`. It
always sets `X-Content-Type-Options: nosniff`, and adds
`Content-Security-Policy: sandbox` for types a browser renders as a page
(HTML, SVG, XML, or no type). Images and PDFs still display.

Tested in core and against the Blob emulator, and checked in a browser:
the uploaded script does not run.
The website gets a /playground section with a console per emulator. The
emulators run in the visitor's browser tab: nothing is sent to a server,
every visitor has a private copy, and a reload starts fresh.

- apps/web/lib/emulator-browser holds browser stand-ins for the Node
  built-ins the emulators import, built on @noble/hashes and buffer and
  tested against Node's own crypto and Buffer.
- The catalogs move from the example app to apps/web/lib/playground.
  Each OAuth emulator gains an "Approve sign-in" request that stands in
  for the consent page, so the code exchange runs with nothing typed.
- Twelve AWS requests are gone: KMS encrypt and decrypt and the Cognito
  token chain need ciphers and RSA keys the stand-ins do not provide.
- examples/playground keeps the five flows and drops the consoles and
  the four emulators only they used.

Checked by driving the console page in a browser through every request:
736 of 741 succeed with nothing typed, none fail, and five need one
value typed in.
@socket-security

socket-security Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Addednpm/​@​noble/​hashes@​2.4.010010010082100

View full report

@lahfir lahfir changed the title Add a playground example that combines the emulators Add an emulator playground to the website and a combined example app Nov 16, 2026
The playground pages get a sidebar that lists every emulator and marks
the current one, so a visitor can switch without going back to the
index. It sits under the site navbar and scrolls on its own.
The playground on the website now has the flows the example app has,
rebuilt to run in the visitor's tab against the in-tab emulators: OAuth
sign-in (seven providers), Resend magic link, Stripe checkout, Twilio
SMS verification, and Vercel Blob sharing. They sit in a Flows group in
the playground sidebar and on its index.

A flow and its console share one emulator per tab, so an email sent by
the magic-link flow shows up in the Resend console.

The flows call the emulator's API directly. The versions that go through
the real SDKs in server code stay in examples/playground.

Each flow was run end to end in a browser.

This branch was successfully deployed

1 active deployment
Preview — ef8ae5b5 Deployed Nov 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant