How shopify/remote-dom works
Based on our analysis of both the file tree and the README, this project is a monorepo for a library called Remote DOM. Its purpose is to allow a sandboxed (remote) JavaScript environment to render and update a “shadow” DOM which is synchronized with a host (main-thread) DOM. In other words, it lets developers create two JavaScript environments – one where potentially untrusted code runs (via an iframe or Web Worker) and one which actually renders the UI – and then efficiently synchronizes updates between them.
Main Components
• Remote Environment: This component runs in a sandbox (e.g., an iframe or Web Worker) and is responsible for creating and updating a virtual DOM.
– Uses a Remote Mutation Observer (from @remote-dom/core) to watch for DOM changes.
– Contains examples that demonstrate both basic usage and advanced custom element rendering.
• Host Environment: The main HTML page that renders the “real” UI.
– Incorporates a DOM Remote Receiver (from @remote-dom/core/receivers) to accept updates via postMessage and render corresponding custom elements on the page.
– Provides implementations of custom elements (e.g., ui-button) that are defined in the remote environment.
• Communication Channel: This is typically implemented via browser postMessage.
– Serves to transfer mutations and updates, ensuring synchronization between the remote and host.
• Additional Integration Packages:
– Support for specific frontend frameworks such as React, Preact, and Signals. They provide framework-specific wrappers and integration logic.
– The polyfill package supports running the library in non-DOM environments (like Web Workers).
– The compat package that might be providing adapter functionality for older or alternative environments.
Representing Relationships and Data Flow
– From the Remote Environment’s Mutation Observer to the host’s DOM Remote Receiver.
– From the remote code (via postMessage) to the host updating its DOM elements.
• Interaction between components like a custom element’s lifecycle – how a remote custom element (e.g., a ui-button) triggers updates that the host version picks up and renders (with attributes, events, and properties synchronized).
• “bridge” component that serializes/deserializes data (the messaging protocols and thread serialization like the usage of ThreadIframe and ThreadNestedWindow in the examples).
Architectural Patterns & Design Principles
• Messaging/Observer Pattern: The remote uses a mutation observer pattern to capture DOM changes; the host uses a receiver to apply these changes.
Relevant Technologies and Frameworks
• JavaScript/TypeScript (noting that the project utilizes TS as evidenced by tsconfig.json files).
• Build & Bundler Tools: Vite, Rollup, and configuration for deploying via GitHub Actions.
• Frontend Frameworks Integration: Preact, React, Svelte, Vue (as seen in the examples and integration packages).
• Testing & Linting: End-to-end tests (e2e folder), and CI/CD files in the .github/workflows directory for continuous integration.