Skip to content

Commit 72fcf0d

Browse files
aomarksaomarks
authored
[SSR/Core] Add @lit-labs/ssr-dom-shim package (#3522)
- 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
1 parent d1f9d14 commit 72fcf0d

41 files changed

Lines changed: 1256 additions & 586 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.changeset/empty-cooks-clap.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@lit-labs/eleventy-plugin-lit': major
3+
---
4+
5+
The Lit SSR global DOM shim is no longer automatically loaded when rendering Lit components from Eleventy. When paired with the latest version of Lit, the global DOM shim is no longer typically required, because Lit now automatically imports shimmed versions of needed APIs.

‎.changeset/fair-spiders-wave.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@lit-labs/ssr': major
3+
---
4+
5+
ModuleLoader now provides a default VM global context object which provides basic globals that are available in both Node and browsers.

‎.changeset/fast-insects-fix.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@lit-labs/ssr': major
3+
---
4+
5+
The SSR dom shim will now throw if a custom element is redefined.

‎.changeset/healthy-pants-sit.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
'@lit-labs/testing': minor
3+
---
4+
5+
@lit-labs/testing no longer automatically loads the Lit SSR global DOM shim
6+
when performing SSR, instead relying on newer versions of Lit which automatically
7+
load necessary shims with minimal global pollution.
8+
9+
This may cause new or different test failures, because APIs such as `document`
10+
will no longer be available on the server by default. Use `isServer` from the
11+
`lit` package to guard against calling such APIs during SSR (see
12+
https://lit.dev/docs/ssr/authoring/#browser-only-code for more information).

‎.changeset/olive-shoes-relax.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
'@lit-labs/ssr-dom-shim': major
3+
'@lit-labs/ssr': minor
4+
'@lit/reactive-element': minor
5+
'lit-html': minor
6+
'lit': minor
7+
---
8+
9+
When running in Node, Lit now automatically includes minimal DOM shims which are
10+
sufficient for most SSR (Server Side Rendering) use-cases, removing the need to
11+
import the global DOM shim from `@lit-labs/ssr`.
12+
13+
The new `@lit-labs/ssr-dom-shim` package has been introduced, which exports an `HTMLElement`, `CustomElementRegistry`, and default `customElements` singleton.
14+
15+
The existing `@lit-labs/ssr` global DOM shim can still be used, and is compatible with the new package, because `@lit-labs/ssr` imports from `@lit-labs/ssr-dom-shim`. Importing the global DOM shim adds more APIs to the global object, such as a global `HTMLElement`, `TreeWalker`, `fetch`, and other APIs. It is recommended that users try to remove usage of the `@lit-labs/ssr` DOM shim, and instead rely on the more minimal, automatic shimming that `@lit/reactive-element` now provides automatically.

‎.changeset/rich-icons-attack.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@lit-labs/ssr': minor
3+
---
4+
5+
APIs such as attachShadow, setAttribute have been moved from the HTMLElement class shim to the Element class shim, matching the structure of the real API. This should have no effect in most cases, as HTMLElement inherits from Element.

‎.eslintignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -275,6 +275,8 @@ packages/labs/ssr-client/controllers/
275275
packages/labs/ssr-client/node_modules/
276276
packages/labs/ssr-client/index.*
277277

278+
packages/labs/ssr-dom-shim/index.*
279+
278280
packages/labs/task/development/
279281
packages/labs/task/test/
280282
packages/labs/task/node_modules/

‎.prettierignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -262,6 +262,8 @@ packages/labs/ssr-client/controllers/
262262
packages/labs/ssr-client/node_modules/
263263
packages/labs/ssr-client/index.*
264264

265+
packages/labs/ssr-dom-shim/index.*
266+
265267
packages/labs/task/development/
266268
packages/labs/task/test/
267269
packages/labs/task/node_modules/

0 commit comments

Comments
 (0)