[SSR/Core] Add @lit-labs/ssr-dom-shim package

[aomarks]

• Adds a new @lit-labs/ssr-dom-shim package which exports Element, HTMLElement, CustomElementRegistry, and a default global customElements (but does not register any of them as globals).

• Updates @lit/reactive-element/reactive-element.js to import from this package in its node build, instead of providing inline no-op versions. This means the parts of the DOM shim required for most Lit components will always be loaded in Node, so that users don't need to think about loading the DOM shim at all anymore.

• When using this new automatic shimming by importing reactive-element from Node, only a single global will now be defined: customElements. So in particular, window will not be defined, solving many issues we encountered with libraries sniffing for window to switch between node vs browser modes.

• ModuleLoader now provides a default VM global context object which provides basic globals that are available in both Node and browsers. A context object can also be directly created with a new makeDefaultContextObject function.

• Updates lit-html/experimental-hydrate.js to not depend on btoa when running in Node, instead using Node's built-in Buffer.

• Updates the existing @lit-labs/ssr/lib/dom-shim.js module to import HTMLElement and customElements from the new package, so that the same base class and registry are used when the full DOM shim is loaded.

• Makes registering a duplicate element in the DOM shim throw an exception.

• Misc minor improvements to the DOM shim code, including moving APIs from HTMLElement to Element, which is the correct interface for them.

• Updates to the following packages to remove usage of the global DOM shim in code/tests/READMEs:

  • @lit-labs/testing
  • @lit-labs/eleventy-plugin-lit
  • @lit-labs/ssr
  • @lit/localize-tools

See also lit/lit.dev#1026 which updates the lit.dev docs for these changes.

Fixes #3523

[changeset-bot]

🦋 Changeset detected

Latest commit: 4f01ca2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@lit-labs/eleventy-plugin-lit	Major
@lit-labs/ssr	Major
@lit-labs/testing	Minor
@lit-labs/ssr-dom-shim	Major
@lit/reactive-element	Minor
lit-html	Minor
lit	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

📊 Tachometer Benchmark Results

Summary

nop-update

• lit-html-kitchen-sink: unsure 🔍 -4% - +1% (-0.97ms - +0.25ms)
  ^{this-change vs tip-of-tree}

render

• lit-element-list: 81.03ms - 83.52ms
• lit-html-kitchen-sink: unsure 🔍 -6% - +0% (-1.81ms - +0.14ms)
  ^{this-change vs tip-of-tree}
• lit-html-repeat: unsure 🔍 -6% - +4% (-0.66ms - +0.48ms)
  ^{this-change vs tip-of-tree}
• lit-html-template-heavy: unsure 🔍 -2% - +3% (-0.83ms - +1.38ms)
  ^{this-change vs tip-of-tree}
• reactive-element-list: unsure 🔍 -1% - +5% (-0.43ms - +2.70ms)
  ^{this-change vs tip-of-tree}

update

• lit-element-list: 741.87ms - 751.58ms
• lit-html-kitchen-sink: unsure 🔍 -3% - +6% (-2.13ms - +4.73ms)
  ^{this-change vs tip-of-tree}
• lit-html-repeat: unsure 🔍 -10% - +9% (-31.15ms - +27.94ms)
  ^{this-change vs tip-of-tree}
• lit-html-template-heavy: unsure 🔍 -1% - +2% (-1.39ms - +1.92ms)
  ^{this-change vs tip-of-tree}
• reactive-element-list: unsure 🔍 -1% - +1% (-8.88ms - +4.39ms)
  ^{this-change vs tip-of-tree}

update-reflect

• lit-element-list: 743.47ms - 751.53ms
• reactive-element-list: unsure 🔍 -1% - +1% (-10.52ms - +4.23ms)
  ^{this-change vs tip-of-tree}

Results

lit-element-list

• Browser: chrome-headless 108.0.5359.98
• Sample size: 50
• Built by: Benchmarks #4251

• Commit: 915d2bd

render

Version	Avg time	vs
	81.03ms - 83.52ms	-

update

Version	Avg time	vs
	741.87ms - 751.58ms	-

update-reflect

Version	Avg time	vs
	743.47ms - 751.53ms	-

lit-html-kitchen-sink

• Browser: chrome-headless 108.0.5359.98
• Sample size: 30
• Built by: Benchmarks #4251

• Commit: 915d2bd

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	30.99ms - 31.80ms	-	unsure 🔍 -6% - +0% -1.81ms - +0.14ms	unsure 🔍 -6% - +1% -1.89ms - +0.38ms
tip-of-tree tip-of-tree	31.35ms - 33.12ms	unsure 🔍 -0% - +6% -0.14ms - +1.81ms	-	unsure 🔍 -4% - +5% -1.30ms - +1.46ms
previous-release previous-release	31.09ms - 33.21ms	unsure 🔍 -1% - +6% -0.38ms - +1.89ms	unsure 🔍 -5% - +4% -1.46ms - +1.30ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	80.76ms - 85.32ms	-	unsure 🔍 -3% - +6% -2.13ms - +4.73ms	unsure 🔍 -6% - +2% -5.20ms - +1.70ms
tip-of-tree tip-of-tree	79.18ms - 84.30ms	unsure 🔍 -6% - +3% -4.73ms - +2.13ms	-	unsure 🔍 -8% - +1% -6.69ms - +0.58ms
previous-release previous-release	82.21ms - 87.37ms	unsure 🔍 -2% - +6% -1.70ms - +5.20ms	unsure 🔍 -1% - +8% -0.58ms - +6.69ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	21.97ms - 22.75ms	-	unsure 🔍 -4% - +1% -0.97ms - +0.25ms	unsure 🔍 -5% - +2% -1.08ms - +0.54ms
tip-of-tree tip-of-tree	22.25ms - 23.18ms	unsure 🔍 -1% - +4% -0.25ms - +0.97ms	-	unsure 🔍 -3% - +4% -0.76ms - +0.94ms
previous-release previous-release	21.92ms - 23.33ms	unsure 🔍 -2% - +5% -0.54ms - +1.08ms	unsure 🔍 -4% - +3% -0.94ms - +0.76ms	-

lit-html-repeat

• Browser: chrome-headless 108.0.5359.98
• Sample size: 30
• Built by: Benchmarks #4251

• Commit: 915d2bd

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	11.38ms - 12.19ms	-	unsure 🔍 -6% - +4% -0.66ms - +0.48ms	unsure 🔍 -3% - +8% -0.34ms - +0.88ms
tip-of-tree tip-of-tree	11.47ms - 12.28ms	unsure 🔍 -4% - +6% -0.48ms - +0.66ms	-	unsure 🔍 -2% - +9% -0.25ms - +0.97ms
previous-release previous-release	11.05ms - 11.97ms	unsure 🔍 -7% - +3% -0.88ms - +0.34ms	unsure 🔍 -8% - +2% -0.97ms - +0.25ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	298.87ms - 342.43ms	-	unsure 🔍 -10% - +9% -31.15ms - +27.94ms	unsure 🔍 -10% - +8% -33.00ms - +26.63ms
tip-of-tree tip-of-tree	302.29ms - 342.22ms	unsure 🔍 -9% - +10% -27.94ms - +31.15ms	-	unsure 🔍 -9% - +8% -30.09ms - +26.93ms
previous-release previous-release	303.48ms - 344.19ms	unsure 🔍 -8% - +10% -26.63ms - +33.00ms	unsure 🔍 -8% - +9% -26.93ms - +30.09ms	-

lit-html-template-heavy

• Browser: chrome-headless 108.0.5359.98
• Sample size: 50
• Built by: Benchmarks #4251

• Commit: 915d2bd

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	54.08ms - 55.62ms	-	unsure 🔍 -2% - +3% -0.83ms - +1.38ms	slower ❌ 0% - 4% 0.11ms - 2.03ms
tip-of-tree tip-of-tree	53.79ms - 55.37ms	unsure 🔍 -3% - +2% -1.38ms - +0.83ms	-	unsure 🔍 -0% - +3% -0.17ms - +1.77ms
previous-release previous-release	53.21ms - 54.35ms	faster ✔ 0% - 4% 0.11ms - 2.03ms	unsure 🔍 -3% - +0% -1.77ms - +0.17ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	110.34ms - 112.51ms	-	unsure 🔍 -1% - +2% -1.39ms - +1.92ms	unsure 🔍 -1% - +2% -0.82ms - +2.13ms
tip-of-tree tip-of-tree	109.91ms - 112.40ms	unsure 🔍 -2% - +1% -1.92ms - +1.39ms	-	unsure 🔍 -1% - +2% -1.21ms - +1.98ms
previous-release previous-release	109.77ms - 111.77ms	unsure 🔍 -2% - +1% -2.13ms - +0.82ms	unsure 🔍 -2% - +1% -1.98ms - +1.21ms	-

reactive-element-list

• Browser: chrome-headless 108.0.5359.98
• Sample size: 50
• Built by: Benchmarks #4251

• Commit: 915d2bd

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	53.38ms - 55.49ms	-	unsure 🔍 -1% - +5% -0.43ms - +2.70ms	unsure 🔍 -5% - +2% -2.91ms - +1.00ms
tip-of-tree tip-of-tree	52.14ms - 54.46ms	unsure 🔍 -5% - +1% -2.70ms - +0.43ms	-	faster ✔ 0% - 7% 0.07ms - 4.10ms
previous-release previous-release	53.74ms - 57.03ms	unsure 🔍 -2% - +5% -1.00ms - +2.91ms	slower ❌ 0% - 8% 0.07ms - 4.10ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	750.47ms - 758.93ms	-	unsure 🔍 -1% - +1% -8.88ms - +4.39ms	unsure 🔍 -1% - +1% -8.66ms - +4.61ms
tip-of-tree tip-of-tree	751.82ms - 762.06ms	unsure 🔍 -1% - +1% -4.39ms - +8.88ms	-	unsure 🔍 -1% - +1% -7.01ms - +7.46ms
previous-release previous-release	751.60ms - 761.83ms	unsure 🔍 -1% - +1% -4.61ms - +8.66ms	unsure 🔍 -1% - +1% -7.46ms - +7.01ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	771.40ms - 781.76ms	-	unsure 🔍 -1% - +1% -10.52ms - +4.23ms	unsure 🔍 -1% - +1% -4.64ms - +9.09ms
tip-of-tree tip-of-tree	774.48ms - 784.97ms	unsure 🔍 -1% - +1% -4.23ms - +10.52ms	-	unsure 🔍 -0% - +2% -1.54ms - +12.28ms
previous-release previous-release	769.86ms - 778.86ms	unsure 🔍 -1% - +1% -9.09ms - +4.64ms	unsure 🔍 -2% - +0% -12.28ms - +1.54ms	-

_{tachometer-reporter-action v2 for Benchmarks}

[augustjk]

This is great! Some comments below.

[aomarks]

Comments addressed.

Also addressed two comments from @kevinpschaaf that were made in an in-person conversation:

• reactive-element.js in Node now falls back to globalThis.HTMLElement if one has been defined, which matches the behavior we had before, and allows users to use alternative DOM shims if they want.

• The existing getWindow function from the SSR package now behaves like it did before, in that it returns a new CustomElementRegistry for each object, instead of using a global singleton. This is important for VM modules that are using getWindow, since otherwise there would be a shared CE registry between different VM render contexts.

[aomarks]

Ah, seeing failures relating to code that looks at the TypeScript AST. Now I remember why we did the weird temporary-global-assignment trick previously. Though that won't work here, because of the shadowing we have due to the import. Will need to investigate another pattern.

   FAIL  legacy class field emit  "@localized"
    Expected values to be deeply equal:  (equal)

        ··[
        Actual:
        --··"../reactive-element/reactive-element.d.ts(181,55):·error·TS2749:·'ReactiveElement_base'·refers·to·a·value,·but·is·being·used·as·a·type·here.·Did·you·mean·'typeof·ReactiveElement_base'?\n",
        ··]

[aomarks]

Also just pushed updates to the following packages to remove usage of the global DOM shim in its code/tests/READMEs:

• @lit-labs/testing (the actual code)
• @lit-labs/eleventy-plugin-lit (the actual code)
• @lit-labs/ssr (the README)
• @lit/localize-tools (a test)

There is now no usage of the global DOM shim in any of our packages.

[aomarks]

See also lit/lit.dev#1026 which updates the lit.dev docs to account for this new approach of automatic shimming.

[justinfagnani]

awesome!

[augustjk]

This is fantastic! Super excited to see this land.

Minor suggestions for importing render from @lit-labs/ssr in other packages.

[kevinpschaaf]

Wonder if this change should be major since it's potentially removing previously shimmed globals?

[aomarks]

Yeah it should be, but since we're still on 0.x.x we have to call it minor or else changesets will release 1.0.0.

[aomarks]

Although now that I think of it, let's just release 1.0.0