afv-library/samples/ui-bundle-template-app-react-sample-b2x

Property Rental App

A property rental sample React UI Bundle for Salesforce Experience Cloud. Demonstrates property listings, maintenance requests, and a dashboard with an app shell designed for external-facing deployment. Built with React, Vite, TypeScript, and Tailwind/shadcn.

Table of Contents

1. What's Included
2. Prerequisites
3. Quick Start (Automated)
4. Step-by-Step Setup
   • 1. Install Dependencies
   • 2. Authenticate Your Org
   • 3. Deploy Metadata
   • 4. Assign Permission Sets
   • 5. Import Sample Data
   • 6. Generate GraphQL Types
   • 7. Rebuild the UI Bundle
   • 8. Deploy the UI Bundle
5. Org Configuration
   • Step 1: Assign a Role to Your Admin User
   • Step 2: Create and Configure the Community Profile
   • Step 3: Configure the Experience Cloud Site
   • Step 4: Configure the Guest User Profile
   • Step 5: Create Criteria-Based Sharing Rules for Guest Access
6. Local Development
7. Resources

---

What's Included

force-app/main/default/
├── classes/                # Apex Logic: Triggers, Auth, and Registration
│   ├── MaintenanceRequestTriggerHandler.cls
│   ├── TenantTriggerHandler.cls
│   └── UIBundle (Auth, Login, Registration, etc.)
├── cspTrustedSites/        # External resource security (Maps, Fonts, Avatars)
├── data/                   # Sample JSON data for "sf data import tree"
├── digitalExperienceConfigs/ # Experience Cloud site configurations
├── digitalExperiences/      # Experience Cloud site definitions
├── layouts/                # Page layouts for all 17 custom objects
├── networks/               # Experience Cloud network metadata
├── objects/                # 17 Custom Objects (Property, Tenant, Lease, etc.)
├── permissionsets/         # Property_Rental_Guest_User_Access (guest browsing)
├── sites/                  # Salesforce Sites configuration
├── triggers/               # Apex Triggers: MaintenanceRequest & Tenant
└── uiBundles/
    └── propertyrentalapp/  # React UI Bundle (source, config, tests)

---

Prerequisites

Before you begin, ensure the following are in place.

Tools

Tool	Minimum Version	Install
Salesforce CLI (sf)	v2+	npm install -g @salesforce/cli
Node.js	v22+	nodejs.org
Git	Any recent version	git-scm.com

Verify your Salesforce CLI version with:

sf --version

Salesforce Org Requirements

This project requires a Salesforce org with the following features and licenses. Developer Edition orgs do not include these by default. Use a sandbox, an org configured with add-ons, or request a pre-configured org from your Salesforce account team.

• Digital Experiences (Experience Cloud) enabled — required to deploy and run the Experience Cloud site. To verify, go to Setup > Digital Experiences > Settings and confirm "Enable Digital Experiences" is checked.
• Customer Community or Customer Community Plus user licenses — required to create community (portal) users. Customer Community Plus is recommended if you need record-level sharing via sharing rules.
• Salesforce Sites enabled — required for guest user access.

Note: If Digital Experiences is not yet enabled in your org, go to Setup > Digital Experiences > Settings, check "Enable Digital Experiences", set a domain name, and save. This action cannot be undone.

---

Quick Start (Automated)

Two npm scripts at the project root streamline getting started and deployment.

npm run sf-project-setup — installs the UI Bundle dependencies, builds the app, and starts the dev server (see Local Development).

npm run setup — automates the full setup: login, deploy metadata, assign permission sets, import sample data, fetch the GraphQL schema, run codegen, build the UI Bundle, and optionally launch the dev server:

npm run setup -- --target-org <alias>

Replace <alias> with your target org alias or username. Running without flags presents an interactive step picker. Pass --yes to skip it and run all steps immediately:

npm run setup -- --target-org <alias> --yes

Common Options

Option	Description
--skip-login	Skip browser login (auto-skipped if org is already connected)
--skip-deploy	Skip the metadata deploy step
--skip-permset	Skip permission set assignment
--skip-data	Skip data preparation and import
--skip-graphql	Skip GraphQL schema fetch and codegen
--skip-ui-bundle-build	Skip npm install and UI Bundle build
--skip-role	Skip role assignment to current user
--skip-self-reg	Skip Experience Cloud self-registration configuration
--skip-dev	Do not launch the dev server at the end
--permset-name <name>	Assign only a specific permission set (repeatable). Default: all sets in the project
--ui-bundle-name <name>	UI Bundle folder name under uiBundles/ (default: auto-detected)
-y, --yes	Skip interactive step picker and run all enabled steps immediately

For a full list of options:

npm run setup -- --help

Setup Configuration (scripts/org-setup.config.json)

The npm run setup script reads scripts/org-setup.config.json to control which steps run and how they behave. Each top-level section is optional — if a section is absent, the corresponding step is hidden from the interactive picker.

{
  "permsetAssignments": {
    "assignments": {
      "Property_Management_Access": { "assignee": "currentUser" },
      "Tenant_Maintenance_Access": { "assignee": "skip" },
      "Property_Rental_Guest_User_Access": {
        "assignee": "guestUser",
        "siteName": "propertyrentalapp"
      }
    }
  },
  "role": {
    "assignee": "currentUser",
    "roleName": "Admin"
  },
  "selfRegistration": {
    "siteName": "propertyrentalapp",
    "selfRegProfile": "Property Rental Prospect Profile",
    "accountName": "Property Rental Self-Registration"
  }
}

permsetAssignments.assignments

Each key is a permission set API name. The assignee value controls who it is assigned to:

Value	Behavior
"currentUser"	Assigns to the user running the script (resolved via sf org display)
"skip"	Explicitly skips this permission set
"guestUser"	Auto-resolves the site's guest user (requires siteName field on the same entry)
"user@org.com"	Assigns to a specific user by username

role

Assigns a role to the current user — a prerequisite for Experience Cloud self-registration. Only "currentUser" is supported as the assignee.

selfRegistration

Enables Experience Cloud self-registration by:

1. Setting <selfRegistration>true</selfRegistration> in the network metadata
2. Adding the specified profile to network member groups
3. Creating an Account record for self-registered users
4. Creating the NetworkSelfRegistration record

After the automated setup completes, proceed to Org Configuration for the manual steps that cannot be automated via CLI (profile cloning, site member configuration, guest user setup, and publishing the Experience Cloud site).

---

Step-by-Step Setup

Use this section if you prefer to run each step manually, or if the automated script is not available.

1. Install Dependencies

Install root-level project dependencies:

npm install

Install the UI Bundle dependencies and build it:

cd force-app/main/default/uiBundles/propertyrentalapp
npm install
npm run build
cd -

This produces the static bundle artifacts that are packaged into the Salesforce metadata. Having them built now means any deploy option in Step 3 is ready to run without an additional build step.

2. Authenticate Your Org

Log in to your target org using the Salesforce CLI. This opens a browser window for OAuth authentication:

sf org login web --alias <alias>

To verify the login was successful:

sf org display --target-org <alias>

If you are working with a sandbox, use:

sf org login web --alias <alias> --instance-url https://test.salesforce.com

3. Deploy Metadata

Option A: Deploy Everything (metadata + Experience Cloud site + UI Bundle)

Build the UI Bundle first, then deploy all source directories in a single command:

cd force-app/main/default/uiBundles/propertyrentalapp && npm run build && cd -
sf project deploy start --source-dir force-app --target-org <alias>

Option B: Deploy Metadata Only (objects, layouts, permission sets, Apex)

Use this approach for an initial deploy to verify metadata before deploying the Experience Cloud site:

sf project deploy start \
  --source-dir force-app/main/default/objects \
  --source-dir force-app/main/default/layouts \
  --source-dir force-app/main/default/permissionsets \
  --source-dir force-app/main/default/classes \
  --source-dir force-app/main/default/triggers \
  --source-dir force-app/main/default/cspTrustedSites \
  --target-org <alias>

Option C: Deploy Experience Cloud Site Only

sf project deploy start \
  --source-dir force-app/main/default/digitalExperienceConfigs \
  --source-dir force-app/main/default/digitalExperiences \
  --source-dir force-app/main/default/networks \
  --source-dir force-app/main/default/sites \
  --target-org <alias>

Option D: Deploy the UI Bundle Only

cd force-app/main/default/uiBundles/propertyrentalapp && npm run build && cd -
sf project deploy start --source-dir force-app/main/default/uiBundles --target-org <alias>

Deployment order matters. Deploy metadata (Option B) before deploying the Experience Cloud site (Option C). The site configuration depends on the custom objects and classes being present in the org.

4. Assign Permission Sets

Three permission sets are included in this project:

Permission Set	Purpose	Assign To
Property_Management_Access	Full CRUD access to all custom objects. Intended for property managers and admin users.	Internal users managing the app
Tenant_Maintenance_Access	Scoped read/write access for tenants. Allows creating and updating their own maintenance requests only.	Tenant community users
Property_Rental_Guest_User_Access	Read-only access to property objects for unauthenticated browsing. Includes Apex class access for auth flows.	Site guest user

Assign permission sets using the CLI:

# Assign Property_Management_Access to a specific user
sf org assign permset --name Property_Management_Access --on-behalf-of <username> --target-org <alias>

# Assign Tenant_Maintenance_Access to a tenant user
sf org assign permset --name Tenant_Maintenance_Access --on-behalf-of <username> --target-org <alias>

To assign to multiple users, repeat the command for each user, or use the automated script which assigns all permission sets to the running user by default.

5. Import Sample Data

Once the metadata has been successfully deployed:

sf data import tree --plan force-app/main/default/data/data-plan.json --target-org <alias>

The data plan imports records in dependency order: Contacts, Agents, Maintenance Workers, Properties, Tenants, Applications, Maintenance Requests, Notifications, Property Management Companies, Property Owners, Leases, Property Sales, Property Costs, Payments, KPI Snapshots, Property Listings, Property Images, and Property Features.

Note: If you re-run the import, duplicate records will be created. Wipe existing records first or use the --upsert flag if your plan supports it.

6. Generate GraphQL Types

After metadata is deployed, generate the GraphQL schema and TypeScript types for the UI Bundle. These are used to provide type-safe queries against the Salesforce GraphQL API.

cd force-app/main/default/uiBundles/propertyrentalapp
npm run graphql:schema   # Fetches schema from org → outputs schema.graphql
npm run graphql:codegen  # Generates TypeScript types → updates src/api/graphql-operations-types.ts
cd -

Prerequisite: The org must be authenticated and metadata must already be deployed before running these commands, as the schema is generated from the org's live metadata.

7. Rebuild the UI Bundle

Step 6 updates the generated GraphQL types in the UI Bundle source. Rebuild the app to compile those changes into the bundle before deploying:

cd force-app/main/default/uiBundles/propertyrentalapp
npm run build
cd -

8. Deploy the UI Bundle

Once the build is complete, deploy the UI Bundle to your org:

sf project deploy start --source-dir force-app/main/default/uiBundles --target-org <alias>

---

Org Configuration

The following steps must be completed manually in the Salesforce Setup UI. They configure Experience Cloud, user profiles, and data sharing for guest and community users. Complete these steps after the metadata and UI Bundle have been deployed.

License requirement: Your org must have Customer Community or Customer Community Plus user licenses available before you can complete these steps. Customer Community Plus licenses are required if you need ownership-based record sharing (Private OWD with sharing rules). Verify available licenses at Setup > Company Settings > Company Information, in the "User Licenses" section.

---

Step 1: Assign a Role to Your Admin User

Salesforce requires that the org's admin user has a role assigned before Experience Cloud sites can be created or managed. If your admin user already has a role, skip this step.

1. Go to Setup > Users > Roles.
2. Click Set Up Roles.
3. Click Add Role. Provide a label (e.g., CEO) and save.
4. From the role hierarchy, click the role you just created, then click Assign Users to Role.
5. Add your system administrator user and click Save.

Why this matters: Salesforce prevents users without a role in the hierarchy from owning Experience Cloud sites. This is a platform-level requirement, not specific to this app.

---

Step 2: Create and Configure the Community Profile

Community users require a profile that is based on one of the standard community profile templates. You will clone one of these templates and configure its permissions for this app.

2a. Clone the Base Profile

1. Go to Setup > Users > Profiles.
2. Locate either Customer Community User or Customer Community Login User.
   • Choose Customer Community Plus User if you need ownership-based record-level sharing.
3. Click Clone next to the profile. Give it a descriptive name such as Property Rental Prospect Profile.
4. Click Save.

2b. Edit the Cloned Profile

Open the newly cloned profile and configure the following settings.

Administrative Permissions:

Permission	Setting
API Enabled	Checked

Custom Object Permissions:

Set the following object-level access. After saving, also review field-level security for each object to ensure all relevant fields are readable.

Object	Read	Create	Edit	Delete
Agents (Agent__c)	✓
Applications (Application__c)	✓	✓	✓	✓
KPI Snapshots (KPI_Snapshot__c)	✓
Leases (Lease__c)	✓
Maintenance Requests (Maintenance_Request__c)	✓	✓	✓	✓
Maintenance Workers (Maintenance_Worker__c)	✓		✓
Notifications (Notification__c)	✓
Payments (Payment__c)	✓
Properties (Property__c)	✓
Property Costs (Property_Cost__c)	✓
Property Features (Property_Feature__c)	✓
Property Images (Property_Image__c)	✓
Property Listings (Property_Listing__c)	✓
Property Management Companies (Property_Management_Company__c)	✓
Property Owners (Property_Owner__c)	✓
Property Sales (Property_Sale__c)	✓
Tenants (Tenant__c)	✓

Apex Class Access:

Scroll to the Enabled Apex Class Access section and add the following classes. These classes handle authentication flows called by the UI Bundle:

• UIBundleAuthUtils
• UIBundleChangePassword
• UIBundleForgotPassword

Note: MaintenanceRequestTriggerHandler and TenantTriggerHandler are trigger handler classes that run in system context when DML operations are performed. They do not need to be explicitly enabled in community profiles.

2c. Configure View All for Property, Property Listing, Maintenance Worker

Tenants need to see all available properties and listings, not just records they own. Enable View All on these three objects for the community profile:

1. Go to Setup > Object Manager.
2. Search for and open Property.
3. Click Object Access in the left navigation.
4. Set the profile's access to allow viewing all records.
5. Repeat for Property Listing and Maintenance Worker.

• Note: the access for the Maintenance Worker is required for the MaintenanceRequestTriggerHandler to auto assign a worker on submission

2d. Configure Field Level Security for the Application

1. Go to Setup > Object Manager.
2. Search for and open Application.
3. Click Fields and Relationships in the left navigation.
4. Select the References__c field, then click Set Field-Level Security.
5. Enable the field to be "Visible" to the community profile.
6. Click Save.
7. Repeat for the following fields:

• Property__c
• Employment__c
• User__c
• Status__c
• Start_Date__c

---

Step 3: Configure the Experience Cloud Site

After deploying the Experience Cloud site metadata, configure its membership and self-registration settings.

1. In the App Launcher, open the Digital Experiences app (search for it if needed).
2. Find the Property Rental App site and click Workspaces.
3. Click the Administration tile.

Members

1. In the left navigation, click Members.
2. Under Select Profiles, add the cloned community profile (Property Rental Prospect Profile) to the Selected Profiles list.
3. Click Save.

Login & Registration

1. In the left navigation, click Login & Registration.
2. Check Allow customers and partners to self-register.
3. Under Registration, set:
   • Profile: Select your cloned community profile (Property Rental Prospect Profile).
   • Account: Select or create an account record to associate self-registered users with (e.g., a generic "Portal Account").
4. Click Save.

Guest User Profile

The site's guest user profile controls what unauthenticated visitors can see. You will configure this profile in Step 4. To navigate to it:

1. In the Administration area, click Preferences in the left navigation.
2. Click the link next to Guest user profile to open it directly.

---

Step 4: Configure the Guest User Profile

The guest user profile is auto-generated by Salesforce when an Experience Cloud site is created. It controls what unauthenticated visitors can access. Configure it to allow browsing of available properties only.

Open the guest user profile (linked from the site's Preferences page, as described above) and apply the following settings.

Administrative Permissions:

Permission	Setting
API Enabled	Checked

Security note: Enabling API access for the guest profile is required for the UI Bundle to make GraphQL API calls on behalf of unauthenticated users. Ensure that object-level and field-level permissions are restrictive (as listed below) to avoid exposing sensitive data.

Custom Object Permissions:

Guest users can only browse available properties and listings. All other objects are restricted.

Object	Read	Create	Edit	Delete
Properties (Property__c)	✓
Property Costs (Property_Cost__c)	✓
Property Features (Property_Feature__c)	✓
Property Images (Property_Image__c)	✓
Property Listings (Property_Listing__c)	✓
All other objects	—	—	—	—

Apex Class Access:

Add the following classes. These are required for the self-registration and login flows available to unauthenticated users:

• UIBundleLogin
• UIBundleRegistration

---

Step 5: Create Criteria-Based Sharing Rules for Guest Access

By default, Salesforce does not expose any records to guest users. A criteria-based sharing rule is included in the deployed metadata to make properties visible to unauthenticated site visitors.

Organization-Wide Defaults (OWD): Criteria-based sharing rules for guest users only work correctly when the object's OWD is set to Public Read Only or Private. Verify your OWD settings at Setup > Sharing Settings before proceeding.

Included Sharing Rule: Properties

The deployed metadata includes a sharing rule for Property__c (Property_Rental_App_Guest_User_Access) that grants Read access to the site's guest user for all properties with a non-empty Name field. This is deployed automatically with sf project deploy start.

Optional: Create Additional Sharing Rules

If you need to expose additional objects (e.g., Property Listings) to guest users, create sharing rules manually:

1. Go to Setup > Sharing Settings.
2. Scroll to the relevant object's sharing rules section and click New.
3. Configure the rule:
   • Rule Type: Select Guest user access, based on criteria
   • Criteria: Match records you want to expose (e.g., Status Equals Active)
   • Share with: Select Guests of the Property Rental App site
   • Access Level: Read Only
4. Click Save.

Note: The "Guests of [site name]" option only appears in the sharing rule target list after the Experience Cloud site has been created and saved. If you do not see it, confirm the site metadata has been deployed and the site exists in the org.

---

Local Development

Install project dependencies and start the dev server:

npm install
npm run sf-project-setup

This installs the UI Bundle dependencies, builds the app, and opens the dev server at http://localhost:5173. For manual build and test instructions, see the UI Bundle README.

---

Resources

• Salesforce Extensions Documentation
• Salesforce CLI Setup Guide
• Salesforce DX Developer Guide
• Salesforce CLI Command Reference
• Experience Cloud Developer Guide
• Salesforce DX Project Configuration