使用 Lit 创建一个 AI 对话组件库 01 搭建篇

本篇将介绍如何使用 vite 创建并初始化一个 Lit + shoelace 项目

目录#

前言#

此系列文章仅作为项目搭建过程的记录, 可能会忽略大量细节, 并且可能中道崩殂, 仅作为学习参考;

如果你对 Lit / Web Components 有兴趣, 请查看我的另外两篇文章:

创建项目#

1
pnpm create vite
2
✔ Project name: … hyosan-chat
3
✔ Select a framework: › Lit
4
✔ Select a variant: › TypeScript
5

6
Scaffolding project in /Users/xxx/projects/hyosan-chat...
7

8
Done. Now run:
9

10
  cd hyosan-chat
11
  pnpm install
12
  pnpm run dev

TIP
在创建项目时选择 Lit & TypeScript, 下面我们先来搭建项目工程化所需的相关依赖 👇🏻

git#

1
cd my-chat
2
pnpm i # 安装依赖
3
git init # 初始化 git 仓库

biome#

biome 是一个使用 Rust 编写的 代码检查 和 格式化 工具, 相比于 eslint / prettier, 它具有更好的性能和速度, 并且 开箱即用

1
# 安装 biome
2
pnpm add --save-dev --save-exact @biomejs/biome
3
# 生成配置文件 biome.json
4
pnpm biome init

修改配置文件 biome.json:

1
{
2
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
3
  "vcs": {
4
    "enabled": true,
5
    "clientKind": "git",
6
    "useIgnoreFile": true
7
  },
8
  "files": {
9
    "ignoreUnknown": false,
10
    "ignore": []
11
  },
12
  "formatter": {
13
    "enabled": true,
14
    "indentStyle": "tab"
15
  },
16
  "organizeImports": {
17
    "enabled": true
18
  },
19
  "linter": {
20
    "enabled": true,
21
    "rules": {
22
      "recommended": true,
23
      "correctness": {
24
        "noUnknownUnit": "off"
25
      }
26
    }
27
  },
28
  "javascript": {
29
    "formatter": {
30
      "quoteStyle": "single",
31
      "semicolons": "asNeeded"
32
    }
33
  }
34
}

为了方便使用, 我们将 biome 命令加入到 package.json scripts 中:

1
{
2
  "scripts": {
3
    "lint": "biome check",
4
    "lint:fix": "biome check --write",
5
  }
6
}

这样我们就可以直接通过 pnpm run lint / pnpm run lint:fix 执行格式化了

然后安装编辑器插件, 我用的是 vscode, 直接安装 Biome VSCode 扩展, 详见在编辑器中集成Biome

然后创建 .vscode/extensions.json 文件, 添加如下内容:

1
{
2
  "recommendations": ["biomejs.biome"]
3
}

TIP
添加 .vscode/extensions.json 是为了向其他开发者推荐安装此扩展(biome 扩展)

创建 .vscode/settings.json:

1
{
2
  "editor.defaultFormatter": "biomejs.biome", // 将 biome 设置为默认格式化器
3
  "[javascript]": {
4
    "editor.defaultFormatter": "biomejs.biome"
5
  },
6
  "[typescript]": {
7
    "editor.defaultFormatter": "biomejs.biome"
8
  },
9
  "editor.formatOnSave": true,
10
  "editor.codeActionsOnSave": {
11
    "source.fixAll.biome": "always", // 保存时自动 fixed
12
    "source.organizeImports.biome": "always"
13
  }
14
}

cz-git#

参考我的另一篇文章: 🔗 使用 ChatGPT 生成 git message

git hooks 相关#

WARNING
在上一步(cz-git)已经中安装并配置了 commitlint / commitizen, 所以这里不在提及

1
pnpm install -D simple-git-hooks lint-staged

修改 package.json 文件:

1
{
2
  "simple-git-hooks": {
3
    "pre-commit": "npx lint-staged",
4
    "commit-msg": "npx commitlint --edit ${1}"
5
  },
6
  "lint-staged": {
7
    "*.{html,css,json,md,vue,js,ts,jsx,tsx}": "pnpm run lint:fix"
8
  }
9
}

1
# Update ./git/hooks
2
npx simple-git-hooks

最后, 让我们测试一下是否生效:

1
git add -A # 添加所有文件
2
pnpm run cz ai # 使用 ChatGPT 生成 git message

shoelace#

shoelace 是 web components 生态中最成熟的基础 UI 组件库, 有了它, 我们可以很方便的使用它来构建我们的对话组件

1
pnpm i @shoelace-style/shoelace

添加 demo 代码#

简单的写一个 hyosan-chat 组件, 并在 index.html 中展示

index.html:

1
<!doctype html>
2
<html lang="en">
3
  <head>
4
    <meta charset="UTF-8" />
5
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
6
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7
    <title>Vite + Lit + TS</title>
8

9
    <!-- ⚠️ 这里直接按照官方文档使用 link cdn 标签引入了样式, 用来实现 主题切换 -->
10
    <!-- ⚠️ 切换功能会在后续章节中实现, 实现方式暂未确定 -->
11

12
    <link
13
      rel="stylesheet"
14
      media="(prefers-color-scheme:light)"
15
      href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.0/cdn/themes/light.css"
16
    />
17
    <link
18
      rel="stylesheet"
19
      media="(prefers-color-scheme:dark)"
20
      href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.0/cdn/themes/dark.css"
21
      onload="document.documentElement.classList.add('sl-theme-dark');"
22
    />
23

24
    <link rel="stylesheet" href="./src/index.css" />
25
    <script type="module" src="/src/main.ts"></script>
26
  </head>
27
  <body>
28
    <div class="demo-container">
29
      <hyosan-chat></hyosan-chat>
30
    </div>
31
  </body>
32
</html>

TIP
在代码中我们使用了最简单的 <link> 方式来引入 shoelace 样式, 在后续章节中我们会将其改为其他方式引入

src/main.ts:

1
import '@shoelace-style/shoelace/dist/themes/light.css'
2
export * from "./components";

index.css:

1
html, body, h1, h2, h3, h4, p { padding: 0; margin: 0; }
2
.demo-container {
3
  width: 100wh;
4
  height: 100vh;
5
  display: flex;
6
}

index.html 是我们用来展示组件的 demo 页面, 这里修改了一下样式, 使得组件的容器元素 .demo-container 宽高 100%, 并消除了浏览器默认的 padding 和 margin 样式

增加 vite.config.ts 用于指定端口号(多个 vite 项目共用端口号会造成浏览器缓存更新带来的各种问题):

1
import { defineConfig } from 'vite'
2
import { resolve } from 'node:path'
3

4
export default defineConfig({
5
  server: {
6
    port: 29510,
7
  },
8
  preview: {
9
    port: 29511,
10
  },
11
  resolve: {
12
    alias: {
13
      '@': resolve(__dirname, 'src'),
14
    },
15
  },
16
})

src/components/index.ts:

1
export { HyosanChat } from "./hyosan-chat";

src/components/hyosan-chat.ts:

1
import { LitElement, css, html } from "lit";
2
import { customElement, property } from "lit/decorators.js";
3
import '@shoelace-style/shoelace/dist/components/button/button.js'
4

5
@customElement("hyosan-chat")
6
export class HyosanChat extends LitElement {
7
  static styles? = css`
8
    :host {
9
      width: 100%;
10
      height: 100%;
11
    }
12
  `;
13

14
  @property({ reflect: true })
15
  message = "Hello Lit";
16

17
  render() {
18
    return html`
19
      <h2>HyosanChat Component</h2>
20
      <div>Hello Lit!</div>
21
      <sl-button variant="primary">Hello Shoelace</sl-button>
22
    `;
23
  }
24
}
25

26
declare global {
27
  interface HTMLElementTagNameMap {
28
    "hyosan-chat": HyosanChat;
29
  }
30
}

README.md#

最后我们新增 README.md, 用来描述我们的组件库:

1
# hyosan-chat
2
> 🚧 Work in Progress | 此项目处于早期开发阶段
3
>
4
> hyosan-chat is currently in active development and not usable for production yet.
5

6
## 介绍
7
这是一个使用 [Lit@3](https://lit.dev) & [shoelace](https://shoelace.style/) 创建一个 `AI` 对话组件库
8

9
## 技术栈
10
- [Lit@^3.2.1](https://lit.dev): `Web Component` 库
11
- [shoelace@^2.20.0](https://shoelace.style/): 使用 `Web Components` 实现的 `UI` 组件库
12
- [vite@^6.1.0](https://github.com/vitejs/vite): 现代化的前端构建工具

TIP
README.md 文件非常重要, 他是开发者了解整个项目的重要入口

编辑器自动补全插件#

这里我是用的是通义灵码, copilot 也是不错的选择

目录#

前言#

创建项目#

git#

biome#

cz-git#

git hooks 相关#

shoelace#

添加 demo 代码#

README.md#

编辑器自动补全插件#

参考#