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(...) 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>你好世界</acme-button>，Nuxt/Vue 实际生成和使用的代码将是 <LitWrapper><acme-button>你好世界</acme-button></LitWrapper>。

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

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

注意事项

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

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