Lightweight Charts 插件脚手架 create-lwc-plugin 的本地开发与发布实战指南

Lightweight Charts 插件脚手架 create-lwc-plugin 的本地开发与发布实战指南【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址: https://gitcode.com/gh_mirrors/li/lightweight-chartscreate-lwc-plugin是 TradingView Lightweight Charts™ 官方提供的向导式CLI 脚手架工具用于从零生成可直接运行、可直接发布到 npm 的插件项目。本篇技术指南以仓库中 BUILDING.md 为骨架完整讲解如何在本地环境迭代开发该 CLI 本身、如何以普通项目与仓库 workspace 两种模式运行它以及如何为它发布新版本同时结合仓库源码逐层拆解其向导问题、模板替换机制与包发布清单帮助你既能跑通全流程也能理解每一步背后的实现原理。开发环境要求与前置准备BUILDING.md 明确指出开发 create-lwc-plugin 所支持的最低 Node.js 版本为22.3这与整个 lightweight-charts 仓库的开发基线一致。该版本要求由工具链决定——CLI 源码src/index.ts使用了AbortSignal.timeout、String.prototype.replaceAll等现代 API且构建层依赖 unbuild 3.x因此请确保本地 Node 版本不低于 22.3。仓库是一个pnpm workspace根目录存在 pnpm-workspace.yaml因此依赖安装可以直接在仓库根目录执行pnpm install这一步会安装整个 monorepo 的依赖包括 create-lwc-plugin 包自身的依赖clack/prompts、picocolors、unbuild等见 package.json 的 devDependencies。本地开发三步走构建 stub 并运行 CLIBUILDING.md 给出了核心的本地开发工作流共三步1. 安装依赖pnpm install2. 创建开发 stubpnpm dev该命令在 package.json 中定义为dev: unbuild --stub echo now run node index.js从源码可以确认unbuild --stub会为src/index.ts生成指向源码的 stub 产物因此后续通过node index.js运行时修改src/下的 TypeScript 源码会即时生效无需每次重新编译——这正是开发 stub的含义。它同时解决了 CLI 内部通过import.meta.url定位模板目录scaffold.ts 的templatePath函数的路径问题。3. 运行 CLInode index.js重要前提请在一个空白scratch目录中运行它——CLI 会直接向当前工作目录脚手架新项目。这一点在源码中有明确体现index.ts 中const cwd process.cwd()随后baseDir workspaceRoot ?? cwd第 92 行即非 workspace 模式下目标目录以当前目录为基准。运行后会进入交互式向导依次询问插件类型、名称、描述、包名、类名、作者、许可证、最低支持的 lightweight-charts 版本、目录 tags 等问题详见下文向导问题解析最后在你确认后生成完整项目。Workspace 模式在仓库内生成官方插件除了面向外部开发者的普通项目模式CLI 还支持workspace 模式用于维护者在 lightweight-charts 仓库内部直接脚手架一个官方插件包node packages/create-lwc-plugin/index.js --workspaceBUILDING.md 特别强调该模式有两个约束必须在仓库内部运行CLI 通过向上逐级查找pnpm-workspace.yaml来确定仓库根目录index.ts 的findWorkspaceRootWORKSPACE_MARKER pnpm-workspace.yaml找不到会直接cancel并以退出码 1 结束。脚手架输出到packages/目录workspace 包相对仓库根目录放置例如默认路径为packages/package-namequestions.ts。与普通模式相比workspace 模式会生成差异化的包包名强制限定tradingview/scopequestions.ts对库与共享工具使用workspace:*依赖scaffold.ts额外生成CHANGELOG.md、LICENSE、NOTICE在lwcPlugin元数据中标记origin: official表示官方目录条目scaffold.ts。测试后清理BUILDING.md 提醒如果只是测试 workspace 模式记得删除生成的脚手架包如果运行过安装还要恢复pnpm-lock.yaml。由于 workspace 包声明了workspace:*依赖pnpm install会把新包写入 lockfile。向导机制源码解析为了让本地开发更有把握理解 CLI 的交互流程很有必要。整个流程在 questions.ts 中实现基于clack/prompts构建第一步插件类型选择questions.ts。三种类型类型选项值适用场景对应模板目录Series Primitiveseries-primitive附着在某个 series 上可绘制到图表任意位置、价格轴与时间轴适合数据相关的自定义可视化、绘图工具与标注template-series-primitivePane Primitivepane-primitive附着在 pane窗格而非 series 上适合标题、徽章、图例、水印等窗格级装饰template-pane-primitiveCustom Seriescustom-series定义一种全新的 series 类型自行绘制 series 的数据点template-seriescategoryTemplates映射questions.ts正是生成阶段选择模板目录的依据。向导还提供 Help me decide 帮助分支并在多数情况下建议优先选择 primitive除非你明确要创建一种新 series。第二步常规问题questions.ts插件名称必填如 My Custom Series一句话描述必填将展示在 npm 与插件注册中心卡片上包名默认由名称派生为lwc-plugin-nametoValidPackageName会把空格替换为连字符并转小写见 validation.tsworkspace 模式强制要求tradingview/前缀两种模式都要求以lwc-plugin-开头且是合法的 npm 包名类名默认把名称中的非字母数字字符去掉并大写首字母校验规则包括不得含空格/连字符、不得以数字开头、必须以大写字母开头作者与许可证普通模式可选许可证提供 MIT / Apache-2.0 / ISC / 留空四选一workspace 模式固定为 TradingView 与 Apache-2.0最低支持的 Lightweight Charts 版本默认值通过 lwc-version.ts 实时查询 npm registry 上lightweight-charts/latest得到3 秒超时失败回退到FALLBACK_VERSION 5.2.1最终以^version形式写入 peerDependencies注册中心 tags逗号分隔写入lwcPlugin.tags是否包含提示注释includeHints决定生成的源码中//*开头的提示性注释是否保留scaffold.ts目标文件夹路径普通模式默认使用当前目录留空workspace 模式默认为packages/name且要求文件夹为空或不存在。此外在普通模式下向导会最先询问是否为 AI 编码助手Claude Code、Codex、Cursor 等安装插件开发 Agent Skillquestions.ts 的askSkillInstall。选择 继续 则 skill 会在脚手架完成后安装进新项目选择 退出并交给助手 则 skill 安装到当前目录、向导立即停止把后续工作交给你的 AI 助手对应 index.ts 的handOverToAssistant。skill 的安装命令也可随时手动执行npx skills add tradingview/lightweight-charts --skill lightweight-charts-plugin-authoring生成阶段模板替换与文件装配确认所有回答后CLI 进入生成阶段scaffold.ts按categoryTemplates选择类型模板目录同时复制公共模板template-common执行有序的占位符替换替换顺序经过设计README 代码片段_ATTACH_SNIPPET_、_USAGE_SNIPPET_等最先注入因为它们内部还包含_CLASSNAME_、_PACKAGENAME_、_ENTRYNAME_等占位符需要被后续替换再次解析替换函数而非字符串是为了防止回答内容中的$等字符被当作替换模式处理对 JSON 文件使用 JSON 字符串转义替换器保证回答中的引号、反斜杠不会破坏package.json的可解析性_gitignore重命名为.gitignore入口文件src/template-entry.ts重命名为entry-name.tsentry name 为去掉 scope 与lwc-plugin-前缀的包名如heatmap-seriesworkspace 模式额外复制template-workspace内容并追加.gitignore条目因为 prepack 脚本会把仓库根 LICENSE 复制进包内见 scaffold.ts。生成的项目结构以 custom series 为例见 template-series/src包含data.ts、options.ts、renderer.ts、sample-data.ts与src/example/演示页面。生成的package.json采用 ES moduletype: module通过exports暴露包入口与./standalone子路径并携带lwcPlugin元数据块title、category、origin、demo、tags等这正是 Lightweight Charts 插件注册中心读取的约定格式模板见 template-common/package.json。发布新版本完整流程与检查清单BUILDING.md 的第二大部分是发布流程这是维护者迭代该 CLI 的关键操作路径1. 安装依赖pnpm install2. 升级版本号在 package.json 中修改version字段当前仓库内版本为0.2.0。3. 构建包pnpm prepublishOnly该脚本在 package.json 中定义为prepublishOnly: pnpm build即触发unbuild构建。npm publish会自动执行prepublishOnly钩子但这里显式运行可以提前暴露构建问题。4. 校验发布清单pnpm dlx publintlatest确保生成的package.json不存在问题。publint 会检查exports、files、types、bin等字段是否符合 npm 发布规范。5. 发布到 npmnpm publish提示在发布命令末尾追加--dry-run可以先查看发布结果而不实际把包上传到 npmnpm publish --dry-run发布边界说明files白名单package.json只包含index.js、各template-*模板目录、dist与CHANGELOG.md——模板目录是运行时脚手架的数据源必须随包发布bin字段把create-lwc-plugin命令映射到index.js这是npm create lwc-plugin/pnpm create lwc-plugin/yarn create lwc-plugin能直接调用的入口engines声明node: ^18.0.0 || 20.0.0注意这与仓库开发基线22.3不同前者是 CLI 作为 npm 包被外部用户消费时的运行下限后者是仓库内开发环境的推荐版本如果你发布到 npm 后希望插件出现在 Lightweight Charts 插件注册中心生成的插件项目本身也要按 README.md 的指引构建npm run build产出name.js、name.standalone.js、name.d.ts三个文件并发布其lwcPlugin元数据正是目录收录的依据。常见问题与调试要点结合源码与文档梳理本地开发中容易踩坑的点运行目录错误普通模式向当前目录脚手架务必在空白目录中运行node index.js否则会触发文件夹已存在且非空的校验questions.ts 的dirExists/isEmpty检查workspace 模式定位失败--workspace必须在包含pnpm-workspace.yaml的仓库目录树内执行否则直接退出码 1修改源码不生效确认先运行过pnpm devunbuild --stubstub 指向源码改完即生效发布前清单不完整用publint--dry-run双重检查确认模板目录与dist都在发布包内测试后残留workspace 模式测试产生的packages/name与 lockfile 变更需要清理恢复避免污染仓库。总结create-lwc-plugin 的本地开发与发布流程虽然简短却是一条贯穿向导交互 → 模板装配 → 包发布的完整工具链pnpm dev借助 unbuild stub 打通 TypeScript 源码到可运行 CLI 的即时反馈--workspace模式复用pnpm-workspace.yaml定位仓库根并生成符合官方目录规范的包而prepublishOnlypublintnpm publish --dry-run则构成发布前的质量闸门。理解 src/index.ts、src/questions.ts、src/scaffold.ts 三份核心源码你就能在修改向导问题、调整模板占位符、扩展发布元数据时游刃有余。【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考