Package an existing UI Bundle (2GP)

How to take a UI Bundle that already exists in the current project (under

<packageDir>/uiBundles/<name>/

, where

<packageDir>

is the package directory from

sfdx-project.json

— commonly

force-app/main/default

) and ship it as a second-generation package (2GP), then install / upgrade / uninstall it in another org.

This is reference knowledge, not a runbook to execute top-to-bottom. The user already has a project and a built (or buildable) bundle. Read their intent and apply only the matching part:

Answer only what was asked. Give the commands for the one part the user needs plus the org each targets and any genuine caveat — nothing else. Do not restate the other parts, re-explain the flavor table, or replay the full build→create→install→promote sequence when the user asked about a single step. A debug question wants the fix, not a packaging tutorial; an install question wants the

sf package install

line and the subscriber-vs-Dev-Hub distinction, not Part 1 and Part 2. Brevity is correctness here.

The user wants to…	Go to
Decide managed vs. unlocked	Choose a flavor
Make the bundle packageable / wire a CustomApplication	Part 1
Create the package or a new version	Part 2
Install / upgrade / uninstall / promote	Part 3
Debug a failure	Part 4 + Troubleshooting

This skill is for packaging and cross-org distribution (

sf package …

). For plain source deploy of a bundle into one org (

sf project deploy …

), use experience-ui-bundle-deploy instead. Never

sf project generate

sf template generate ui-bundle

here — the project and bundle exist.

MyReactApp

force-app

force-app/main/default

are placeholders; substitute the user's real bundle name and their

<packageDir>

everywhere they appear below. Resolve

<packageDir>

deterministically — never guess

[0]

in a multi-package project — with:

bash

packageDir="$(scripts/find-bundle-package-dir.sh <bundleName>)"   # walks packageDirectories; picks the entry whose tree contains uiBundles/<bundleName>/

Step 0 — Confirm the orgs (do this before touching any org)

Do not assume the default org. Ask the user, or read

sf org list

, then restate what you'll use:

Dev Hub (
```
devhub
```
) — where the package is created, versions are built, and source is deployed. Always required.
Subscriber (
```
subscriber
```
) — the org you install into. Only required for install / upgrade / uninstall.

bash

sf org list                                            # connected orgs + default Dev Hub
sf org list --json | jq -r '.result.nonScratchOrgs[]?.alias'

Rules:

Create-only task (package or version) → one Dev Hub is enough; don't ask for a subscriber.
Install task → confirm both, and confirm which is which. Installing into the Dev Hub by mistake is a common, messy error.

Substitute the real aliases for

devhub

subscriber

everywhere below.

ID legend (packaging):

0Ho…

package ·

04t…

installable version (SubscriberPackageVersionId) ·

05i…

Package2Version ·

08c…

version-create request ·

0Hf…

install request ·

06y…

uninstall request.

ID legend (runtime, useful when debugging a broken subscriber):

9YE…

UI Bundle row ·

9YF…

UIBundleApplication junction ·

02u…

CustomApplication / TabSet ·

0Zu…

ManagedContentSpace (workspace) ·

0ap…

ManagedContentChannel (WEB_APP). A missing App Launcher tile after install almost always traces back to one of these being absent or misprovisioned.

Prerequisite — the 2GP toggle everyone forgets

2GP needs a manual Setup toggle on the Dev Hub that no CLI command or metadata deploy can flip. Setup → Dev Hub, both on:

Enable Dev Hub, and
Enable Unlocked Packages and Second-Generation Managed Packages ← the real gate.

Until #2 is on,

sf package create

returns

NOT_FOUND

and any

Package2

query returns

sObject type 'Package2' is not supported

. There is no CLI workaround — flip the toggle. Verify before starting:

bash

# clean "0 records" = 2GP ON;  "sObject type 'Package2' is not supported" = toggle OFF
sf data query --target-org devhub --use-tooling-api --query "SELECT Id FROM Package2 LIMIT 1"
sf org display --target-org devhub --json | jq '.result.isDevHub'

Choose a flavor

All three are 2GP (same

sf package

CLI). Pick before creating — it drives the namespace, how the bundle is named on install, and coexistence.

	Managed	Unlocked — namespaced	Unlocked — org-dependent
Namespace	required	required	none (empty `""` )
Source visibility	hidden (IP-protected)	visible / editable	visible / editable
Installs as	`ns__Name`	`ns__Name`	bare `Name` (flat)
Coexists with a local same-name bundle	yes (ns-filtered)	yes (ns-filtered)	no — collides
Upgrade behavior	clean replace (locked)	replace, overwrites subscriber edits	replace, overwrites subscriber edits
Rollback risk on failed upgrade	yes	yes	none
Typical use	ISV / AppExchange distribution	org-agnostic sharing, source open	package depends on metadata already in the target org

Namespaced flavors (managed, unlocked-namespaced) need a namespace registered and linked to this Dev Hub (App Launcher → Namespace Registries). No registered namespace? Use org-dependent unlocked — it needs none.

How linking works (namespace ⇄ Dev Hub)

The namespace lives in a separate Developer Edition (DE) org that owns it; the Dev Hub borrows it via a linked registration. Concretely:

Sign up a DE org and register a namespace on it (Setup → Package Manager → Namespace Registrations).
In the Dev Hub, App Launcher → Namespace Registries → Link Namespace, log in with the DE org's credentials to link the namespace to this Dev Hub.
Set
```
namespace
```
in
```
sfdx-project.json
```
to the linked namespace slug. If the value here isn't linked to the target Dev Hub,
```
sf package version create
```
fails with a namespace error (see Troubleshooting).

One DE org can carry multiple namespaces, and one Dev Hub can link multiple DE orgs — so a single Dev Hub can build packages under several namespaces. The namespace is locked in at version-create time and travels with every UI Bundle row inside the built version; you cannot change it later.

Runtime model — why the flavor matters

You do not have to explain this to answer a routine question. Reach for it when the user asks why: why managed hides source, why namespaced installs are

ns__Name

, why some URLs look different, or why an unlocked upgrade wiped their edits.

Origin isolation. Every installed UI Bundle renders from its own origin on
```
*.salesforce.app
```
, distinct from
```
salesforce.com
```
core UI. Tiers:
- ```
salesforce.com
```
  — 1st-party core UI
- ```
*.salesforce.app
```
  — 2nd-party AFS-hosted bundles (no namespace)
- ```
<ns>.salesforce.app
```
  — 3rd-party / namespaced (managed + unlocked-namespaced) Because each namespace gets its own subdomain, two bundles from different packages can coexist without cross-origin bleed.
IP protection is a managed-only property. For managed packages,
```
getSourceZip()
```
returns null in subscriber orgs — the compiled
```
dist/
```
is stored as opaque content and never handed back. For unlocked (namespaced or org-dependent), the served binary is fully readable by the subscriber.
Install semantics. Managed and unlocked-namespaced install as
```
ns__Name
```
and can coexist with a local same-name bundle. Org-dependent unlocked has no namespace — it installs as bare
```
Name
```
and collides with a local bundle of the same developer name.
Delta upgrade. On
```
sf package install
```
of a newer
```
04t…
```
, the platform compares content-index hashes of each incoming
```
dist/
```
asset against what's already stored and skips any asset whose hash is unchanged — a patch that touches one bundle re-writes only that bundle's changed files. Developer-owned artifacts (
```
dist/
```
,
```
ui-bundle.json
```
, ISV base permission sets) are replaced; subscriber-owned state (subscriber-created permission sets, custom metadata, provisioned domain) is preserved.
Kill switch. Setup → Security → Multi-Framework Domains → disable a provisioned domain. Immediate 404; metadata stays installed; reversible.

Part 1 — make the existing bundle packageable

Prepare the project so it can be packaged and used in-org. Apply only what the request needs.

1a. Set API version + namespace in

sfdx-project.json

The

namespace

here decides which flavor you can build (see table above), so set it deliberately — there is no safe default. Substitute the user's real registered namespace for

<ns>

; use

""

for org-dependent.

bash

# namespaced (managed / unlocked-namespaced): <ns> MUST be registered & linked to this Dev Hub
node -e "const fs=require('fs'),f='sfdx-project.json',j=JSON.parse(fs.readFileSync(f)); j.sourceApiVersion='68.0'; j.namespace='<ns>'; fs.writeFileSync(f,JSON.stringify(j,null,2))"

# org-dependent unlocked: no namespace
node -e "const fs=require('fs'),f='sfdx-project.json',j=JSON.parse(fs.readFileSync(f)); j.sourceApiVersion='68.0'; j.namespace=''; fs.writeFileSync(f,JSON.stringify(j,null,2))"

cat sfdx-project.json    # confirm namespace + sourceApiVersion before packaging

Managed / namespaced-unlocked →
```
namespace
```
= a registered, linked namespace.
Org-dependent unlocked → leave
```
namespace
```
as
```
""
```
.
Setting a namespace that isn't registered to this Dev Hub fails the build later (see Troubleshooting).

1b. Build the bundle —

dist/

must exist before packaging

bash

cd force-app/main/default/uiBundles/MyReactApp        # the real bundle dir
npm install --no-audit --no-fund
npm run build
cd -

Package or deploy before

dist/

exists and the app installs but renders blank — the bundle ships with its built assets. Always build first.

1c. Wire a CustomApplication (only if the bundle must be launchable as a Salesforce app)

Skip this step when the bundle is already referenced another way (embedded in a FlexiPage, Experience Cloud site, etc.). Otherwise read

<SKILL_DIR>/assets/CustomApplication.app-meta.xml

(where

<SKILL_DIR>

is the absolute path to this skill's own directory), replace every

MyReactApp

with the real bundle developer name, and write the result to the user's project under

<packageDir>/applications/

. Author

<uiBundle>

with the bundle's developer name — inside the same package no prefix is needed; cross-namespace it resolves as

ns__Name

(namespaced) or

c__Name

(no namespace).

The three fields the App Launcher tile actually cares about — installed subscribers won't see a broken tile if they're set correctly:

```
<uiType>Lightning</uiType>
```
— required for the App Launcher to render it
```
<navType>Standard</navType>
```
— standard navigation container
```
<formFactors>Large</formFactors>
```
— desktop form factor (validation is install-time only, so a missing/wrong value passes deploy but hides the tile)

bash

mkdir -p force-app/main/default/applications
# then write the substituted template to:
#   force-app/main/default/applications/<BundleName>.app-meta.xml

1d. Deploy source to the Dev Hub (so metadata exists before

package create

)

bash

sf project deploy start --source-dir force-app --target-org devhub --api-version 68.0 --wait 30

1e. Grant app visibility via a permission set (only if 1c added a CustomApplication and the app must be reachable without a manual Setup click)

Read

<SKILL_DIR>/assets/PermissionSet.permissionset-meta.xml

, replace

MyReactApp

with the real bundle name (both in

<application>

and the label), write the result into the user's project, then deploy and assign:

bash

mkdir -p force-app/main/default/permissionsets
# write the substituted template to:
#   force-app/main/default/permissionsets/<BundleName>_Access.permissionset-meta.xml
sf project deploy start --source-dir force-app/main/default/permissionsets/MyReactApp_Access.permissionset-meta.xml --target-org devhub --api-version 68.0 --wait 30
sf org assign permset --name MyReactApp_Access --target-org devhub

Part 2 — create the package (Dev Hub only)

No subscriber org involved.

sf package create

runs once (registers the

0Ho…

container); you build installable

04t…

versions repeatedly after. Pick the one flavor you chose above:

bash

# managed
sf package create --name MyReactApp --package-type Managed --path force-app --target-dev-hub devhub

# unlocked, namespaced  (namespace comes from sfdx-project.json)
sf package create --name MyReactApp --package-type Unlocked --path force-app --target-dev-hub devhub

# unlocked, org-dependent (no namespace)
sf package create --name MyReactApp --package-type Unlocked --org-dependent --path force-app --target-dev-hub devhub

Then build a version:

bash

sf package version create --package MyReactApp --installation-key-bypass --wait 20 --target-dev-hub devhub
# a specific/patch version instead:
sf package version create --package MyReactApp --version-number 1.0.1 --wait 20 --target-dev-hub devhub

--version-number 1.0.0.NEXT

auto-bumps the build number; a fixed

1.0.1

pins it.

--installation-key-bypass

builds an unprotected version (no key to install); omit it and pass

--installation-key <key>

to gate installs.

Robust version-create (survives a slow Dev Hub queue)

--wait

can time out while the build sits queued, losing the request handle. Submit async, capture the

08c…

id, poll:

bash

REQ=$(sf package version create --package MyReactApp --installation-key-bypass \
  --skip-validation --target-dev-hub devhub --json | jq -r '.result.Id')
echo "request: $REQ"
while :; do
  J=$(sf package version create report -i "$REQ" --target-dev-hub devhub --json)
  ST=$(echo "$J" | jq -r '.result[0].Status'); echo "status: $ST"
  case "$ST" in
    Success) echo "$J" | jq -r '.result[0].SubscriberPackageVersionId'; break;;
    Error)   echo "$J" | jq -r '.result[0].Error[]? // "build failed"'; break;;
  esac
  sleep 30
done

--skip-validation

is faster but produces a beta version (can't be promoted, and beta can't upgrade beta — see Part 3). Drop it for a releasable build. Resume a queued build anytime:

sf package version create report -i 08c… --target-dev-hub devhub

Part 3 — install / upgrade / uninstall / promote

Confirm the subscriber alias first (Step 0). Everything here hits the subscriber — except promote, which runs on the Dev Hub.

bash

# fresh install
sf package install --package 04t… --target-org subscriber --wait 10
#   add --installation-key <key> if the version was built with one
#   add --publish-wait 10 to wait for the version to finish publishing

# upgrade (newer version over the old)
sf package install --package 04t…v2 --target-org subscriber --upgrade-type Mixed --wait 10
#   --upgrade-type: Mixed (default) | DeprecateOnly | Delete (destructive — care)

# uninstall
sf package uninstall --package 04t… --target-org subscriber --wait 20

# promote a managed version to released/immutable — runs on the DEV HUB, irreversible
sf package version promote --package 04t… --target-dev-hub devhub

Beta can't upgrade beta. A

--skip-validation

(beta) v0.2 over a beta v0.1 fails with "Cannot upgrade beta package." Either promote v0.1 (managed) or uninstall v0.1 first, then install v0.2.

Unlocked upgrades overwrite subscriber edits to the bundle. Org-dependent has no rollback on a failed upgrade; namespaced flavors do.

Robust install (confirm it actually landed)

sf package install --wait

can exit 0 while the request is still IN_PROGRESS — a false success. Verify:

bash

sf package install --package 04t… --target-org subscriber --wait 20 --no-prompt
sf package installed list --target-org subscriber --json \
  | jq -r '.result[]? | select(.SubscriberPackageVersionId=="04t…") | .SubscriberPackageVersionId'

Prints nothing → still processing server-side; poll

sf package installed list

a few minutes before concluding it failed.

Part 4 — debug / inspect

Mostly read-only. Reach for these to diagnose a failure or inspect state.

bash

# Dev Hub state
sf org display --target-org devhub --json | jq '{isDevHub:.result.isDevHub, user:.result.username, instance:.result.instanceUrl, api:.result.apiVersion}'

# Is 2GP on?  (the #1 root cause)
sf data query --target-org devhub --use-tooling-api --query "SELECT Id, Name, NamespacePrefix, ContainerOptions FROM Package2"

# Packages & versions on the Dev Hub
sf package list --target-dev-hub devhub
sf package version list --packages MyReactApp --target-dev-hub devhub --verbose

# Version-create failures — status + Error[]
sf package version create list --target-dev-hub devhub
sf package version create report -i 08c… --target-dev-hub devhub
sf data query --target-org devhub --use-tooling-api \
  --query "SELECT Id, Status, Package2Id, Error FROM Package2VersionCreateRequest ORDER BY CreatedDate DESC LIMIT 5"

# A version's details
sf package version report --package 04t… --target-dev-hub devhub

# What's installed in the subscriber
sf package installed list --target-org subscriber --json \
  | jq -r '.result[]? | "\(.SubscriberPackageName) \(.SubscriberPackageVersionNumber) \(.SubscriberPackageVersionId)"'

# Install/uninstall stuck IN_PROGRESS
sf package install report   --request-id 0Hf… --target-org subscriber
sf package uninstall report --request-id 06y… --target-org subscriber

# Deploy failures (before you can even package)
sf project deploy start --source-dir force-app --target-org devhub --dry-run --wait 30
sf project deploy report --target-org devhub

# Bundle renders blank — confirm built assets shipped
ls -la force-app/main/default/uiBundles/MyReactApp/dist

Troubleshooting

Symptom	Cause / fix
`sObject type 'Package2' is not supported`	2GP toggle OFF — Setup → Dev Hub → enable "Unlocked & Second-Gen Managed Packages" (manual, no CLI fix).
`sf package create` → `NOT_FOUND`	Same — 2GP not provisioned. Enable toggle, re-auth.
`isDevHub: false/null` after enabling	Cached CLI login — re-auth. Trust the `Package2` query + `package create` , not the cached flag.
`version create` hangs / `--wait` times out	Build queued. Use the async submit + `version create report -i 08c…` poll; resume later with the same id.
`install --wait` exits 0 but app missing	Still IN_PROGRESS server-side. Confirm with `sf package installed list` ; poll a few minutes.
"Cannot upgrade beta package"	Beta can't upgrade beta. Promote v0.1 (managed) or uninstall it first, then install v0.2.
Namespace error on managed/namespaced build	Namespace not registered/linked to this Dev Hub (App Launcher → Namespace Registries), or switch to org-dependent unlocked (no namespace).
App installs but renders blank	Bundle not built before deploy/package — `npm run build` , confirm `dist/` , redeploy, rebuild the version.
Installed into the wrong org	Wrong alias confirmed in Step 0. Re-check `sf org list` ; `subscriber` ≠ `devhub` .
Org-dependent bundle collides with a local one	Both use a bare (null-prefix) name. Use a namespaced flavor, or rename.

Notes

Confirm orgs first. Dev Hub always; subscriber only for install/upgrade/ uninstall. Don't ask for a subscriber on a create-only task.
Order for a full run: build bundle → deploy source →
```
package create
```
(once) →
```
package version create
```
(each release) →
```
install
```
→
```
promote
```
(managed only).
For internal Salesforce packaging questions, the authoritative channel is #packaging.
Authoritative external docs (for deeper reference):
- Second-Generation Managed Packaging Developer Guide — https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/sfdx_dev_dev2gp.htm (managed / AppExchange flavor: workflow, components, distribution, push upgrades, 1GP→2GP gaps).
- Unlocked packages share the same
```
sf package
```
  CLI; see the "Unlocked Packages" section of the same guide for the unlocked-namespaced and org-dependent flavors.

experience-ui-bundle-2gp-deploy

NPX Install

Tags

SKILL.md Content

Package an existing UI Bundle (2GP)

Step 0 — Confirm the orgs (do this before touching any org)

Prerequisite — the 2GP toggle everyone forgets

Choose a flavor

How linking works (namespace ⇄ Dev Hub)

Runtime model — why the flavor matters

Part 1 — make the existing bundle packageable

1a. Set API version + namespace in
`sfdx-project.json`

1b. Build the bundle —
`dist/`
must exist before packaging

1c. Wire a CustomApplication (only if the bundle must be launchable as a Salesforce app)

1d. Deploy source to the Dev Hub (so metadata exists before
`package create`
)

1e. Grant app visibility via a permission set (only if 1c added a CustomApplication and the app must be reachable without a manual Setup click)

Part 2 — create the package (Dev Hub only)

Robust version-create (survives a slow Dev Hub queue)

Part 3 — install / upgrade / uninstall / promote

Robust install (confirm it actually landed)

Part 4 — debug / inspect

Troubleshooting

Notes

experience-ui-bundle-2gp-deploy

NPX Install

Tags

SKILL.md Content

Package an existing UI Bundle (2GP)

Step 0 — Confirm the orgs (do this before touching any org)

Prerequisite — the 2GP toggle everyone forgets

Choose a flavor

How linking works (namespace ⇄ Dev Hub)

Runtime model — why the flavor matters

Part 1 — make the existing bundle packageable

1a. Set API version + namespace in sfdx-project.json

1b. Build the bundle — dist/ must exist before packaging

1c. Wire a CustomApplication (only if the bundle must be launchable as a Salesforce app)

1d. Deploy source to the Dev Hub (so metadata exists before package create)

1e. Grant app visibility via a permission set (only if 1c added a CustomApplication and the app must be reachable without a manual Setup click)

Part 2 — create the package (Dev Hub only)

Robust version-create (survives a slow Dev Hub queue)

Part 3 — install / upgrade / uninstall / promote

Robust install (confirm it actually landed)

Part 4 — debug / inspect

Troubleshooting

Notes

1a. Set API version + namespace in
`sfdx-project.json`

1b. Build the bundle —
`dist/`
must exist before packaging

1d. Deploy source to the Dev Hub (so metadata exists before
`package create`
)