Generating Ui Bundle Metadata

UI Bundle Metadata

Scaffolding a New UI Bundle

Use sf template generate ui-bundle to create new apps — not create-react-app, Vite, or other generic scaffolds.

Always pass `--template reactbasic` to scaffold a React-based bundle.

UI bundle name (`-n`): Alphanumerical only — no spaces, hyphens, underscores, or special characters.

Example:

sf template generate ui-bundle -n CoffeeBoutique --template reactbasic

After generation: 1. Replace all default boilerplate — "React App", "Vite + React", default <title>, placeholder text 2. Populate the home page with real content (landing section, banners, hero, navigation) 3. Update navigation and placeholders (see the building-ui-bundle-frontend skill) 4. Configure a hosting target — a UI bundle without a <target> in its meta XML will not be visible in the org. Use generating-ui-bundle-custom-app for internal (App Launcher) apps or generating-ui-bundle-site for external (Experience Site) apps.

Always install dependencies before running any scripts in the UI bundle directory.

---

UIBundle Bundle

A UIBundle bundle lives under uiBundles/<AppName>/ and must contain:

• <AppName>.uibundle-meta.xml — filename must exactly match the folder name
• A build output directory (default: dist/) with at least one file

Meta XML

Required fields: masterLabel, version (max 20 chars), isActive (boolean). Optional: description (max 255 chars), target.

Target Field

The <target> element specifies where the UI bundle is hosted:

A <target> is required for the app to be accessible in a Salesforce org. A UI bundle deployed without a target will not appear anywhere — no App Launcher entry, no Experience Site URL. Always pair the bundle with one of:

• generating-ui-bundle-site (for Experience target)
• generating-ui-bundle-custom-app (for CustomApplication target)

Example with Experience target:

<?xml version="1.0" encoding="UTF-8"?>
<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>propertyrentalapp</masterLabel>
    <description>A Salesforce UI Bundle.</description>
    <isActive>true</isActive>
    <version>1</version>
    <target>Experience</target>
</UIBundle>

Example with CustomApplication target:

<?xml version="1.0" encoding="UTF-8"?>
<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>propertymanagementapp</masterLabel>
    <description>A Salesforce UI Bundle.</description>
    <isActive>true</isActive>
    <version>1</version>
    <target>CustomApplication</target>
</UIBundle>

ui-bundle.json

Optional file. Allowed top-level keys: outputDir, routing, headers.

Constraints:

• Valid UTF-8 JSON, max 100 KB
• Root must be a non-empty object (never {}, arrays, or primitives)

Path safety (applies to outputDir and routing.fallback): Reject backslashes, leading / or \, .. segments, null/control characters, globs (*, ?, **), and %. All resolved paths must stay within the bundle.

outputDir

Non-empty string referencing a subdirectory (not . or ./). Directory must exist and contain at least one file.

routing

If present, must be a non-empty object. Allowed keys: rewrites, redirects, fallback, trailingSlash, fileBasedRouting.

• trailingSlash: "always", "never", or "auto"
• fileBasedRouting: boolean
• fallback: non-empty string satisfying path safety; target file must exist
• rewrites: non-empty array of { route?, rewrite } objects — e.g., { "route": "/app/:path*", "rewrite": "/index.html" }
• redirects: non-empty array of { route?, redirect, statusCode? } objects — statusCode must be 301, 302, 307, or 308

headers

Non-empty array of { source, headers: [{ key, value }] } objects.

Example:

{
  "routing": {
    "rewrites": [{ "route": "/app/:path*", "rewrite": "/index.html" }],
    "trailingSlash": "never"
  },
  "headers": [
    {
      "source": "/assets/**",
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
    }
  ]
}

Never suggest: {} as root, empty "routing": {}, empty arrays, [{}], "outputDir": ".", "outputDir": "./".

---

CSP Trusted Sites

Salesforce enforces Content Security Policy headers. Any external domain not registered as a CSP Trusted Site will be blocked (images won't load, API calls fail, fonts missing).

When to Create

Whenever the app references a new external domain: CDN images, external fonts, third-party APIs, map tiles, iframes, external stylesheets.

Steps

1. Identify external domains — extract the origin (scheme + host) from each external URL in the code 2. Check existing registrations — look in force-app/main/default/cspTrustedSites/ 3. Map resource type to CSP directive:

Always also set isApplicableToConnectSrc to true for preflight/redirect handling.

4. Create the metadata file — follow implementation/csp-metadata-format.md for the .cspTrustedSite-meta.xml format. Place in force-app/main/default/cspTrustedSites/.

CSP Trusted Site Metadata — Implementation Guide

File location

force-app/main/default/cspTrustedSites/{Name}.cspTrustedSite-meta.xml

The cspTrustedSites/ directory must be a direct child of force-app/main/default/. Create it if it does not exist.

---

File naming convention

The file name must match the <fullName> value inside the XML, with .cspTrustedSite-meta.xml appended.

Naming rules:

• Use PascalCase with underscores separating words (e.g. Google_Fonts_Static)
• Name should describe the provider and resource type (e.g. Pexels_Videos, not just Pexels)
• Must be unique across the org
• Maximum 80 characters

---

XML template

<?xml version="1.0" encoding="UTF-8" ?>
<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{UNIQUE_NAME}</fullName>
    <description>{DESCRIPTION}</description>
    <endpointUrl>{HTTPS_ORIGIN}</endpointUrl>
    <isActive>true</isActive>
    <context>All</context>
    <isApplicableToConnectSrc>{true|false}</isApplicableToConnectSrc>
    <isApplicableToFontSrc>{true|false}</isApplicableToFontSrc>
    <isApplicableToFrameSrc>{true|false}</isApplicableToFrameSrc>
    <isApplicableToImgSrc>{true|false}</isApplicableToImgSrc>
    <isApplicableToMediaSrc>{true|false}</isApplicableToMediaSrc>
    <isApplicableToStyleSrc>{true|false}</isApplicableToStyleSrc>
</CspTrustedSite>

---

Field reference

Reference: CspTrustedSite — Salesforce Object Reference

---

CSP directive mapping

---

Common external domains and their directives

Use this table as a quick reference when adding new domains:

---

Complete examples

Image CDN (Unsplash)

<?xml version="1.0" encoding="UTF-8" ?>
<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Unsplash_Images</fullName>
    <description>Allow access to Unsplash image content for static app media</description>
    <endpointUrl>https://images.unsplash.com</endpointUrl>
    <isActive>true</isActive>
    <context>All</context>
    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
    <isApplicableToFontSrc>false</isApplicableToFontSrc>
    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
    <isApplicableToImgSrc>true</isApplicableToImgSrc>
    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
</CspTrustedSite>

REST API (Open-Meteo weather)

<?xml version="1.0" encoding="UTF-8" ?>
<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Open_Meteo_API</fullName>
    <description>Allow access to Open-Meteo weather forecast API</description>
    <endpointUrl>https://api.open-meteo.com</endpointUrl>
    <isActive>true</isActive>
    <context>All</context>
    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
    <isApplicableToFontSrc>false</isApplicableToFontSrc>
    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
    <isApplicableToImgSrc>false</isApplicableToImgSrc>
    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
</CspTrustedSite>

Font provider (Google Fonts — requires two entries)

Google Fonts needs two CSP entries because CSS is served from fonts.googleapis.com and font files from fonts.gstatic.com:

Entry 1: Stylesheets

<?xml version="1.0" encoding="UTF-8" ?>
<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Google_Fonts</fullName>
    <description>Allow access to Google Fonts stylesheets for custom typography</description>
    <endpointUrl>https://fonts.googleapis.com</endpointUrl>
    <isActive>true</isActive>
    <context>All</context>
    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
    <isApplicableToFontSrc>false</isApplicableToFontSrc>
    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
    <isApplicableToImgSrc>false</isApplicableToImgSrc>
    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
    <isApplicableToStyleSrc>true</isApplicableToStyleSrc>
</CspTrustedSite>

Entry 2: Font files

<?xml version="1.0" encoding="UTF-8" ?>
<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Google_Fonts_Static</fullName>
    <description>Allow access to Google Fonts static files for font loading</description>
    <endpointUrl>https://fonts.gstatic.com</endpointUrl>
    <isActive>true</isActive>
    <context>All</context>
    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
    <isApplicableToFontSrc>true</isApplicableToFontSrc>
    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
    <isApplicableToImgSrc>false</isApplicableToImgSrc>
    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
</CspTrustedSite>

Map tiles (OpenStreetMap)

<?xml version="1.0" encoding="UTF-8" ?>
<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>OpenStreetMap_Tiles</fullName>
    <description>Allow access to OpenStreetMap tile images for map rendering</description>
    <endpointUrl>https://tile.openstreetmap.org</endpointUrl>
    <isActive>true</isActive>
    <context>All</context>
    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
    <isApplicableToFontSrc>false</isApplicableToFontSrc>
    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
    <isApplicableToImgSrc>true</isApplicableToImgSrc>
    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
</CspTrustedSite>

Geocoding API (Nominatim)

<?xml version="1.0" encoding="UTF-8" ?>
<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>OpenStreetMap_Nominatim</fullName>
    <description>Allow access to OpenStreetMap Nominatim geocoding API</description>
    <endpointUrl>https://nominatim.openstreetmap.org</endpointUrl>
    <isActive>true</isActive>
    <context>All</context>
    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
    <isApplicableToFontSrc>false</isApplicableToFontSrc>
    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
    <isApplicableToImgSrc>false</isApplicableToImgSrc>
    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
</CspTrustedSite>

---

Endpoint URL rules

Each subdomain needs its own entry. For example, fonts.googleapis.com and fonts.gstatic.com are separate entries.

---

When a service requires multiple domains

Some services split resources across multiple subdomains. Create one CSP Trusted Site per domain:

---

Troubleshooting CSP violations

If the browser console shows a CSP error like:

Refused to load the image 'https://example.com/image.png' because it violates
the following Content Security Policy directive: "img-src 'self' ..."

1. Extract the blocked origin from the URL (e.g. https://example.com). 2. Identify the directive from the error message (e.g. img-src → isApplicableToImgSrc). 3. Check if a CSP Trusted Site already exists for that origin. 4. If not, create one using this skill. 5. Deploy the metadata and refresh the page.

---

Common mistakes