Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

`BrowserWidget` module for `@effect/platform-browser`

Chiusa
  • Qualcosa non va?
#8,458 2 commenti 1 reazione 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
38/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
typescript
Ambito
frontend

Direzione di ricerca

No implementation files or tests are identified in the issue. Start by reviewing the proposed BrowserWidget, Launcher, EmbedLauncher, PopupLauncher, and Self APIs in @effect/platform-browser, then determine the package entry points and testing approach. Done means the typed widget lifecycle, embed and popup launchers, message validation, teardown, and widget-side completion signaling are implemented.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

enhancement

Proposal: BrowserWidget module for @effect/platform-browser

Summary

A small, typed abstraction for launching a cross-origin UI ("widget") in an
iframe or popup and consuming what it sends back as a Stream. The widget is
described via schemas (payload in, items out, error out); a
Launcher service decides how the widget is mounted (embedded iframe vs.
popup window); calling launch returns a Stream whose lifecycle is the
widget's lifecycle.

Motivation

Any browser app that hosts a third-party or cross-origin UI ends up
hand-rolling the same things:

  • build a URL with the initial state encoded in the query string
  • create an iframe / open a popup, size it, set sandbox / allow
  • subscribe to window message events, filter by source, validate data
  • know when the child is finished, tear the element down
  • surface all of this to the caller as something they can await / compose

Every one of those steps has a natural Effect answer already, but nothing
ties them together. The result is that this logic lives as ad-hoc glue in
app code and is hard to test or swap (e.g. embed in prod, popup in dev,
a no-op launcher in tests).

Core ideas

1. Define the widget schemas
import { Schema as S } from "effect"
import { BrowserWidget } from "@effect/platform-browser"

export const LinkWidget = BrowserWidget.make({
  pathname: "link",
  payload: S.Struct({ challengeId: LinkChallengeId, allowance: Allowance }),
  item: S.Void,     // messages the widget posts back to the host
  error: S.Never,   // typed failure the widget can report
})
  • payload is encoded into URL search params (S.toCodecStringTree →
    S.fromURLSearchParams → UrlParams), so the widget page can decode its
    initial state with the same schema on the other side.
  • item is the schema of each message the widget posts back to the host.
  • error is the typed error channel. The stream's error type is
    LaunchError | UrlError | SchemaError | E.
  • The widget also implements Standard Schema for its payload, so it can be
    handed directly to form libraries / validators.
2. Launching a widget is running a stream
// Host side
yield* BrowserWidget.launch(LinkWidget, { challengeId, allowance }).pipe(
  Stream.runDrain,
)

There's no separate "open" / "close" / "subscribe" API. launch returns a
Stream<A, E, R>:

  • Running the stream launches the widget. Nothing is mounted until the
    stream is consumed.
  • Each element is a validated message from the widget (S.is(item)),
    filtered by event.source so you never see messages from other frames.
  • The stream ends when the widget signals done (a well-known
    postMessage sent by the widget's Self.postFinished()).
  • Interrupting the stream tears down the widget. The iframe is removed /
    the popup is closed via a scope finalizer, so cancellation, timeouts,
    Stream.take, racing, etc. all just work.

Because it's a Stream, all the usual combinators apply: Stream.take(1)
for a one-shot result, Stream.timeout, Stream.runCollect, Stream.merge
with other event sources, and so on.

3. The launcher is a service
class Launcher extends Context.Service<Launcher, {
  readonly launch: <Payload, A, E>(
    widget: Widget<Payload, A, E>,
    payload: Payload["Type"],
  ) => Stream.Stream<A["Type"], Launcher.Error<E>, Payload["EncodingServices"]>
}>()("@effect/platform-browser/BrowserWidget/Launcher") {}

Two layers ship out of the box:

  • EmbedLauncher.layer({ url, className }): creates a full-viewport,
    transparent, sandboxed <iframe>.
  • PopupLauncher.layer({ url }): window.opens the widget, closes it
    on scope close.

App code is written once against Launcher; the choice of embed vs. popup
is a layer decision. This also makes widgets trivially testable: provide a
Launcher that returns Stream.make(...) and the calling code never
touches the DOM.

4. The widget side

The child page gets a tiny Self module:

  • Self.parent(): window.opener ?? window.parent, i.e. "whoever launched
    me", regardless of embed vs. popup.
  • Self.postFinished(): posts the done sentinel that ends the host's stream.
  • (Posting items is just parent().postMessage(encoded, origin).)

Happy to open a PR if there's appetite.

Lingua principale
TypeScript
Stelle
16.7k
Fork
808
Merge medio
10h 13m
PR unite (30g)
800

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Effect-TS/effect

Tutte le issue di Effect-TS/effect

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.