nuxt-ssr-lit

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

🚀 使用方法

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

安装

安装 nuxt-ssr-lit。

npx nuxi@latest module add ssr-lit

将以下代码添加到 nuxt.config.js 文件的 modules 部分。

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(...) is not a constructor`

当 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 使用声明式 Shadow DOM 渲染包装的 Lit 元素。这使得 Lit 组件在浏览器上正确渲染，而无需加载和执行 JS，并且一旦服务器 HTML 被解析。

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

注意事项

Lit 组件通过在 Node 端应用一个微小的 DOM shim 进行 SSR。并非所有 DOM API 都可用。例如，获取分配的插槽或子元素、分派自定义事件、在服务器端调用的生命周期钩子上添加事件监听器将不起作用。避免在服务器运行的代码中进行此类客户端活动将使您走得更远。

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