Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

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

クローズ
  • 何か問題がありますか？
#8,458 コメント 2 件 リアクション 1 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
38/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
活発
技術スタック
typescript
領域
frontend

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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.

主要言語
TypeScript
スター
16.7k
フォーク
808
平均マージ
11時間 33分
マージ済み PR（30日）
855

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

Effect-TS/effect のほかの issue

Effect-TS/effect の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。