SDK CLI 参考

SDK CLI 参考

termii-plugin-sdk 是 @termii/plugin-sdk 附带的 esbuild 打包脚手架 （bin.termii-plugin-sdk）。用法说明见 SDK 与打包脚手架。

命令

termii-plugin-sdk build <entry> --outfile <out> [选项]
termii-plugin-sdk --help | -h | help

选项

选项	说明
--outfile <path>	产物文件路径（单文件 ES module）；必填
--minify	压缩产物
--external <name>	将指定包 external 化（不打包、不 alias 到 shim）；可重复传
--help / -h / help	显示帮助

默认行为

• bundle + --format=esm：产物是单文件 ES module，宿主可直接加载。
• .js 文件按 JSX 解析（--loader:.js=jsx）。
• 共享包 alias 到 shims：react / react/jsx-runtime / react-dom / lucide-react 会 alias 到 SDK 包的 shims/，运行时从 window.__termii.shared 取宿主共享实例——不要自己 npm 安装 react / lucide-react，否则每个插件都会各自打包一份 React（上下文 冲突、体积膨胀）。
• SDK alias 到源码：@termii/plugin-sdk 会 alias 到 SDK 包的 src/index.ts（definePlugin / validateManifest / 宿主 API 类型 直接随插件 bundle，无需插件自建本地链接）。
• external 覆盖：对某个包传入对应的 --external（如 --external react --external lucide-react）则改为 external 处理， --external @termii/plugin-sdk 同理。
• esbuild 定位：优先插件仓库根 node_modules，回退 require.resolve；找不到时给出友好报错（先在插件项目 npm install）。

示例

# 入门模板的构建脚本等价命令
npx termii-plugin-sdk build src/main.jsx --outfile main.js --minify

# 共享包改回 external（例如插件自带 React 的罕见场景）
npx termii-plugin-sdk build src/main.jsx --outfile main.js \
  --minify --external react --external lucide-react

# 官方插件构建（TS 入口，产物写入插件目录根）
npx termii-plugin-sdk build plugins/official/termii-docker/src/index.ts \
  --outfile plugins/official/termii-docker/main.js --minify

共享运行时（window.__termii.shared）

宿主启动时在 window.__termii.shared 上暴露共享实例（React / ReactDOM / lucide）。shims 只是薄封装：import React from "react" 在 打包后变成从共享实例取，插件与宿主共用同一个 React 上下文。

i18next / react-i18next 不提供 shim：需要时插件自己 npm i i18next 并随 esbuild 打进 bundle（官方插件 termii-docker 的 src/i18n.ts 即此模式）。