目录#

1. 使用 Lit 创建一个 AI 对话组件库 01 搭建篇
2. 使用 Lit 创建一个 AI 对话组件库 02 Prompts 篇
3. 使用 Lit 创建一个 AI 对话组件库 03 可行性验证 篇
4. 使用 Lit 创建一个 AI 对话组件库 04 国际化 篇

为什么要验证可行性#

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

打包#

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

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

{
	"compilerOptions": {
    // ...
+		"declaration": true,
+		"outDir": "dist",
  }
}

export * from './components'

+ import dts from 'vite-plugin-dts'

export default defineConfig({
  // ...
+ 	plugins: [
+ 		// 用于生成 `d.ts` 文件, refer https://github.com/qmhc/vite-plugin-dts/blob/HEAD/README.zh-CN.md
+ 		dts({ tsconfigPath: './tsconfig.lib.json' })
+ 	],
+ 	build: {
+ 		lib: {
+ 			name: 'hyosan-chat',
+ 			entry: ['src/lib.ts'],
+ 			fileName: 'hyosan-chat',
+ 		},
+ 	},
})

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

{
+	 "description": "A library of web components for AI conversations based on lit and shoelace",
+	 "keywords": ["hyosan-chat", "Lit", "Shoelace", "AI", "chat", "Web Components", "web chat"],
+	 "author": {
+	  	"name": "Ryan"
+	 },
+	 "license": "MIT",
-	 "version": "0.0.0",
+	 "version": "0.0.1",
-  "private": true,
+ 	"files": [
+ 		"dist"
+ 	],
+ 	"main": "./dist/hyosan-chat.umd.cjs",
+ 	"module": "./dist/hyosan-chat.js",
+ 	"exports": {
+ 		".": {
+ 			"import": "./dist/hyosan-chat.js",
+ 			"require": "./dist/hyosan-chat.umd.cjs"
+ 		}
+ 	},
	"scripts": {
+		"build:pack": "pnpm run build && pnpm pack",
  },
}

# 打包
pnpm run build

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

lsd --tree dist/
 dist
├──  components
│   ├──  hyosan-chat.d.ts
│   └──  index.d.ts
├──  hyosan-chat.js
├──  hyosan-chat.umd.cjs
├──  lib.d.ts
└──  vite.svg

rm public/vite.svg

{
+  "types": "./dist/lib.d.ts"
	"exports": {
		".": {
+ 			"types": "./dist/lib.d.ts",
			"import": "./dist/hyosan-chat.js",
			"require": "./dist/hyosan-chat.umd.cjs"
		}
	},
}

+dist
+hyosan-chat-*.tgz

验证#

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

pnpm create vite
.../1954f95e4b3-1078                     |   +1 +
.../1954f95e4b3-1078                     | Progress: resolved 1, reused 0, downloaded 1, added 1, done
│
◇  Project name:
│  vite-project
│
◇  Select a framework:
│  Vue
│
◇  Select a variant:
│  TypeScript
│
◇  Scaffolding project in /Users/xxx/projects/vite-project...
│
└  Done. Now run:

  cd vite-project
  pnpm install
  pnpm run dev

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

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

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

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

pnpm run dev

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

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

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: tag => tag.includes('hyosan-')
        }
      }
    })
  ],
  server: {
    port: 35195,
  }
})

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

index.html:

+    <link
+      rel="stylesheet"
+      media="(prefers-color-scheme:light)"
+      href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.0/cdn/themes/light.css"
+    />
+    <link
+      rel="stylesheet"
+      media="(prefers-color-scheme:dark)"
+      href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.0/cdn/themes/dark.css"
+      onload="document.documentElement.classList.add('sl-theme-dark');"
+    />

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

+  <input v-model="message" />
-  <hyosan-chat></hyosan-chat>
+  <hyosan-chat :message="message"></hyosan-chat>

+ 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 提供了 本地化 和 语言包文件

这些问题我们将在后续章节中一一解决

参考#

• 库模式 - vite
• vite-plugin-dts
• 在 vue 中使用自定义元素
• 非 Vue Web Components 和 TypeScript
• custom-element-vuejs-integration