🌜
🌞
@ampproject/worker-dom

@ampproject/worker-dom

v0.34.0

A facsimile of a modern DOM implementation intended to run in a Web Worker.

npm install @ampproject/worker-dom

README

WorkerDOM

An in-progress implementation of the DOM API intended to run within a Web Worker.

Purpose: Move complexity of intermediate work related to DOM mutations to a background thread, sending only the necessary manipulations to a foreground thread.

Use Cases:

  1. Embedded content from a third party living side by side with first party code.
  2. Mitigation of expensive rendering for content not requiring synchronous updates to user actions.
  3. Retaining main thread availablity for high priority updates by async updating elsewhere in a document.

For more information, visit our blog post announcing WorkerDOM or checkout the slides from the announcement at JSConf US.

Installation

npm install @ampproject/worker-dom

Usage

WorkerDOM comes in two flavours, a global variant and a module variant. It is possible to include the WorkerDOM main thread code within your document directly or via a bundler. Here's how you might do so directly:

<script src="path/to/workerdom/dist/main.mjs" type="module"></script>
<script src="path/to/workerdom/dist/main.js" nomodule defer></script>

WorkerDOM allows us to upgrade a specific section of the document to be driven by a worker. For example, imagine a div node in the page like so:

<div src="hello-world.js" id="upgrade-me"></div>

To upgrade this node using the module version of the code, we can directly import upgradeElement and use it like this:

<script type="module">
  import {upgradeElement} from './dist/main.mjs';
  upgradeElement(document.getElementById('upgrade-me'), './dist/worker/worker.mjs');
</script>

The nomodule format exposes the global MainThread, and could upgrade the div in the following way:

<script nomodule async=false defer>
  document.addEventListener('DOMContentLoaded', function() {
    MainThread.upgradeElement(document.getElementById('upgrade-me'), './dist/worker/worker.js');
  }, false);
</script>

AMP Distribution for amp-script

WorkerDOM has a special output variant that supplies additional hooks for safety features e.g. HTML sanitization. This variant is distributed under the amp folder for main and worker thread binaries:

amp/main.mjs
amp/worker/worker.mjs

This output assumes the consumer will compile this distributed JavaScript to ensure it works with older user-agents.

Debug Distribution

WorkerDOM also has an output variant that includes additional debugging messages. This variant is distributed in the debug folder.

debug/main.mjs
debug/main.js
debug/worker/worker.mjs
debug/worker/worker.js

Running Demos Locally

After cloning the repository, you can try out the debug demos with the following.

npm run demo

This script will build the current version of WorkerDOM and start up a local webserver.

Which JavaScript APIs can I use?

Currently, most DOM elements and their properties are supported. DOM query APIs like querySelector have partial support. Browser APIs like History are not implemented yet. Please see the API support matrix here.

Which Browsers are supported?

In general we support the latest two versions of major browsers like Chrome, Firefox, Edge, Safari, Opera and UC Browser. We support desktop, phone, tablet and the web view version of these respective browsers.

Beyond that, we aim for very wide browser support and we accept fixes for all browsers with market share greater than 1 percent.

In particular, we try to maintain "it might not be perfect but isn't broken"-support for IE 11, iOS 8, the Android 4.0 system browser and Chrome 41.

Local Development

Local development of WorkerDOM assumes the following:

  1. Familiarity with npm or yarn
  2. Latest LTS release of Node (10 at time of writing) available.
  3. Comfort with TypeScript, the codebase and tests are entirely written in TypeScript.

Release Log

Each release includes a log of changes with the newly released version. You can find the log here: https://github.com/ampproject/worker-dom/releases

Security disclosures

The AMP Project accepts responsible security disclosures through the Google Application Security program.

Code of conduct

The AMP Project strives for a positive and growing project community that provides a safe environment for everyone. All members, committers and volunteers in the community are required to act according to the code of conduct.

License

worker-dom is licensed under the Apache License, Version 2.0.

Release Notes

0.34.0
By Jake Fried • Published on March 3, 2022
  • Update all (#1135) d27b429
  • Storage: fix clear and removeItem (#1136) a6bcd6f
  • Update all (#1131) 9cff888

https://github.com/ampproject/worker-dom/compare/v0.33.0...v0.34.0

0.33.0
By Jake Fried • Published on February 11, 2022
  • Add support for nextElementSibling and previousElementSibling (#1132) c906bfc
  • babel loose mode compat: dont spread Set (#1133) d418048
  • Update all (#1130) ad6093d
  • Update all (#1129) 972bbc7
  • Update all (#1127) 7168469
  • Update all (#1124) 808c786
  • Update babel monorepo to v7.16.7 (#1123) 3f3f7b4
  • Update all (#1122) 69207e4
  • Update babel monorepo to v7.16.5 (#1120) 18de540
  • Update all (#1119) 5f56425
  • Update all (#1118) 7fb5d5b
  • Update dependency jsdom to v19 (#1116) edb2f34
  • Update all (#1115) 45ebdcc
  • Update dependency @babel/preset-env to v7.16.4 (#1114) 94b2c5f
  • Update all (#1113) 9a9846e
  • Update all (#1111) d506dbb
  • Update dependency lint-staged to v12 (#1112) fa58c7a
  • Update all (#1110) ea7a243
  • Update babel monorepo (#1106) 52cff6d
  • Update all (#1108) 6a80c79
  • Update all (#1109) 098aba3
  • Added a flag to selectively use shadow dom (#1101) d90e684
  • more descriptive type signature for tuples (#1107) 79ed3f7
  • Update all (#1105) d54c650
  • Update babel monorepo to v7.15.8 (#1104) 3cf6f4e
  • Update all (#1103) 4ade289
  • Update all (#1102) 718accd

https://github.com/ampproject/worker-dom/compare/v0.32.1...v0.33.0

0.32.1
By Jake Fried • Published on September 28, 2021
  • server-lib bugfix: need scopingRoot (#1100) 7c54163

https://github.com/ampproject/worker-dom/compare/v0.32.0...v0.32.1

0.32.0
By Jake Fried • Published on September 28, 2021
  • Benchmark + optimize (#1096) b9ffedd
  • Update all (#1098) cc71f9c
  • Remove copyright header (#1097) da975ce
  • Update all (#1094) 1cf1404
  • Update babel monorepo (#1089) 0388c01
  • Update all (#1083) 5d3cdab

https://github.com/ampproject/worker-dom/compare/v0.31.0...v0.32.0

0.31.0
By Jake Fried • Published on September 10, 2021
  • Use Object.assign (#1092) 7b60849
  • nodom: workerDOM should be document.defaultView (#1091) b2363aa
  • Update babel monorepo to v7.15.0 (#1084) 11ff429
  • Update dependency jsdom to v17 (#1085) 701be54
  • Update babel monorepo to v7.14.9 (#1082) 0f632ba
  • Update all (#1081) be74f37
  • Update all (#1079) 42ebf34
  • Update babel monorepo to v7.14.8 (#1080) 1803335
  • Update all (#1077) 0dbc94e
  • Update all (#1069) 4f94f2c
  • Babel plugins: remove outdated proposals (#1074) d2baf04
  • Update babel monorepo to v7.14.7 (#1070) c1d49b1
  • Update all (#1071) 5401ef6

https://github.com/ampproject/worker-dom/compare/v0.30.1...v0.31.0

0.30.1
By Jake Fried • Published on July 2, 2021
  • Remove all 'import type' after discovery of a TS bug (#1073) 95bb805
  • worker: fix faulty import type (#1072) 35139ef

https://github.com/ampproject/worker-dom/compare/v0.30.0...v0.30.1

0.30.0
By Jake Fried • Published on June 30, 2021
  • nodom: support storage (#1064) 5d4d4c9
  • Separate out all type-only imports (#1067) b1f1658
  • Update all (#1061) f5df3c3
  • Consolidate prettier (#1066) af09257
  • Update babel monorepo (#1065) 1f7faa0
  • Update dependency sinon to v11 (#1063) f627793
  • Update babel monorepo (#1062) b4a1b33
  • Update dependency lint-staged to v11 (#1057) 8fe7039
  • Update babel monorepo (#1054) 471afef
  • Update all (#1053) 92eed67

https://github.com/ampproject/worker-dom/compare/v0.29.3...v0.30.0

0.29.3
By Jake Fried • Published on May 5, 2021
  • create new server-build, for server side use cases (#1055) 3bdf0d2
  • Update babel monorepo to v7.13.16 (#1050) e08c069
  • Update dependency @types/sinon to v10 (#1051) fd862e5
  • Update all (#1049) 3efa121

https://github.com/ampproject/worker-dom/compare/v0.29.2...v0.29.3

0.29.2
By Jake Fried • Published on April 20, 2021
  • Add forgotten demo file (#1048) 6d2844f
  • WorkerDOM.upgrade should wait for Worker init. (#1047) 1472534
  • Update babel monorepo to v7.13.15 (#1046) 253e7b0
  • Update all (#1045) 6005206

https://github.com/ampproject/worker-dom/compare/v0.29.1...v0.29.2

0.29.1
By Jake Fried • Published on April 9, 2021
  • Remove errant 'await' that slipped in. (#1044) 3c4341b
  • Update all (#1043) bff2183

https://github.com/ampproject/worker-dom/compare/v0.29.0...v0.29.1

General

License
Apache-2.0
Typescript Types
None found
Tree-shakeable
No

Popularity

GitHub Stargazers
3,003
Community Interest
3,045
Number of Forks
140

Maintenance

Commits
11/2110/2209
Last Commit
Open Issues
85
Closed Issues
82
Open Pull Requests
8
Closed Pull Requests
184

Versions

Versions Released
11/2110/2201
Latest Version Released
Mar 3, 2022
Current Tags
latest0.34.0

Contributors

renovate-bot
renovate-bot
Commits: 492
kristoferbaxter
kristoferbaxter
Commits: 251
choumx
choumx
Commits: 57
samouri
samouri
Commits: 47
renovate[bot]
renovate[bot]
Commits: 25
nainar
nainar
Commits: 20
delima02
delima02
Commits: 14
jridgewell
jridgewell
Commits: 6
dvoytenko
dvoytenko
Commits: 6
patrickkettner
patrickkettner
Commits: 3
JamesLMilner
JamesLMilner
Commits: 3
niutech
niutech
Commits: 2
mrjoro
mrjoro
Commits: 2
andrei0x309
andrei0x309
Commits: 1
honeybadgerdontcare
honeybadgerdontcare
Commits: 1