experience-ui-bundle-project-generate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using a UI Bundle Template

使用UI Bundle模板

Before building a Salesforce React UI bundle app from scratch, offer the user a prebuilt starter template. The Salesforce CLI generates these — a complete, deployable SFDX project (React UI bundle + toolchain + an

npm run setup

automation) — in one command. Starting from a starter is faster and less error-prone than hand-scaffolding.

The CLI command is

sf template generate project

在从头构建Salesforce React UI bundle应用之前，为用户提供一个预构建的启动模板。这些模板由Salesforce CLI生成——一键即可创建完整的、可部署的SFDX项目（包含React UI bundle + 工具链 +

npm run setup

自动化流程）。从启动模板开始比手动搭建更快且更少出错。

使用的CLI命令为

sf template generate project

。

Step 1: Offer the choice

步骤1：提供选择

The following are the templates. Ask the user which one fits, or whether they want to start from scratch.

Template	`--template` flag	Best for
Internal starter	`reactinternalapp`	Starter for internal, employee-facing Salesforce apps (e.g. support consoles, ops dashboards, internal admin apps) — users are already-authenticated employees. Includes Agentforce chat. No login flow or public.
External starter	`reactexternalapp`	Starter for customer/partner-facing Salesforce apps/sites (e.g. portals, communities, storefront, public sites). Full auth support (login, registration, reset, profile) -- external users sign in with their own accounts.

If the user prefers to start from scratch (or neither fits), stop here and let

experience-ui-bundle-app-coordinate

scaffold a new project. This skill is opt-in — do not force a template.

以下是可用模板，请询问用户哪一个符合需求，或者是否想要从头开始。

模板	`--template` 参数	适用场景
内部启动模板	`reactinternalapp`	面向内部员工的Salesforce应用（如支持控制台、运营仪表板、内部管理应用）的启动模板——用户为已认证员工。包含Agentforce聊天功能，无登录流程或公共访问。
外部启动模板	`reactexternalapp`	面向客户/合作伙伴的Salesforce应用/站点（如门户、社区、店面、公共站点）的启动模板。支持完整认证（登录、注册、重置、个人资料）——外部用户使用自有账号登录。

如果用户偏好从头开始（或两个模板都不符合），请在此停止，让

experience-ui-bundle-app-coordinate

搭建新项目。此技能为可选——请勿强制使用模板。

Step 2: Generate the project into the target root

步骤2：将项目生成到目标根目录

The project contents must land directly at the target root
$DEST
— so

sfdx-project.json

sits at

$DEST/sfdx-project.json

, with no extra wrapper subfolder.

sf template generate project

always nests its output under a

--name

subfolder, so generate into the

$DEST

dir, then move the contents from the subfolder up into

$DEST

, overwriting anything already there on conflict. Remove the empty subfolder at the end.

```
<SKILL_DIR>
```
= the absolute path to this skill's own directory — the folder containing this
```
SKILL.md
```
; resolve it from the skill path in context
$NAME
— the project name (alphanumerical only — no spaces, hyphens, underscores, or special characters). Ask the user for it. It also names the UI bundle, so it shows up inside the project.
$DEST
— the target root directory the contents land in (use
```
.
```
for the current directory).

NAME=MyApp   # project name the user chose; also names the UI bundle
DEST=.       # target root directory (the contents land directly here, no NAME/ wrapper)

项目内容必须直接放在**目标根目录

$DEST

**下——即

sfdx-project.json

位于

$DEST/sfdx-project.json

，无额外的包装子文件夹。

sf template generate project

始终会将输出嵌套在

--name

指定的子文件夹下，因此需先将项目生成到

$DEST

目录，然后将子文件夹中的内容移至

$DEST

，冲突时覆盖已有内容。最后删除空的子文件夹。

```
<SKILL_DIR>
```
= 此技能自身目录的绝对路径——包含此
```
SKILL.md
```
的文件夹；根据上下文路径解析
$NAME
—— 项目名称（仅允许字母数字——无空格、连字符、下划线或特殊字符）。需向用户询问。它同时也是UI bundle的名称，会显示在项目内部。
$DEST
—— 内容存放的目标根目录（使用
```
.
```
表示当前目录）。

NAME=MyApp   # 用户选择的项目名称；同时作为UI bundle的名称
DEST=.       # 目标根目录（内容直接存放在此处，无NAME/包装文件夹）

choose ONE template flag based on the user's pick from Step 1

根据步骤1中用户的选择，选择一个模板参数

TEMPLATE=reactinternalapp # or reactexternalapp

mkdir -p "$DEST" sf template generate project --name "$NAME" --template "$TEMPLATE" --output-dir "$DEST"

TEMPLATE=reactinternalapp # 或reactexternalapp

mkdir -p "$DEST" sf template generate project --name "$NAME" --template "$TEMPLATE" --output-dir "$DEST"

Flatten the generated $DEST/$NAME contents up into $DEST (see <SKILL_DIR>/scripts/flatten-project.mjs).

将生成的$DEST/$NAME中的内容移至$DEST（请参考<SKILL_DIR>/scripts/flatten-project.mjs）。

Use the absolute skill-dir path — a relative ./scripts/ would resolve against $DEST, not the skill.

使用技能目录的绝对路径——相对路径./scripts/会相对于$DEST解析，而非技能目录。

node "<SKILL_DIR>/scripts/flatten-project.mjs" "$DEST/$NAME" "$DEST" rm -rf "$DEST/$NAME"


> `<SKILL_DIR>/scripts/flatten-project.mjs` moves every generated entry (incl. dotfiles) into `$DEST`, overwriting any existing file/dir of any type on conflict while preserving unrelated files the user already had in `$DEST`. The per-entry `rmSync` + `renameSync` is what guarantees the template's files win on conflict (including a file-vs-directory type mismatch).

node "<SKILL_DIR>/scripts/flatten-project.mjs" "$DEST/$NAME" "$DEST" rm -rf "$DEST/$NAME"


> `<SKILL_DIR>/scripts/flatten-project.mjs`会将所有生成的条目（包括点文件）移至`$DEST`，冲突时覆盖任何现有文件/目录（包括文件与目录类型不匹配的情况），同时保留用户已在`$DEST`中的无关文件。逐条执行`rmSync` + `renameSync`可确保模板文件在冲突时优先保留（包括文件与目录类型不匹配的情况）。

Verify

验证

After generation, confirm the contents landed at the root (not in a

$NAME/

subfolder):

test -f "$DEST/sfdx-project.json" && echo "OK: project root landed" || echo "FAILED"

sfdx-project.json

must sit at

$DEST/sfdx-project.json

. The project also contains

package.json

force-app/main/default/uiBundles/$NAME/

(the React/Vite bundle),

scripts/

config/

, and

README.md

. If

sfdx-project.json

is missing or is one level down in

$DEST/$NAME/

, the flatten did not run — re-check before continuing.

生成完成后，确认内容已存放在根目录（而非

$NAME/

子文件夹中）：

test -f "$DEST/sfdx-project.json" && echo "OK: project root landed" || echo "FAILED"

sfdx-project.json

必须位于

$DEST/sfdx-project.json

。项目还包含

package.json

、

force-app/main/default/uiBundles/$NAME/

（React/Vite bundle）、

scripts/

、

config/

和

README.md

。如果

sfdx-project.json

缺失或位于

$DEST/$NAME/

下一级目录，则移动操作未成功——请在继续前重新检查。

Step 3: Install dependencies (you do this — do NOT hand off uninstalled)

步骤3：安装依赖（由你完成——请勿交付未安装的项目）

If the generated project ships without

node_modules

, install dependencies yourself before handing the project back — a fresh template is not runnable (preview/build/lint all fail) until deps are present. The user should receive a ready-to-develop project.

There are multiple

package.json

files, each needing its own install:

the project root (
```
$DEST/package.json
```
), and
the UI bundle dir under
```
$DEST/force-app/main/default/uiBundles/$NAME/
```
— this holds the toolchain the preview server loads, so it must have
```
node_modules
```
too.

undefined

如果生成的项目未包含

node_modules

，在交付项目前自行安装依赖——全新模板在安装依赖前无法运行（预览/构建/检查都会失败）。用户收到的应是可直接开发的项目。

项目中有多个

package.json

文件，每个都需要单独安装：

项目根目录（
```
$DEST/package.json
```
），以及
UI bundle目录
```
$DEST/force-app/main/default/uiBundles/$NAME/
```
——此处包含预览服务器加载的工具链，因此必须有
```
node_modules
```
。

undefined

1. project root ($DEST was set in Step 2)

1. 项目根目录（$DEST已在步骤2中设置）

( cd "$DEST" && npm install )

2. each UI bundle

2. 每个UI bundle

for b in "$DEST"/force-app/main/default/uiBundles/*/; do [ -f "$b/package.json" ] && ( cd "$b" && npm install ) done


> First-run install of the bundle is the heavy step (tailwind, radix-ui, recharts, vite, etc.); expect a short wait. If an install fails, surface it — don't hand off a half-installed project.

for b in "$DEST"/force-app/main/default/uiBundles/*/; do [ -f "$b/package.json" ] && ( cd "$b" && npm install ) done


> 首次安装bundle是耗时步骤（包含tailwind、radix-ui、recharts、vite等）；请等待片刻。如果安装失败，请告知用户——请勿交付安装未完成的项目。

Step 4: Confirm and hand off

步骤4：确认并交付

Verify the project landed and is installed:

ls "$DEST" # sfdx-project.json, package.json, force-app/, scripts/, README.md ...
ls "$DEST"/force-app/main/default/uiBundles/*/node_modules >/dev/null && echo "bundle deps installed"

The project is now ready to develop and deploy. If there's a

README.md

in the template, take a look at it to see if there is any extra step or guidance for the user.

From here, continue development with the other ui-bundle skills (

experience-ui-bundle-frontend-generate

experience-ui-bundle-salesforce-data-access

experience-ui-bundle-deploy

, etc.) against the now-scaffolded project — scaffolding and dependency install are already done.

验证项目已生成且依赖已安装：

ls "$DEST" # sfdx-project.json, package.json, force-app/, scripts/, README.md ...
ls "$DEST"/force-app/main/default/uiBundles/*/node_modules >/dev/null && echo "bundle deps installed"

项目现在已准备好进行开发和部署。如果模板中包含

README.md

，请查看其中是否有针对用户的额外步骤或指南。

从这里开始，可针对已搭建好的项目使用其他ui-bundle技能（

experience-ui-bundle-frontend-generate

、

experience-ui-bundle-salesforce-data-access

、

experience-ui-bundle-deploy

等）继续开发——搭建和依赖安装已完成。

Notes

注意事项

The starters are minimal — no seeded sample data or custom objects. Build the rest with the other ui-bundle skills.
These templates use the
```
uiBundles
```
metadata convention. The UI bundle directory and meta XML are named after the project name you pass to
```
--name
```
.
```
sf template generate project --help
```
lists all available templates if the flag names ever change.

启动模板是最小化的——无预填充的示例数据或自定义对象。其余功能请使用其他ui-bundle技能构建。
这些模板使用
```
uiBundles
```
元数据约定。UI bundle目录和元XML文件的名称与你传递给
```
--name
```
的项目名称一致。
如果参数名称有变化，
```
sf template generate project --help
```
会列出所有可用模板。