从 CHANGELOG 读懂 lit-starter-jsLit 3 起始模板的工程化实践与版本演进路线【免费下载链接】litLit is a simple library for building fast, lightweight web components.项目地址: https://gitcode.com/GitHub_Trending/li/litlit/lit-starter-js是 Lit 官方仓库中面向 JavaScript 开发者的 Web Component 起始模板包其 CHANGELOG.md 完整记录了该模板从 1.0.0 到 2.0.2 的演进过程。本文以这份变更日志为骨架结合仓库内my-element.js、rollup.config.js、web-test-runner.config.js等真实源码逐版本解读其中的关键工程决策——从放弃 IE11、引入MODEdev/prod双模式、统一打包压缩链路到测试与文档自动化。读完本文你将理解 Lit 起始模板的构建、测试、文档生成整套工程实践并能据此评估自己的 Lit 项目在升级时需要注意的变更点。一、包定位lit-starter-js 在 Lit 生态中的角色packages/lit-starter-js是一个private: true的示例模板包其package.json中name为lit/lit-starter-js、version为2.0.2description为 A simple web component。它并不是一个发布到 npm 供生产使用的库而是由npm create类脚手架生成的起始项目模板——你可以把它复制出来作为自己组件库的起点。模板的核心组件定义在 my-element.jsimport {LitElement, html, css} from lit; export class MyElement extends LitElement { static get styles() { return css :host { display: block; border: solid 1px gray; padding: 16px; max-width: 800px; } ; } static get properties() { return { name: {type: String}, count: {type: Number}, }; } constructor() { super(); this.name World; this.count 0; } render() { return html h1${this.sayHello(this.name)}!/h1 button click${this._onClick} partbutton Click Count: ${this.count} /button slot/slot ; } _onClick() { this.count; this.dispatchEvent(new CustomEvent(count-changed)); } sayHello(name) { return Hello, ${name}; } } window.customElements.define(my-element, MyElement);这份源码演示了 LitElement 的四个核心能力css标签定义的 Shadow DOM 样式:host、padding等、properties声明的响应式属性name/count、render()中的声明式模板事件绑定click、partbutton暴露给外部样式、slot投影、以及通过CustomEvent(count-changed)对外通信。模板依赖lit^3.2.0对应 Lit 3.x 版本线。二、2.0 大版本从 Lit 2 到 Lit 3 的迁移信号CHANGELOG 的 2.0.0 条目标记为Major Changes其中明确列出的破坏性变更有Drop IE11 supportPR #3756Lit 3.0 彻底移除对 IE11 的支持这也是 2.0.0 大版本最核心的破坏性变更依赖同步升级为lit3.0.0。结合模板 README.md 中 About this release 一节Lit 3.0 相对 2.0 的破坏性变更很少总共三点放弃 IE11以 ES2021 标准发布产物移除少量已废弃的 Lit 1.x API。README 还给出了一个实用的兼容性结论绝大多数用户从 Lit 2 升级到 Lit 3 不需要改动代码应用或库可以同时兼容两个大版本例如把依赖范围写成^2.7.0 || ^3.0.0且 Lit 2.x 与 3.x 是互操作的——模板、基类、指令、装饰器可以跨版本混用。对模板使用者的直接含义如果你还在维护需要支持 IE11 的旧项目应停留在 lit-starter-js 1.x 线如果你的目标浏览器是现代浏览器支持 ES2021 模块、attachShadow、getRootNode可以放心升级到 2.x 模板因为它已经围绕现代浏览器的能力设计。三、MODEdev/prod 双模式机制模板的调试开关CHANGELOG 的 1.0.0 条目记录了一项重要功能Added Lit dev mode to test and serve commands, controlled via the MODEdev or MODEprod environment variables.这一机制在两个配置文件中都有落地实现。3.1 开发服务器端的实现web-dev-server.config.js 中通过MODE环境变量控制nodeResolve的导出条件const mode process.env.MODE || dev; if (![dev, prod].includes(mode)) { throw new Error(MODE must be dev or prod, was ${mode}); } export default { nodeResolve: {exportConditions: mode dev ? [development] : []}, preserveSymlinks: true, plugins: [ legacyPlugin({ polyfills: { // Manually imported in index.html file webcomponents: false, }, }), ], };当MODEdev时exportConditions包含development会解析到 Lit 的开发构建产物带更详细的报错信息当MODEprod时为空数组解析到生产构建产物。注意MODE默认值为dev且只接受dev/prod两个取值传其他值会直接抛错——这是模板内置的防呆校验。3.2 测试端的实现web-test-runner.config.js 中使用了完全相同的模式约定const mode process.env.MODE || dev; if (![dev, prod].includes(mode)) { throw new Error(MODE must be dev or prod, was ${mode}); } // ... export default { rootDir: ., files: [./test/**/*_test.js], nodeResolve: {exportConditions: mode dev ? [development] : []}, preserveSymlinks: true, browsers: commandLineBrowsers ?? Object.values(browsers), testFramework: { config: { ui: tdd, timeout: 60000, }, }, plugins: [ legacyPlugin({ polyfills: { webcomponents: true, custom: [ { name: lit-polyfill-support, path: node_modules/lit/polyfill-support.js, test: !(attachShadow in Element.prototype) || !(getRootNode in Element.prototype) || window.ShadyDOM window.ShadyDOM.force, module: false, }, ], }, }), ], };除了同样受MODE控制的双模式解析外该配置还包含几个值得注意的细节默认通过 Playwright 启动chromium、firefox、webkit三个浏览器运行测试也可以通过BROWSERSchromium,firefox npm run test指定子集配置文件中还预留了 Sauce Labs 与 BrowserStack 云端测试的注释示例legacyPlugin会在不支持 Web Component 的旧浏览器上注入webcomponentspolyfill并额外注入 Lit 的polyfill-support模块路径为node_modules/lit/polyfill-support.js这是 Lit 与 webcomponents polyfill 协同工作的必要胶水层测试框架使用 Mocha 的 TDD 风格ui: tdd超时 60 秒。3.3 对应的 npm scriptspackage.json 中的脚本完整体现了双模式设计serve: wds --watch, serve:prod: MODEprod npm run serve, test: npm run test:dev npm run test:prod, test:dev: wtr, test:watch: wtr --watch, test:prod: MODEprod wtr, test:prod:watch: MODEprod wtr --watchnpm test会先跑 dev 模式测试、再跑 prod 模式测试保证代码在两种构建下行为一致npm run serve默认 dev 模式npm run serve:prod切换为生产模式npm test:watch在每次源码变更时以 dev 模式重跑测试。与之配套根目录的 index.html 提供了指向/dev/index.html组件示例的入口链接而 dev/index.html 演示了如何在浏览器中加载组件——手动引入webcomponents-loader.js与lit/polyfill-support.js再以script typemodule方式加载my-element.js。四、打包与压缩从 Terser 依赖更新看构建链路CHANGELOG 中有多条与打包相关的条目1.0.3更新 Rollup 及 Rollup 插件1.0.5更新rollup/plugin-replace1.0.6Improve bundling and minification recommendations改进打包与压缩建议2.0.2更新 Rollup 与 Terser 依赖。这些变更的实际落点就是 rollup.config.jsimport summary from rollup-plugin-summary; import {terser} from rollup-plugin-terser; import resolve from rollup/plugin-node-resolve; import replace from rollup/plugin-replace; export default { input: my-element.js, output: { file: my-element.bundled.js, format: esm, }, onwarn(warning) { if (warning.code ! THIS_IS_UNDEFINED) { console.error((!) ${warning.message}); } }, plugins: [ replace({preventAssignment: false, Reflect.decorate: undefined}), resolve(), terser({ ecma: 2021, module: true, warnings: true, mangle: { properties: { regex: /^__/, }, }, }), summary(), ], };配置要点解读replace插件把Reflect.decorate替换为undefined——这是针对装饰器相关的代码路径优化避免保留未使用的运行时逻辑terser以ecma: 2021为压缩目标module: true开启 ES module 友好的压缩mangle.properties.regex: /^__/只混淆以双下划线开头的私有属性名summary插件在构建结束后输出产物大小摘要方便观察打包体积。重要前提该 Rollup 配置仅为静态文档站点生成打包产物并不用于发布到 npm。模板 README 的 Bundling and minification 一节明确建议把组件以未优化的 ES module 形式发布在应用层做构建期优化这样构建工具才能最大化地去重、去除死代码。这是 1.0.6 版本改进打包与压缩建议的核心内容——模板刻意把发布组件与构建应用两种场景分开处理。package.json中还提供了checksize脚本用于快速评估产物体积checksize: rollup -c ; cat my-element.bundled.js | gzip -9 | wc -c ; rm my-element.bundled.js该脚本先执行 Rollup 打包再对产物做 gzip 压缩并输出字节数最后清理临时文件。五、测试体系从 open-wc 测试套件到多浏览器验证CHANGELOG 1.0.0 条目还记录了模板测试体系的确立使用 open-wc analyzer 生成custom-elements.json并把模板内置的 API 文档生成器更新为新清单格式。测试本身则基于open-wc/testing与web/test-runner。test/my-element_test.js 覆盖了组件的四个核心行为import {MyElement} from ../my-element.js; import {fixture, assert} from open-wc/testing; import {html} from lit/static-html.js; suite(my-element, () { test(is defined, () { const el document.createElement(my-element); assert.instanceOf(el, MyElement); }); test(renders with default values, async () { const el await fixture(htmlmy-element/my-element); assert.shadowDom.equal(el, h1Hello, World!/h1 button partbuttonClick Count: 0/button slot/slot ); }); test(renders with a set name, async () { const el await fixture(htmlmy-element nameTest/my-element); assert.shadowDom.equal(el, h1Hello, Test!/h1 button partbuttonClick Count: 0/button slot/slot ); }); test(handles a click, async () { const el await fixture(htmlmy-element/my-element); const button el.shadowRoot.querySelector(button); button.click(); await el.updateComplete; assert.shadowDom.equal(el, h1Hello, World!/h1 button partbuttonClick Count: 1/button slot/slot ); }); test(styling applied, async () { const el await fixture(htmlmy-element/my-element); await el.updateComplete; assert.equal(getComputedStyle(el).paddingTop, 16px); }); });这套测试验证了元素注册成功、默认渲染Hello, World!与计数 0、属性驱动的渲染nameTest输出Hello, Test!、交互后的响应式更新点击后计数变为 1且通过await el.updateComplete等待更新完成、以及 Shadow DOM 样式的实际生效paddingTop为 16px。六、文档与自定义元素清单Eleventy custom-elements.json 链路CHANGELOG 1.0.0 的另一项变更是把模板的 API 文档生成切换到新的清单格式具体链路如下分析package.json中的analyze脚本执行cem analyze --litelement --globs **/*.js --exclude docs基于 Custom Elements Manifest Analyzer 扫描 JS 源码并生成custom-elements.jsonpackage.json中customElements: custom-elements.json字段指向该清单文档源站点的 Markdown 页面位于 docs-src 目录index.md、install.md、examples/等模板与页面布局在_includes/下生成docs:build脚本rollup -c --file docs/my-element.bundled.js打包组件示例docs:gen脚本通过 Eleventy.eleventy.cjs把 Markdown 渲染为静态站点输出到docs/目录预览docs:serve使用wds --root-dirdocs --node-resolve --watch本地预览文档站点。值得留意的是模板把生成的docs/目录直接提交进仓库从而可以配合 GitHub Pages 的 main branch /docs folder 发布源设置直接托管文档站点——README 的 Static Site 一节对此有完整说明。七、1.x 时代的工程细节serve 修复与安全维护CHANGELOG 低版本条目中还有两个容易被忽视但影响日常使用的变更1.0.1修复npm run serve使其正确服务根目录并在根目录/添加指向/dev/index.html组件示例的链接。对应到仓库中就是根目录 index.html 里的a href/dev/index.htmlComponent Demo/a同时依赖lit2.1.0。1.0.2更新 README说明 issue 与 PR 应提交到 Lit 主仓库——这也是本文所依据的 CHANGELOG.md 本身位于packages/lit-starter-js/而非独立仓库的原因。2.0.1Minor security fixes小幅安全修复。这提醒模板使用者即使是示例性质的模板也应跟随其安全修复更新。1.0.4更新依赖并移除未使用的依赖说明模板维护者会持续清理依赖保持模板的最小化。八、版本演进对照与升级建议综合 CHANGELOG可以把 lit-starter-js 的演进总结为两条主线版本变更性质关键内容1.0.0功能确立引入MODEdev/prod、open-wc analyzer 生成custom-elements.json、升级 TypeScript 4.4.2、依赖lit2.0.01.0.1修复npm run serve服务根目录、根页面链接组件示例1.0.2~1.0.5维护README 归属说明、依赖清理、Rollup 插件更新1.0.6文档改进强化发布组件 vs 应用构建的打包压缩建议2.0.0破坏性变更放弃 IE11、升级 TypeScript 5.x、依赖lit3.0.02.0.1安全修复小幅安全修复2.0.2维护更新 Rollup 与 Terser 依赖、依赖lit3.2.0对模板使用者的三条实操建议升级前先确认浏览器目标2.x 模板放弃 IE11 且以 ES2021 为压缩目标若仍须支持旧浏览器请锁定 1.x 版本线善用双模式验证保持npm testdevprod 两次测试作为默认质量门禁避免只在开发构建下通过测试而生产构建出错不要把模板的 Rollup 配置当作发布配置发布组件应输出未优化的 ES module应用构建期的压缩去重交给应用自己的构建链完成——这正是 CHANGELOG 1.0.6 版本想传达的核心建议。九、延伸阅读模板源码与入口my-element.js、index.html构建与配置package.json、rollup.config.js、web-test-runner.config.js、web-dev-server.config.js测试用例test/my_element_test.js组件演示页dev/index.html文档站点源文件docs-src 目录TypeScript 版本模板packages/lit-starter-ts/CHANGELOG.md其 2.0.3 条目显示 TypeScript 依赖升级至 5.8 并同步了ariaColIndexText等 ARIAMixin 类型变更可作为 TS 用户对照参考【免费下载链接】litLit is a simple library for building fast, lightweight web components.项目地址: https://gitcode.com/GitHub_Trending/li/lit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考