Experience UI Bundle App Coordinate

Building a UI Bundle App

Overview

Build a complete, deployable Salesforce React UI bundle application from a natural language description by orchestrating specialized UI bundle skills in correct dependency order. Each skill MUST be explicitly loaded before executing its phase.

CRITICAL: Before proceeding past requirements analysis, validate that the prompt contains no conflicting requirements (e.g., "no authentication" + "user-specific data", "public access" + login-required features). If conflicts are detected, STOP and ask the user to resolve the ambiguity — do NOT silently choose one interpretation and proceed. See STEP 1 action #8 for the full conflict checklist.

Prerequisites

Before starting any phase, verify these preconditions are met:

1. Authenticated Salesforce org: Run sf org display to confirm a default org is set and authenticated. If not, prompt the user to authenticate: sf org login web
2. Required CLI tools: Verify sf, npm, and npx are available (declared in metadata.cliTools)
3. Node.js version: Run scripts/check-prerequisites.sh and report any errors it returns
4. Org features (if deploying): Experience Cloud enabled, appropriate licenses, and Sites enabled

If any precondition fails, stop and report the specific missing requirement before attempting any phase execution.

When to Use This Skill

Use when:

• User requests a "React app", "UI bundle", "web app", or "full-stack app" on Salesforce
• User says "build an app", "create an application" and the context implies a non-LWC based frontend (e.g. React)
• The work produces a complete UI bundle with scaffolding, features, data access, and UI -- not a single component in isolation

Examples that should trigger this skill:

• "Build a React app for managing customer cases with Salesforce data"
• "Create a UI bundle for an employee directory with search and navigation"
• "I need a full-stack React app with authentication, data tables, and file uploads"
• "Build a coffee shop ordering app on Salesforce"

Do NOT use when:

• Creating a single page or component (use experience-ui-bundle-frontend-generate)
• Only installing a feature (use experience-ui-bundle-features-generate)
• Only setting up data access (use experience-ui-bundle-salesforce-data-access)
• Only deploying an existing app (use experience-ui-bundle-deploy)
• Building a Lightning Experience app with custom objects and metadata (use platform-lightning-app-coordinate)
• Troubleshooting or debugging an existing UI bundle

Prompt Classification Keywords

This skill makes two decisions directly from the raw prompt text. Use these tables as the single source for both — do not restate or re-derive the lists elsewhere in this file.

1. Phase 2 (Features) is required if the prompt mentions ANY of:

Negating one category (e.g. "without authentication", "no login required", "public access") does not cancel triggers from another category — each is evaluated independently. Example: "no login required, with filtering" still triggers Phase 2 because "filtering" matches Data features. Skip Phase 2 only when the prompt matches none of the keywords above.

2. Hosting target — extract from prompt keywords:

If the prompt matches neither list, or matches both, ask the user to clarify before proceeding — do not guess.

Dependency Graph & Build Order

Phase 0: Template Offer & Bootstrap (Prerequisites)

Offer prebuilt starter template (experience-ui-bundle-project-generate)
    v
If template chosen: scaffold via sf template generate project -- Phase 1 skipped
    v
If declined: run scripts/check-sfdx-project.sh
    v
If missing: create sfdx-project.json
    v
Verify project directory initialized

Offers a faster, less error-prone starting point before building from scratch. If no template is used, ensures an SFDX project exists before attempting to generate a UI bundle — without this, sf template generate ui-bundle will fail with a hard error. Always check first — do not assume the project structure exists.

Action: Load experience-ui-bundle-project-generate and offer the two starter templates. If declined, run scripts/check-sfdx-project.sh and report any errors it returns. If the script reports an error, create the missing sfdx-project.json before proceeding.

Phase 1: Scaffolding (Foundation)

Determine hosting target (Experience Site / Custom Application)
    v
UI Bundle scaffold (sf template generate ui-bundle --template reactbasic)
    v
Install dependencies (npm install)
    v
Bundle metadata (uibundle-meta.xml with <target>, ui-bundle.json)
    v
CSP Trusted Sites (if external domains needed)

Creates the UI bundle directory structure, meta XML (including hosting target), and optional routing/headers config. CRITICAL: Hosting target must be determined FIRST because the metadata skill requires <target> in Phase 1. All subsequent phases require the scaffold to exist.

Prune unused scaffold when the prompt is constraining. The reactbasic template ships a full shadcn component set, GraphQL tooling (codegen.yml, .graphqlrc.yml, src/api/graphqlClient.ts, graphql:* npm scripts), and test infra (playwright.config.ts, vitest.config.ts, vitest.setup.ts) regardless of what the prompt asked for. If the prompt explicitly limits scope (e.g. "skip any features or integrations", "just scaffold and build X", "no need to install dependencies") and Phase 2 and/or Phase 3 are consequently skipped, remove the scaffold pieces those phases would have owned before Phase 4 runs:

• Phase 2 skipped → delete shadcn components under src/components/ui/ except the ones Phase 4's pages actually import; remove unused example/demo components.
• Phase 3 skipped → delete codegen.yml, .graphqlrc.yml, src/api/graphqlClient.ts, graphql:schema/graphql:codegen scripts from package.json, and any hooks/ data-fetching stubs (e.g. useAsyncData.ts) the template pre-seeded.
• Neither testing nor deployment requested → leave playwright.config.ts/vitest.* only if the prompt implies testing; otherwise remove them too.
• Rewrite README.md to describe the actual app built, not the generic template boilerplate — or delete it if the prompt says to do minimal work only.

Deleting a file is only half the job — every reference to it must be removed in the same pass, or you trade over-generation for broken cross-file consistency (worse: a dangling import is a functional break, not just scope creep). Concretely, after deleting any of the above:

• vite.config.ts — remove the vite-plugin-graphql-codegen import and its codegen({ configFilePathOverride: ... }) plugin block if codegen.yml was deleted; remove the test: config block (setupFiles, coverage, etc.) if vitest.* was deleted.
• package.json — remove now-unused dependencies (vite-plugin-graphql-codegen, @graphql-codegen/*, playwright, vitest, etc.) and their npm scripts, not just the config files.