Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Cerrado
  • ¿Algo no está bien?
#8,458 2 comentarios 1 reacción 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
38/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
typescript
Área
frontend

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
TypeScript
Estrellas
16.7k
Forks
808
Merge medio
10 h 33 min
PR fusionados (30 d)
830

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Effect-TS/effect

Todos los issues de Effect-TS/effect

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.