# shopify/remote-dom architecture

> Architecture diagram of the GitHub repository shopify/remote-dom, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shopify/remote-dom
- Repository: https://github.com/shopify/remote-dom

## Overview

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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Remote Environment"
        REM["Remote Mutation Observer"]:::remote
        SBOX["Sandboxed Code (iframe/Web Worker)"]:::remote
    end

    subgraph "Communication Bridge"
        PM["PostMessage Channel"]:::bridge
        CONN["Connection Abstraction"]:::bridge
    end

    subgraph "Host Environment"
        HOST_RECEIVER["DOM Remote Receiver"]:::host
        HOST_RENDERER["Custom Element Renderer"]:::host
    end

    subgraph "Integration Packages"
        REACT["React Integration"]:::integration
        PREACT["Preact Integration"]:::integration
        SIGNALS["Signals Integration"]:::integration
        POLYFILL["Polyfill Support"]:::integration
        COMPAT["Compat Support"]:::integration
    end

    SBOX -->|"triggers"| REM
    REM -->|"sendsMutation"| PM
    CONN -->|"enables"| PM
    PM -->|"forwardsUpdate"| HOST_RECEIVER
    HOST_RECEIVER -->|"appliesUpdates"| HOST_RENDERER

    REACT -.->|"integrates"| HOST_RECEIVER
    PREACT -.->|"integrates"| HOST_RECEIVER
    SIGNALS -.->|"integrates"| HOST_RECEIVER
    POLYFILL -.->|"supports"| REM
    COMPAT -.->|"adapts"| REM

    click REM "https://github.com/shopify/remote-dom/blob/main/packages/core/source/elements/RemoteMutationObserver.ts"
    click HOST_RECEIVER "https://github.com/shopify/remote-dom/blob/main/packages/core/source/receivers/DOMRemoteReceiver.ts"
    click HOST_RENDERER "https://github.com/shopify/remote-dom/blob/main/examples/kitchen-sink/app/host.tsx"
    click CONN "https://github.com/shopify/remote-dom/blob/main/packages/core/source/connection.ts"
    click REACT "https://github.com/shopify/remote-dom/tree/main/packages/react"
    click PREACT "https://github.com/shopify/remote-dom/tree/main/packages/preact"
    click SIGNALS "https://github.com/shopify/remote-dom/tree/main/packages/signals"
    click POLYFILL "https://github.com/shopify/remote-dom/tree/main/packages/polyfill"
    click COMPAT "https://github.com/shopify/remote-dom/tree/main/packages/compat"

    classDef remote fill:#AED6F1,stroke:#1F618D,stroke-width:2px
    classDef bridge fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px
    classDef host fill:#A9DFBF,stroke:#27AE60,stroke-width:2px
    classDef integration fill:#F5CBA7,stroke:#B9770E,stroke-width:2px
```
