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.
| [Git](https://git-scm.com/) | Any recent version | [git-scm.com](https://git-scm.com/) |
Verify your Salesforce CLI version with:
```bash
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.
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](#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:
```bash
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:
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.
> **After the automated setup completes**, proceed to [Org Configuration](#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.
This produces the static bundle artifacts that are packaged into the Salesforce metadata. Having them built now means any deploy option in [Step 3](#3-deploy-metadata) is ready to run without an additional build step.
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.
| `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 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.
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.
```bash
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:
```bash
cd force-app/main/default/uiBundles/propertyrentalapp
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.
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.
- **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](#step-4-configure-the-guest-user-profile). 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.
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.
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:
> **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:
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](force-app/main/default/uiBundles/propertyrentalapp/README.md).
