experience-ui-bundle-site-generate

# Digital Experience Site for React UI Bundles Create and configure Digital Experience Sites that host React UI bundles on Salesforce. This skill generates the minimum necessary site infrastructure — Network, CustomSite, DigitalExperienceConfig, DigitalExperienceBundle, and the `sfdc_cms__site` content type — so a React app can be served from Salesforce. React sites differ from standard LWR sites: they don't need routes, views, theme layouts, or branding sets. The site acts as a thin container (`appContainer: true`) that delegates rendering to the React UI bundle referenced by `appSpace`. ## Required Properties Resolve all five properties before generating any metadata. Each has a fallback chain — work through each option in order until a value is found. | Property | Format | How to Resolve | |----------|--------|----------------| | **siteName** | `UpperCamelCase` (e.g., `MyCommunity`) | Ask user or derive from context | | **siteUrlPathPrefix** | `All lowercase` (e.g., `mycommunity`) | User-provided, or convert siteName to all lowercase with alphanumeric characters only | | **appNamespace** | String | `namespace` in `sfdx-project.json` → `sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias}` → default `c` | | **appDevName** | String | `UIBundle` metadata in the project → `sf data query -q "SELECT DeveloperName FROM UIBundle" --target-org ${usernameOrAlias}` → default to siteName | | **enableGuestAccess** | Boolean | Ask user whether unauthenticated guest users can access site APIs → default `false` | The `appNamespace` and `appDevName` properties record the intended UIBundle binding for a **future follow-up update**; they are **not** substituted into `appSpace` at initial site creation. `appSpace` in the `sfdc_cms__site` `content.json` is always `""` at initial creation — see [configure-metadata-digital-experience.md](references/configure-metadata-digital-experience.md) for the reason and the follow-up flow. ### Language Properties The skill always emits `sfdc_cms__languageSettings` alongside `sfdc_cms__site`. Resolve `defaultLocale` for every site (defaults to `en_US`); resolve `languages` only when the user requests additional languages beyond the default. | Property | Format | How to Resolve | |----------|--------|----------------| | **defaultLocale** | `xx` or `xx_YY` (e.g., `en`, `en_US`) | Ask user → default `en_US` | | **languages** | List of `{label, locale}` | Only when the user asks for multiple languages, locales, internationalization, or translation support: ask for the additional languages the site supports. When not requested, the languageSettings content declares only the resolved `defaultLocale` as a single-language entry. | The content-item folder name (`languages`), `title` (`LanguageContent`), and `urlName` (`languagecontent`) are fixed Experience Builder auto-defaults — they are **not** user-authored. See [configure-metadata-language-settings.md](references/configure-metadata-language-settings.md). ## Pre-flight: Target Org Release (Multi-Language Only) The `sfdc_cms__languageSettings` content type accepts multi-language declarations only on Salesforce Release 264 (API **v68.0** or higher). Sites reduced to a single-locale `en_US` declaration work on any org and do not need this check. When the user requests multiple languages, verify the target org's maximum supported API version **before writing any metadata**. `sf api request rest` hits `/services/data/` on the instance directly and handles authentication at the transport layer, so the org's true ceiling is returned without any access token entering this script's context. ```bash MAX_API=$(sf api request rest "/services/data/" --target-org "${usernameOrAlias}" \ | jq -r '[.[].version | tonumber] | max') awk -v v="$MAX_API" 'BEGIN{ exit !(v+0 >= 68.0) }' \ || { echo "ERROR: multi-language site containers require Salesforce Release 264 (API v68.0+). Target org's maximum supported API version is v${MAX_API}. Retarget to a Release 264+ org, or reduce the site to a single-locale (en_US) declaration." >&2; exit 1; } ``` If the check fails, do not write metadata. Report the version mismatch to the user and stop. ## Generation Workflow ### Step 1: Resolve All Required Properties Determine values for all five required properties and the `defaultLocale` language property before constructing anything. Use the resolution strategies in the tables above, falling through each option until a value is found. Resolve the `languages` property only when the user has requested multiple languages — and when they do, run the [Pre-flight](#pre-flight-target-org-release-multi-language-only) check above before continuing to Step 2. ### Step 2: Create the Project Structure Use available Salesforce metadata schema and field context for `Network`, `CustomSite`, `DigitalExperienceConfig`, and `DigitalExperienceBundle` to ensure each file uses valid structure. Create any files and directories that don't already exist, using these paths: | Metadata Type | Path | |--------------|------| | Network | `networks/{siteName}.network-meta.xml` | | CustomSite | `sites/{siteName}.site-meta.xml` | | DigitalExperienceConfig | `digitalExperienceConfigs/{siteName}1.digitalExperienceConfig-meta.xml` | | DigitalExperienceBundle | `digitalExperiences/site/{siteName}1/{siteName}1.digitalExperience-meta.xml` | | DigitalExperience (sfdc_cms__site) | `digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/*` | | DigitalExperience (sfdc_cms__languageSettings) | `digitalExperiences/site/{siteName}1/sfdc_cms__languageSettings/languages/*` | Each DigitalExperience content-type directory contains only `_meta.json` and `content.json`. Both `sfdc_cms__site` and `sfdc_cms__languageSettings` are always required inside the bundle. The `sfdc_cms__languageSettings` default declares only the resolved `defaultLocale` (e.g. `en_US`); it is extended with additional languages when the user requests multi-language support. No other content types are permitted. ### Step 3: Populate All Metadata Fields Use the default templates in the docs below. Values in `{braces}` are resolved property references — substitute them with the actual values from Step 1. | Metadata Type | Template Reference | |--------------|-------------------| | Network | [configure-metadata-network.md](references/configure-metadata-network.md) | | CustomSite | [configure-metadata-custom-site.md](references/configure-metadata-custom-site.md) | | DigitalExperienceConfig | [configure-metadata-digital-experience-config.md](references/configure-metadata-digital-experience-config.md) | | DigitalExperienceBundle | [configure-metadata-digital-experience-bundle.md](references/configure-metadata-digital-experience-bundle.md) | | DigitalExperience (sfdc_cms__site) | [configure-metadata-digital-experience.md](references/configure-metadata-digital-experience.md) | | DigitalExperience (sfdc_cms__languageSettings) | [configure-metadata-language-settings.md](references/configure-metadata-language-settings.md) | For URL updates, see [update-site-urls.md](references/update-site-urls.md). ### Execution Note for Step 3: Load and use the docs - Agents MUST read the full contents of each references/*.md file referenced in Step 3 before attempting to populate metadata fields. - Use your platform's file-read tool (for example, `read_file`) to load these files in full, then perform placeholder substitution for values in `{braces}` using the resolved properties from Step 1. - Files to load: - `references/configure-metadata-network.md` - `references/configure-metadata-custom-site.md` - `references/configure-metadata-digital-experience-config.md` - `references/configure-metadata-digital-experience-bundle.md` - `references/configure-metadata-digital-experience.md` - `references/configure-metadata-language-settings.md` - Read entire file contents, replace placeholders (e.g. `{siteName}`) with the resolved values, then use the expanded templates to populate the metadata XML/JSON content. ### Step 4: Do Not Modify Non-Templated Properties Do not modify any default property values for `Network`, `CustomSite`, `DigitalExperience`, `DigitalExperienceConfig`, or `DigitalExperienceBundle` metadata that are not expressed as variables wrapped in `{braces}`. ## Verification Checklist Before deploying, confirm: - [ ] All five required properties are resolved, and `defaultLocale` is resolved (defaulting to `en_US` when the user does not specify one) - [ ] All metadata directories and files exist per the project structure - [ ] All metadata fields match the Step 3 templates with `{braces}` substituted only; no other default property values were added or changed - [ ] `appSpace` in `sfdc_cms__site` `content.json` is the empty string `""` (initial site creation never binds `appSpace`; that is a separate follow-up update after the UIBundle is deployed to the target org) - [ ] The `sfdc_cms__languageSettings/languages/` files exist. The language declaration satisfies every platform rule below: - [ ] `defaultLocale` matches the `locale` of one declared language, which is active - [ ] every `locale` is Salesforce-supported, every language is `isActive: true`, each `locale` + `label` combination is unique, and the number of declared languages does not exceed the platform maximum - See [configure-metadata-language-settings.md](references/configure-metadata-language-settings.md) for the full rule catalog. Single-language default declarations satisfy every rule trivially. - [ ] Deployment validates successfully (the `DigitalExperience` type already covers `sfdc_cms__languageSettings` — no change to the `--metadata` list is needed): ```bash sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig DigitalExperienceBundle DigitalExperience --target-org ${usernameOrAlias} ``` ## Common Workflows ### Updating Experience Site URLs **Use when** user wants to update or change site URLs (urlPathPrefix). **Steps**: - [ ] Read [update-site-urls.md](references/update-site-urls.md) to understand the three-component architecture and URL update workflow - [ ] Follow the step-by-step workflow in the doc to update URLs consistently across all three components (DigitalExperienceConfig, Network, CustomSite) ### Configuring Multi-Language Support **Use when** user wants the site to support multiple languages, locales, internationalization, or translation — beyond the default-locale-only declaration that every site already receives. **Steps**: - [ ] Collect the additional languages the site should support and which locale is the default (resolve the `defaultLocale` and `languages` properties above) - [ ] Run the [Pre-flight: Target Org Release](#pre-flight-target-org-release-multi-language-only) check — abort if the org is below Release 264 (API v68+) - [ ] Read [configure-metadata-language-settings.md](references/configure-metadata-language-settings.md) for the templates, field reference, and platform validation rules - [ ] Extend the `sfdc_cms__languageSettings/languages/content.json` (which already exists with the default locale) to include the additional language entries, then re-run deploy validation **Note:** This is authoring-only — declared locales deploy cleanly, but locale-in-path routing does not resolve at request time yet. Do not translate the UI bundle content itself; this only declares the site's supported languages.