Skip to content

Docs: interactive playground (Monaco + GraphiQL, WebContainers) #29

Description

@egriff38

Split from #15.

An in-browser sandbox where a user can:

  1. Edit a Provider declaration in Monaco on the left (with our types autocompleting)
  2. Run it inline and hit the derived schema through GraphiQL on the right
  3. Change a resolver → see the effect immediately in GraphiQL

The hard part

The library uses effect, graphql-js, and Provider.toExecutor internally — this isn't a pure-syntax playground. Options:

  • A. WebContainers (StackBlitz SDK) — real Node.js in the browser via WASM. Runs bun install + bun start in-page. Faithful to the actual runtime; heavy first-load (~30-50 MB).
  • B. Pre-built worker bundle — ship the library + a tiny driver as an ESM bundle to a Web Worker; user code compiles via @typescript/vfs and gets evaluated inside the worker. Lighter, but has to reimplement enough of Node to satisfy effect/unstable/http and the two-tier runtime.
  • C. StackBlitz iframe embed — outsource everything to a StackBlitz project template. Zero infra on our end; leaves our docs, opens a new tab. Loses side-by-side layout unless we iframe it into VitePress.

My lean: A (WebContainers). Preserves the "type it, run it here" story that makes the demo compelling. Cost is one-time infra; per-visit cost is a first-load hit that people accept for playgrounds.

Depends on

#25 (VitePress site must exist to host the playground route).

Acceptance

  • /playground route in the docs site
  • Split-pane: Monaco left, GraphiQL right, seeded with the README hello-world
  • Autocomplete works for Provider.* (we ship .d.ts files via WebContainer's virtual FS)
  • Edit-and-run under 500 ms after initial boot
  • Share button — playground state encoded in URL (Sandpack-style)

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions