Falaah Falaah AI
Platform

How We Built Real-Time Embeddable Widgets with SSE, Shadow DOM, and Zero Dependencies

Technical deep dive into Muin's embed architecture: Shadow DOM for style isolation, SSE for real-time updates, CORS for cross-origin embedding, and a sub-25KB widget loader.

FT
Falaah Team
· · 5 min read
How We Built Real-Time Embeddable Widgets with SSE, Shadow DOM, and Zero Dependencies

When we set out to build Muin’s embeddable widgets (donation forms, event registrations, payment pages, campaign thermometers), we had constraints that ruled out most off-the-shelf approaches.

The widgets had to render correctly on any website regardless of the host site’s CSS framework. They had to update in real time. They had to work cross-origin without requiring the host site to configure anything beyond pasting a <script> tag. They had to be small enough that embedding one would not degrade performance. And they had to be idempotent: a flaky network connection or a double-click must not result in a duplicate charge.

The Widget Loader: Under 25KB

Every Muin embed starts with a single script tag:

<script src="https://muin.falaah.ai/embed/widget.js" data-tenant="your-org" data-type="button"></script>

The widget.js loader is under 25KB minified and gzipped. It is vanilla JavaScript with zero runtime dependencies: no React, no Vue, no jQuery. It performs three tasks:

  1. Parses data-* attributes on the script tag to determine which widget to render and what configuration to apply.
  2. Creates a container at the script tag’s location in the DOM.
  3. Renders the widget, either directly inside a Shadow DOM root or as an auto-sized iframe of our hosted page.

The widget types are controlled by the data-type attribute: button, form, thermometer, popup, floating, banner, zakat, event, impact, and support.

Shadow DOM for Light Widgets, Iframes for Rich Ones

The classic approach to embedding third-party content is an iframe. Iframes provide complete isolation, but a fixed-height iframe creates scrolling-inside-scrolling on mobile and looks foreign on the host page.

We use both, each where it fits. Lightweight widgets (button, popup, floating button, banner) render inside a Shadow DOM root attached to a host <div>:

CSS isolation. The host site’s styles do not leak into the widget, and the widget’s styles do not leak out. A site using Tailwind with aggressive resets will not flatten the widget’s form layout.

DOM isolation. The widget’s elements are not queryable from the host site’s JavaScript via document.querySelector. This prevents accidental collisions.

Part of the page. The widget resizes naturally with its content, participates in the host page’s scroll, and screen readers traverse it as part of the document.

Rich widgets (donation form, thermometer, Zakat calculator, event signup, support) load our hosted page in an iframe that resizes itself to its content, so there is no inner scroll bar. The iframe boundary is its own style isolation.

For payment fields, we use Stripe Elements, which renders sensitive input inside Stripe’s own iframe, so card numbers never touch our code or the host page’s DOM.

Server-Sent Events: Real-Time Without WebSockets

Campaign thermometers need to update in real time. When someone donates on the standalone giving page, the thermometer widget embedded on a completely different website must tick upward within seconds.

We chose SSE over WebSockets because our use case is unidirectional: the server sends updates to the client. SSE is HTTP-based (works through any proxy), automatically reconnects on disconnection, and is natively supported by every modern browser via the EventSource API.

The thermometer page inside the embed opens an SSE connection to /api/v1/embed/campaigns/{id}/events. The server holds the connection open and pushes an event when the campaign total changes, and the thermometer updates its progress bar and total with no page refresh and no polling.

Redis Pub/Sub: Broadcasting Across Instances

The API runs multiple server instances behind a load balancer. When a donation is processed on instance A, the SSE connections held by instances B, C, and D also need to push updates.

We use Redis pub/sub for this broadcast. A donation triggers a message on the campaign’s Redis channel. Every API instance subscribed to that channel pushes the update to its connected SSE clients. If a connection drops, EventSource reconnects with its Last-Event-ID and the server replays the events it missed.

CORS: Cross-Origin Embedding Without Configuration

The widget script is served from https://muin.falaah.ai, and it derives its API base from its own <script src>, so its calls go back to that same origin, which routes /api/* to the API service and /go/* to the hosted donor pages. The host site is on a second domain. This cross-origin setup requires careful CORS configuration.

  • The widget loader (muin.falaah.ai/embed/widget.js) is served with Access-Control-Allow-Origin: * because it is a static, public script.
  • The public embed endpoints (widget config, embed pages, campaign events) also send Access-Control-Allow-Origin: *. They return only public data, so any site can call them.
  • Embed pages include frame-ancestors * in their CSP header so they can be framed on any site.

The critical design decision: the host site pastes one script tag and configures nothing else. No CORS headers to set on their side. No proxy to configure.

Idempotency: Preventing Duplicate Charges

Every charge is sent to Stripe with an idempotency key derived from the payment itself: the surface it came from and the request that defines “the same payment”. A retry or a double-click produces the same key, so Stripe returns the first charge instead of creating a second one.

Performance

The loader is a single script under 25KB gzipped. It does not load external CSS frameworks, icon libraries, or font files.

Resilience

Dropped connections. If the SSE connection drops, EventSource reconnects on its own and the server replays the events it missed, so the thermometer catches up.

Payment failure. Stripe errors are displayed in plain language with the option to retry. The idempotency key ensures a retry is safe.

The Result

A single <script> tag. Under 25KB. Works on any website. Real-time updates via SSE. Style isolation via Shadow DOM or a self-sizing iframe. No duplicate charges. No configuration required from the host site.

The same infrastructure powers all 26 embedding combinations described in 26 Ways to Accept Payments, Donations, and Registrations with Muin. For practical setup instructions rather than the architecture, see the embedding documentation.