mcpField
E
experience-ui-bundle-custom-app-generate

experience-ui-bundle-custom-app-generate

github.com/forcedotcom开发1.1k5.2k 次安装1 天前更新
代码仓库

关于 experience-ui-bundle-custom-app-generate

该 Skill 为 Salesforce React UI Bundle 生成 Lightning Experience 自定义应用元数据，面向需要向内部用户提供应用入口的开发者。它根据目标组织的 API 版本确定 Bundle 引用字段，并修改现有 Bundle 元数据以匹配托管目标。

主要功能

  1. 01生成 CustomApplication 元数据
  2. 02解析应用名称、命名空间与标签
  3. 03查询 API 版本支持的字段
  4. 04更新现有 UI Bundle 元数据
  5. 05验证部署配置

适用场景

  1. 01在 Lightning App Launcher 中提供应用入口
  2. 02将 React UI Bundle 配置为内部应用
  3. 03适配不同 Salesforce API 版本
  4. 04验证 CustomApplication 与 UI Bundle 部署

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/forcedotcom/sf-skills --skill experience-ui-bundle-custom-app-generate

安装后在 Claude Code 中输入/experience-ui-bundle-custom-app-generate确认已加载。

附带文件references/configure-metadata-custom-application.mdscripts/resolve-uibundle-path.mjs

详细介绍

React UI Bundle 的自定义应用

创建并配置 Salesforce 自定义应用，以便在 Lightning Experience 中托管 React UI bundle。此技能会生成 CustomApplication 元数据，使应用显示在 Lightning App Launcher 中，并供内部用户访问。

自定义应用与 Experience Sites 不同：它们不需要 Networks、CustomSite、DigitalExperienceConfig 或 DigitalExperienceBundle 元数据。自定义应用充当轻量级的启动器入口，并将渲染工作交给 uiBundle 引用的 React UI bundle。

必需属性

生成任何元数据之前，请先解析所有属性。每项属性都有一条回退链——按顺序尝试各个选项，直到找到值。

属性格式解析方式
appNamelowercamelcase（例如，myInternalApp）uiBundles/<name>/ 目录中的 UI bundle 名称
appNamespace字符串sfdx-project.json 中的 namespace → sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias} → 默认为 c
appLabel易于理解的字符串用户提供；或将 appName 中的 camelCase 转换为标题格式

appNamespace 和 appName 用于将自定义应用连接到正确的 React UI bundle。在较新的 API 版本中使用 <uiBundle>{appNamespace}__{appName}</uiBundle>；在较旧的版本中使用 <webApplication>{appName}</webApplication>。如果这里设置错误，应用启动器入口仍会存在，但会显示空白页面。工作流的第 2 步会确定要使用哪个字段。

生成工作流

第 1 步：解析所有必需属性

在构建任何内容之前，确定所有属性的值。使用上表中的解析策略。

第 2 步：查询 API 上下文（按版本发现字段）

调用 salesforce-api-context MCP 工具，发现目标组织 API 版本中存在哪些字段。这可确保生成的元数据与用户的 Salesforce 版本兼容。

必需调用——请严格使用下方所示的 metadataType 参数。请勿替换为 detail 参数或任何其他形式；此工具仅接受 metadataType 参数：

  1. get_metadata_type_fields({ "metadataType": "CustomApplication" }) — 检查响应的字段列表中是否存在 uiBundle 字段
  2. get_metadata_type_fields({ "metadataType": "UIBundle" }) — 检查响应的字段列表中是否存在 target 字段

根据 API 响应解析字段：

字段检查如果存在如果不存在（较旧的 API 版本）
CustomApplication.uiBundle使用 <uiBundle>{appNamespace}__{appName}</uiBundle>使用 <webApplication>{appName}</webApplication>（不含命名空间）
UIBundle.target使用 <target>CustomApplication</target>完全省略 <target> 元素

如果实际尝试后 salesforce-api-context 仍不可用，则回退到较新的字段名称（uiBundle + target）。

第 3 步：创建项目结构

创建所有尚不存在的文件和目录：

元数据类型路径
CustomApplication<sourceDir>/applications/{appName}.app-meta.xml

注意：<sourceDir> 由 sfdx-project.json 确定。读取 packageDirectories[]，并使用其中 "default": true 的条目；完整源目录为 <path>/main/default。如果未设置默认项，则使用第一个条目。常见路径为 force-app/main/default，但此路径可配置。

步骤 4：填写所有元数据字段

使用下方文档中的默认模板。{大括号} 中的值是已解析的属性引用——将它们替换为步骤 1 中的实际值。应用步骤 2 中的字段解析结果，以确定要使用哪些 XML 元素。

元数据类型模板引用
CustomApplicationconfigure-metadata-custom-application.md
步骤 4 的执行说明：加载并使用文档
  • Agent 在尝试填写元数据字段前，必须阅读步骤 4 所引用的 references/*.md 文件的全部内容。
  • 完整读取该文件，替换占位符（例如 {appName}）为已解析的值，然后使用展开后的模板填写元数据 XML 内容。
  • 如果步骤 2 判定应使用较旧的字段名称，请在生成的输出中将 <uiBundle> 替换为 <webApplication>。
步骤 5：更新 UI Bundle 元 XML

此步骤编辑的是现有文件——绝不会创建新文件。UIBundle 是一种捆绑包样式的元数据类型：其元 XML 通常位于自己的文件夹中，路径为 uiBundles/{appName}/{appName}.uibundle-meta.xml，与该捆绑包的其他源文件（例如 index.html、src/）并列。一些较旧或手动编写的项目可能使用扁平路径 uiBundles/{appName}.uibundle-meta.xml（没有子文件夹）。

运行 node scripts/resolve-uibundle-path.mjs "{appName}"——该命令会输出现有元 XML 的路径（优先使用嵌套布局，若不存在则回退到扁平布局）。始终通过 node 调用（切勿直接执行），以确保在 Windows、macOS 和 Linux 上均可正常工作。就地编辑该确切文件；不要在另一条路径下创建第二个文件，也不要将文件迁移到其他布局，这是此技能不应执行的操作。

如果步骤 2 确认 UIBundle 上存在 target 字段，请在该文件现有的 <UIBundle> 元素内添加 <target>CustomApplication</target>，并保持所有其他现有元素和值不变（如果组织的 API 版本中不存在该字段，则完全跳过此步骤——不要创建文件或添加 <target>）。

不要：

  • 创建新的 .uibundle-meta.xml 文件
  • 在已有 .uibundle-meta.xml 文件（无论是嵌套还是扁平布局）的其他路径下再创建一个
  • 在其他位置添加 <target>，却不修改原有的 uiBundles/{appName}/{appName}.uibundle-meta.xml（或者现有布局为扁平布局时的 uiBundles/{appName}.uibundle-meta.xml）

此技能唯一会生成或修改的文件是 applications/{appName}.app-meta.xml（新建）和现有的 {appName}.uibundle-meta.xml（仅当适用 <target> 时就地编辑）。输出中出现任何其他与 UI Bundle 相关的文件都属于错误。

已完全更新文件的示例（位于 uiBundles/{appName}/{appName}.uibundle-meta.xml；如果现有布局为扁平布局，则位于扁平路径）——此示例展示的是现有文件的最终状态，而不是要创建的新文件：

<?xml version="1.0" encoding="UTF-8"?>
<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>{appName}</masterLabel>
    <description>A Salesforce UI Bundle.</description>
    <isActive>true</isActive>
    <version>1</version>
    <target>CustomApplication</target>
</UIBundle>
步骤 6：不要修改非模板化属性

不要修改 CustomApplication 元数据中任何未以 {大括号} 包裹变量形式表示的默认属性值。

验证清单

部署前，请确认：

  • 所有必需属性均已解析
  • 已查询 API 上下文以确定可用字段（步骤 2）
  • applications/{appName}.app-meta.xml 已存在且内容正确
  • 捆绑包引用字段与组织的 API 版本匹配（<uiBundle> 或 <webApplication>）
  • 如果支持 target 字段：现有的 {appName}.uibundle-meta.xml（位于 uiBundles/{appName}/ 下的嵌套路径，或 uiBundles/ 下的扁平路径，取决于原有布局）包含 <target>CustomApplication</target>
  • 未创建额外的 .uibundle-meta.xml 文件——恰好存在一个 {appName}.uibundle-meta.xml，且位于原有路径
  • 部署验证成功：
sf project deploy validate --metadata CustomApplication UIBundle --target-org ${usernameOrAlias}

评论

支持 Markdown