@remote-dom/polyfill

@remote-dom/polyfill

A polyfill for the browser APIs used by Remote DOM. This allows you to use Remote DOM in environments that don’t have a native DOM, like Web Workers.

This package provides a low-level polyfill, with hooks that allow other libraries to intercept changes to the DOM. Unless you know you need this package, you probably want to import from @remote-dom/core/polyfill instead, which uses the hooks provided by this library to automatically synchronize remote elements between environments.

Installation

npm install @remote-dom/polyfill --save # npm
pnpm install @remote-dom/polyfill --save # pnpm
yarn add @remote-dom/polyfill # yarn

Usage

This package provides a Window class, which implements a limited subset of the Window browser interface. You’ll create an instance of the Window class and install it to the global environment using the Window.setGlobal() method.

import {Window} from '@remote-dom/polyfill';

const window = new Window();
Window.setGlobal(window);

// Now you can use many important DOM APIs, like `document` and `Element`:
const div = document.createElement('div');

This process will install polyfilled versions of the following globals:

• window, parent, top, and self which are all references to the Window instance (self is only overwritten when it is not already defined, to avoid overwriting the Web Worker self binding).
• document
• customElements
• location and navigator, though these are just set to globalThis.location and globalThis.navigator.
• The Event, EventTarget, CustomEvent, Node, ParentNode, ChildNode, Document, DocumentFragment, CharacterData, Comment, Text, Element, HTMLElement, SVGElement, HTMLTemplateElement, and MutationObserver constructors.

This polyfill lets you hook into many of the operations that happen in the DOM, like creating elements, updating attributes, and adding event listeners. You define these hooks by overwriting any of the properties on the hooks export of this library.

import {hooks} from '@remote-dom/polyfill';

hooks.createElement = (element) => {
  console.log('Creating element:', element);
};