nuxt-ssr-lit

一个用于 Lit 自定义元素的服务器端渲染和客户端水合的 Nuxt3 模块。

🚀 使用方法

注意：此模块用于 Nuxt3。 请查看此问题关于 Nuxt2 支持。 我们正在寻求帮助以完成该模块。

安装

安装 nuxt-ssr-lit。

npx nuxi@latest module add ssr-lit

将以下代码添加到 nuxt.config.js 的模块部分。

import { defineNuxtConfig } from "nuxt";

export default defineNuxtConfig({
  modules: [
    ["nuxt-ssr-lit", { litElementPrefix: ["acme-"] }]
    // ...
  ]
});

就是这样！现在，所有以 acme- 为前缀的 Lit 元素都将进行服务器端渲染。 如果项目中有任何其他自定义元素，它们将进行客户端渲染。

👨‍💻 开发

• 运行 npm run dev:prepare 以生成类型存根。
• 使用 npm run dev 在开发模式下启动playground。

常见问题

TypeError: customElements.get(...) 不是构造函数

当 Lit 元素未正确注册时会发生此错误。 这可能是因为元素未正确设置，或者可能是由于元素具有副作用。 您可能只在生产模式下运行时才会看到此错误。

要解决此问题，可以在 nuxt.config.js 文件中注册您的自定义元素库。

export default defineNuxtConfig({
  ...
  nitro: {
    moduleSideEffects: ["my-custom-element-library"]
  }
});

它是如何工作的？

Nuxt 项目中所有使用模块选项中提供的前缀的 Lit 元素都将用一个名为 LitWrapper 的 Vue 组件包裹起来。

此自动包裹是通过一个名为 AutoLitWrapper 的 Vite 插件完成的，因此发生在构建时。 默认情况下，该插件仅在 Vue 文件上运行，这有助于通过避免不必要的处理来优化性能。

因此，如果其中一个组件中使用了 Lit 元素。 例如 <acme-button>Hello world</acme-button>，实际上由 Nuxt/Vue 生成和使用的代码将是 <LitWrapper><acme-button>Hello world</acme-button></LitWrapper>。

服务器端的 LitWrapper 组件使用 @lit-labs/ssr 的 LitElementRenderer 来使用声明式阴影 DOM渲染包裹的 Lit 元素。 这使得 Lit 组件在浏览器上正确渲染，而无需加载和执行 JS，并且在服务器 HTML 被解析后立即渲染。

客户端的 LitWrapper 组件 不执行任何操作，并让正常的客户端水合发生。

注意事项

Lit 组件通过将微型 DOM 垫片应用于 Node 来在 Node 端进行 SSR。 并非所有 DOM API 都可用。 例如，获取分配的插槽或子元素、调度自定义事件、在服务器端调用的生命周期钩子上添加事件侦听器将不起作用。 避免在服务器端运行的代码中进行此类客户端活动将使您受益匪浅。

另外，请查看 @lit-labs/ssr 的库状态以获取更多信息。