使用 Lit 创建一个 AI 对话组件库 03 可行性验证篇

1672 字

8 分钟

使用 Lit 创建一个 AI 对话组件库 03 可行性验证篇

2025-03-01

教程

hyosan-chat

/

Lit

/

vite

/

Web Components

/

chat

/

lib

/

component library

/

vue

本文将介绍组件库在打包发布后, 在实际的项目中使用是否可行，以及如何进行验证

目录#

为什么要验证可行性#

当我们打算使用一项新技术或新的库时, 最先要做的就是验证可行性; 因为对于新的外部依赖, 我们无法确定是否符合预期, 以及是否会带来新的问题, 进行一次最小规模的验证, 可以 尽早的暴露问题

打包#

我们的项目是使用 vite 进行搭建的, vite 提供了 library mode 以支持将项目中的部分文件进行单独打包, 并构建为库以供其他项目使用

TypeScript 配置#

1
# 引入生成 .d.ts 文件的插件
2
pnpm i -D vite-plugin-dts

tsconfig.json:

1
{
2
  "compilerOptions": {
3
    // ...
4
    "declaration": true,
5
    "outDir": "dist",
6
  }
7
}

创建 src/lib.ts 作为组件库的入口文件:

1
export * from './components'

我们的项目是使用 ts 编写的, 为了让我们的组件库可以支持 ts 项目, 我们需要使用 vite-plugin-dts 将 .d.ts 文件生成到 dist 目录下

vite.config.ts:

1
 import dts from 'vite-plugin-dts'
2

3
export default defineConfig({
4
  // ...
5
   plugins: [
6
     // 用于生成 `d.ts` 文件, refer https://github.com/qmhc/vite-plugin-dts/blob/HEAD/README.zh-CN.md
7
     dts({ tsconfigPath: './tsconfig.lib.json' })
8
   ],
9
   build: {
10
     lib: {
11
       name: 'hyosan-chat',
12
       entry: ['src/lib.ts'],
13
       fileName: 'hyosan-chat',
14
     },
15
   },
16
})

创建 tsconfig.lib.json:

1
{
2
  "extends": "./tsconfig.json", // 继承已有的 tsconfig.json
3
  "include": [ // 添加需要在打包时生产 .d.ts 文件的文件
4
    "./src/lib.ts",
5
    "./src/components/**/*.ts",
6
  ]
7
}

TIP
为什么要额外创建一个 tsconfig.json?
在打包时, vite-plugin-dts 会将 tsconfig.json 中的 include 中的文件进行打包(这里指生成 dts), 但 tsconfig.json 中 include 包含了项目中的所有文件, 也包括了不应该出现在 dist 目录中的文件, 但我们不能修改 tsconfig.json, 因为它适用于整个项目的开发环境, 所以我们需要创建单独的 tsconfig.lib.json 用于生成 d.ts
也就是说, tsconfig.json 用于开发环境, tsconfig.lib.json 用于打包时生成 d.ts

我们将 src/lib.ts 中导出的组件作为整个组件库对外提供的组件, 并通过 vite-plugin-dts 生成了类型描述文件

package.json 配置#

当我们的项目作为组件库供外部使用时, 需要在 package.json 中声明 组件库的基本信息和对外提供的文件:

1
{
2
   "description": "A library of web components for AI conversations based on lit and shoelace",
3
   "keywords": ["hyosan-chat", "Lit", "Shoelace", "AI", "chat", "Web Components", "web chat"],
4
   "author": {
5
      "name": "Ryan"
6
   },
7
   "license": "MIT",
8
   "version": "0.0.0",
9
   "version": "0.0.1",
10
  "private": true,
11
   "files": [
12
     "dist"
13
   ],
14
   "main": "./dist/hyosan-chat.umd.cjs",
15
   "module": "./dist/hyosan-chat.js",
16
   "exports": {
17
     ".": {
18
       "import": "./dist/hyosan-chat.js",
19
       "require": "./dist/hyosan-chat.umd.cjs"
20
     }
21
   },
22
  "scripts": {
23
    "build:pack": "pnpm run build && pnpm pack",
24
  },
25
}

build & pack#

修改完打包所需的配置后, 我们就可以使用 pnpm run build 进行打包了:

1
# 打包
2
pnpm run build
3

4
# 打包并生成 .tgz 文件
5
pnpm run build:pack

1
lsd --tree dist/
2
 dist
3
├──  components
4
│   ├──  hyosan-chat.d.ts
5
│   └──  index.d.ts
6
├──  hyosan-chat.js
7
├──  hyosan-chat.umd.cjs
8
├──  lib.d.ts
9
└──  vite.svg

我们观察一下打包后的产物:

文件	说明
`components/hyosan-chat.d.ts`	对话组件
`components/index.d.ts`	组件库中包含的组件的入口文件
`hyosan-chat.js`	`es` 打包格式产物
`hyosan-chat.umd.cjs`	`umd` 打包格式产物
`lib.d.ts`	组件库的入口文件
`vite.svg`	`vite logo`

其中 vite.svg 不应该出现在 dist 目录中, 因此我们将其删除

1
rm public/vite.svg

lib.d.ts 是组件库的入口文件的类型描述文件, 我们需要在 package.json 中声明:

1
{
2
  "types": "./dist/lib.d.ts"
3
  "exports": {
4
    ".": {
5
       "types": "./dist/lib.d.ts",
6
      "import": "./dist/hyosan-chat.js",
7
      "require": "./dist/hyosan-chat.umd.cjs"
8
    }
9
  },
10
}

dist / hyosan-chat-0.0.1.tgz 文件作为打包后的产物, 不应该提交到仓库中, 我们将其添加到 .gitignore 中:

1
dist
2
hyosan-chat-*.tgz

验证#

打包完成后, 我们需要创建一个新的 vue 项目来引入组件库进行测试:

1
pnpm create vite
2
.../1954f95e4b3-1078                     |   +1 +
3
.../1954f95e4b3-1078                     | Progress: resolved 1, reused 0, downloaded 1, added 1, done
4
│
5
◇  Project name:
6
│  vite-project
7
│
8
◇  Select a framework:
9
│  Vue
10
│
11
◇  Select a variant:
12
│  TypeScript
13
│
14
◇  Scaffolding project in /Users/xxx/projects/vite-project...
15
│
16
└  Done. Now run:
17

18
  cd vite-project
19
  pnpm install
20
  pnpm run dev

1
cd vite-project
2
pnpm i && pnpm i ./hyosan-chat/hyosan-chat-0.0.1.tgz
3
code .

我们使用 vscode 打开项目, 检查有无报错 / 引入失败 / 类型缺失等问题:

在 vscode 中打开 HelloWorrld.vue 尝试引入组件库并添加 <hyosan-chat> 组件, 发现组件可以成功引入, 也有正确的类型定义

下面我们启动项目查看页面显示是否正常:

1
pnpm run dev

页面没有显示出组件, 这里的报错(Class constructor Y cannot be invoked without 'new')是因为 vue 把它当做了 vue 组件进行了渲染, 但其实它应该被当做 自定义元素, 通过查看在 vue 中使用自定义元素, 发现应该在 vite.config.ts 中添加 isCustomElement:

1
import { defineConfig } from 'vite'
2
import vue from '@vitejs/plugin-vue'
3

4
// https://vite.dev/config/
5
export default defineConfig({
6
  plugins: [
7
    vue({
8
      template: {
9
        compilerOptions: {
10
          isCustomElement: tag => tag.includes('hyosan-')
11
        }
12
      }
13
    })
14
  ],
15
  server: {
16
    port: 35195,
17
  }
18
})

添加 isCustomElement 后, 组件渲染出来了, 但是样式没有, 这是因为我们在搭建项目引入 shoelace 时, 使用最简单的 <link> cdn URL 的方式引入了 shoelace 的样式, 在新创建的项目中并没有这个 <link>, 我们为了进行验证, 先引入 <link>, 在后续文章中我们会优化引入方式

index.html:

1
<link
2
  rel="stylesheet"
3
  media="(prefers-color-scheme:light)"
4
  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.0/cdn/themes/light.css"
5
/>
6
<link
7
  rel="stylesheet"
8
  media="(prefers-color-scheme:dark)"
9
  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.0/cdn/themes/dark.css"
10
  onload="document.documentElement.classList.add('sl-theme-dark');"
11
/>

再次查看页面, 组件正常渲染, 接下来我们测试一下 v-model 是否可用:

1
<input v-model="message" />
2
<hyosan-chat></hyosan-chat>
3
<hyosan-chat :message="message"></hyosan-chat>

1
const message = ref('message')

在 input 中修改 message, 页面中的 hyosan-chat 组件也会同步修改

看起来一切正常! 🎉 但在我们现在依然有几个需要解决的问题:

组件的样式现在依然使用的是 <link> cdn 的方式实现, 但我们的用户使用环境可能是内网, 无法访问 cdn 的资源, 因此我们需要优化引入方式, 改为 在组件库中 export shoelace 的样式
vscode 中的 HelloWorld.vue 中编写 <hyosan-chat> 时, 没有关于 hyosan-chat 组件的类型提示(props / events), 也就是 vscode 无法识别 hyosan-chat 组件的类型; 得益于 vue 对自定义组件的支持, 我们可以 生成类型定义文件对 vue GlobalComponents 进行扩展, 这里我们可以使用一些第三方库(custom-element-vuejs-integration) 来实现, 详见非 Vue Web Components 和 TypeScript
组件库没有 提供多语言支持, 虽然 shoelace 提供了本地化和语言包文件