Experience UI Bundle 2gp Deploy

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.

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 or 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:

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.

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:

1. Enable Dev Hub, and
2. 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:

# 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.

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:

1. Sign up a DE org and register a namespace on it (Setup → Package Manager → Namespace Registrations).
2. 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.
3. 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.

# 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).