maintain-custom-addons-dev-watch

Maintain Custom Add-ons In Dev Watch

用途

该技能面向本地 add-on 编写工作流：在编写自定义 add-on 或模板时，持续编译并把包输出同步到目标应用中，便于即时验证效果。

主要能力

• 初始化自定义 add-on
• 编译 add-on 输出
• 运行 add-on 开发循环，在编辑源文件时保持同步
• 将受监视的框架目录同步到沙箱目标应用
• 在修改元数据后重新编译并应用 add-on

使用方式

初始化与编译：

npx @tanstack/cli add-on init
npx @tanstack/cli add-on compile

在编辑源文件时运行 add-on 开发循环：

npx @tanstack/cli add-on dev

将受监视的框架目录同步到沙箱目标应用（--dev-watch 是 create 的选项，而不是 dev 的选项）：

npx @tanstack/cli create my-sandbox --dev-watch ../path/to/framework-dir

当修改元数据后，先重新编译再应用：

npx @tanstack/cli add-on compile
npx @tanstack/cli add my-custom-addon

常见错误

1. 不要将 --dev-watch 与 --no-install 一起使用。错误示例：npx @tanstack/cli create my-sandbox --dev-watch ../my-addon-package --no-install。正确示例：npx @tanstack/cli create my-sandbox --dev-watch ../my-addon-package。dev-watch 会拒绝 --no-install，导致自动化循环在同步工作开始前就失败。
2. 不要在无效的框架目录上启动 dev-watch。错误示例：npx @tanstack/cli create my-sandbox --dev-watch ../missing-or-invalid-dir。正确示例：npx @tanstack/cli create my-sandbox --dev-watch ../valid-framework-dir。监视设置会校验路径存在、是目录，并至少包含 add-ons/、assets/ 或 framework.json 之一；无效目标会在文件同步开始前失败。
3. 不要在 code-router 项目中进行 add-on 编写。应从 file-router 项目运行 npx @tanstack/cli add-on init。自定义 add-on 编写期望 file-router 模式，从不兼容的项目模式运行时会退出。
4. 不要在没有脚手架元数据的情况下运行 add-on 工作流。应在由 TanStack CLI 脚手架生成的项目（包含 .cta.json）中运行 npx @tanstack/cli add-on dev。自定义 add-on 流程依赖持久化的脚手架选项，缺少元数据会阻塞初始化与更新路径。

适用场景

• 开发并迭代自定义 TanStack add-on 或模板
• 需要把本地框架目录实时同步到沙箱应用进行验证

限制

• 需在 TanStack CLI 脚手架生成且包含 .cta.json 的项目中运行
• 项目需为 file-router 模式
• --dev-watch 不能与 --no-install 同时使用
• 监视目标目录必须存在、是目录，并至少包含 add-ons/、assets/ 或 framework.json 之一
• 该领域的模式与 add-addons-existing-app 存在冲突：工具假设可复用自动化，但遗留支持带来的隐藏元数据前置条件使 add-on 循环跨仓库难以移植