|
| 1 | +# Qwik Docs REPL |
| 2 | + |
| 3 | +This folder contains the client-side REPL (Read-Eval-Print Loop) used in the Qwik docs site. The REPL lets users write and run Qwik/TypeScript code snippets in the browser, see results, and share runnable examples. |
| 4 | + |
| 5 | +This README gives a high-level overview of how the REPL is structured, what each area is responsible for, and some development notes and suggested improvements. |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## High-level architecture |
| 10 | + |
| 11 | +The REPL is a browser-first system composed of three main parts: |
| 12 | + |
| 13 | +- Bundler subsystem (web-worker + helpers): transforms user code, resolves imports, bundles modules, and prepares runnable artifacts. |
| 14 | +- Service worker: Intercepts requests to `/repl/[id]/*` and messages the bundler subsystem (via BroadcastChannel) to get responses. This allows the REPL to work without a server. |
| 15 | +- UI (React/Qwik components + Monaco): editor, panels, console, options and controls that let users edit code and view outputs. |
| 16 | + |
| 17 | +The codebase keeps bundling and heavy work off the main thread by using a web worker script per Qwik version. |
| 18 | + |
| 19 | +## Key directories & files |
| 20 | + |
| 21 | +- `bundler/` |
| 22 | + - `bundled.tsx` — provides the current development version of Qwik, so that the REPL can show the latest features, and it can work while developing offline. |
| 23 | + - `bundler-registry.ts` — maintains the per-version Qwik WebWorkers. |
| 24 | + - `bundler-worker.ts` — bundles and runs the REPL user code. |
| 25 | + - `repl-instance.ts` — orchestration or single-instance logic for a REPL embed on a page. |
| 26 | + |
| 27 | +- `repl-sw.ts` and `register-repl-sw.ts` |
| 28 | + - Service worker script and registration helper. The script is actually served via the route `/src/routes/repl/repl-sw.js/entry.ts`, which becomes the served path `/repl/repl-sw.js`. |
| 29 | + |
| 30 | +- `ui/` |
| 31 | + - `editor.tsx`, `monaco.tsx` — Monaco editor wiring and editor UI glue. |
| 32 | + - `repl-*.tsx` — UI components for console, input/output panels, tabs, share URL, version display, etc. |
| 33 | + |
| 34 | +## How it works |
| 35 | + |
| 36 | +1. The UI component (`ui/editor.tsx` + `ui/monaco.tsx`) presents a code editor and controls. |
| 37 | +2. When code is executed, the bundler subsystem is invoked. The UI posts a message to the bundler worker. |
| 38 | +3. The bundler worker (`bundler-worker.ts`) makes the client and SSR bundles, and executes `render()` from the `entry.ssr` to get the SSR result HTML. |
| 39 | +4. The UI also shows an iframe, loading `/repl/[id]/`. |
| 40 | +5. The service worker intercepts all requests and uses messages to get the bundle + html files from the worker. |
| 41 | + |
| 42 | +### Flow diagram |
| 43 | + |
| 44 | +- The iframe requests `/repl/[id]/` |
| 45 | +- The service worker intercepts and sends a message to the REPL instance |
| 46 | +- The REPL instance messages the bundler to bundle the user code |
| 47 | +- The bundler messages the REPL with the result |
| 48 | +- The REPL messages the service worker with the requested file |
| 49 | +- The service worker fullfils the request |
| 50 | + |
| 51 | +```mermaid |
| 52 | +flowchart TD |
| 53 | + Iframe["Iframe - /repl/[replId]/"] |
| 54 | + ServiceWorker["Service Worker (/repl/*)"] |
| 55 | + ReplInstance["REPL instance"] |
| 56 | + BundlerWorker["Bundler Worker"] |
| 57 | +
|
| 58 | + ReplInstance -->|REPL user code| BundlerWorker |
| 59 | + BundlerWorker -->|ReplResult| ReplInstance |
| 60 | + ServiceWorker -->|message: fetch pathname| ReplInstance |
| 61 | + Iframe -->|HTTP request| ServiceWorker |
| 62 | + ReplInstance -->|file contents| ServiceWorker |
| 63 | + ServiceWorker -->|respond to iframe| Iframe |
| 64 | +``` |
| 65 | + |
| 66 | +## Running the REPL |
| 67 | + |
| 68 | +The REPL is part of the docs site — start the docs dev server (project root): |
| 69 | + |
| 70 | +```bash |
| 71 | +pnpm docs.dev |
| 72 | +``` |
| 73 | + |
| 74 | +Then visit `/playground`. |
| 75 | + |
| 76 | +- Resource limits & sandboxing: Running arbitrary user code in the browser can be risky — ensure sandboxed iframes and timeouts/limits for executed code to avoid locking the page. |
0 commit comments