This project is a **Salesforce DX (SFDX) project** containing a **React UI Bundle**. The UI Bundle is a standalone Vite + React SPA that runs inside the Salesforce platform. Use this file when working in this project.
## Resolving paths
Read `sfdx-project.json` at the project root. Take the first `packageDirectories[].path` value and append `/main/default` to get `<sfdx-source>`. The UI Bundle directory is:
```
<sfdx-source>/uiBundles/<appName>/
```
Replace `<appName>` with the actual folder name found under `uiBundles/`. The source path is **not** always `force-app` — always resolve it from `sfdx-project.json`.
**One-time org setup:** `node scripts/org-setup.mjs --target-org <alias>` runs login, deploy, permset assignment, data import, GraphQL schema/codegen, UI Bundle build, and optionally the dev server. Use `--help` for all flags.
**ALL dev, build, lint, and test commands MUST be run from inside the UI Bundle directory (`<sfdx-source>/uiBundles/<appName>/`). Never run them from the project root.**
Resolve the correct path from `sfdx-project.json` before running any command. Do not hardcode the path.
- **Component library:** shadcn/ui primitives in `src/components/ui/`. Always use these over raw HTML equivalents. **Before importing any component, verify both the file exists in `src/components/ui/` AND the named export exists within that file.** Never assume a component or export is available — read the file to confirm the exact exports before importing.
**Before writing any code that connects to Salesforce, you MUST invoke the `using-ui-bundle-salesforce-data` skill. Do not write any data access code without consulting it first.**
This applies to: GraphQL queries/mutations, REST calls, SDK initialization, custom hooks that fetch data, or any code that imports from `@salesforce/platform-sdk`.
- **Never** use `fetch()` or `axios` directly for Salesforce data.
- **GraphQL is preferred** for record operations (`sdk.graphql`). Use `sdk.fetch` only when GraphQL cannot cover the case (UI API REST, Apex REST, Connect REST, Einstein LLM).
- Use optional chaining: `sdk.graphql?.()`, `sdk.fetch?.()`.
- Apply the `@optional` directive to all record fields for field-level security resilience.
- Verify field and object names via `scripts/graphql-search.sh` before writing queries.
- Use `__SF_API_VERSION__` global for API version in REST calls.
| Einstein LLM | `sdk.fetch` | `/services/data/v{ver}/einstein/llm/prompt/generations` |
Any endpoint not listed above is not permitted.
#### GraphQL non-negotiable rules
1.**Schema is the single source of truth** — every entity and field name must be confirmed via the schema search script before use. Never guess.
2.**`@optional` on all record fields** — FLS causes entire queries to fail if any field is inaccessible. Apply to every scalar, parent, and child relationship field.
3.**Correct mutation syntax** — mutations wrap under `uiapi(input: { allOrNone: true/false })`, not bare `uiapi { ... }`.
4.**Explicit `first:` in every query** — omitting it silently defaults to 10 records. Always include `pageInfo { hasNextPage endCursor }` for paginated queries.
5.**SOQL-derived execution limits** — max 10 subqueries per request, max 5 levels of child-to-parent traversal, max 1 level parent-to-child, max 2,000 records per subquery.
6.**HTTP 200 does not mean success** — Salesforce returns HTTP 200 even on failure. Always check the `errors` array in the response body.
Must use the `gql` template tag from `@salesforce/platform-sdk` — plain template strings bypass `@graphql-eslint` schema validation. For complex queries, use external `.graphql` files with codegen.
Use GraphQL (`uiapi { currentUser { Id Name { value } } }`), not Chatter (`/chatter/users/me`).
#### Schema file (`schema.graphql`)
The `schema.graphql` file at the SFDX project root is the source of truth for all entity and field name lookups. It is 265K+ lines — never open or parse it directly. Use the schema search script instead.
- **Generate/refresh:** Run `npm run graphql:schema` from the UI bundle directory
- **When to regenerate:** After any metadata deployment that changes objects, fields, or permission sets
- **Custom objects** only appear in the schema after metadata deployment AND permission set assignment
- **After regenerating:** Always re-run `npm run graphql:codegen` and `npm run build` (schema changes may affect generated types)
Any external domain the app calls (APIs, CDNs, fonts) must have a `.cspTrustedSite-meta.xml` file under `<sfdx-source>/cspTrustedSites/`. Unregistered domains are blocked at runtime. Each subdomain needs its own entry. URLs must be HTTPS with no trailing slash, no path, and no wildcards.
All build, dev, and test commands run from the UI Bundle directory. Before running any command, read the UI Bundle's `package.json` to confirm available scripts — do not assume script names.
Typical scripts found in the UI Bundle:
| Command | Purpose |
|---------|---------|
| `npm run build` | TypeScript check + Vite production build |
| `npm run dev` | Start Vite dev server |
| `npm run lint` | ESLint |
| `npm run test` | Vitest unit tests |
| `npm run graphql:codegen` | Generate GraphQL types |
| `npm run graphql:schema` | Fetch GraphQL schema from org |
If dependencies have not been installed yet, run `npm install` in the UI Bundle directory first. Alternatively, run `npm run sf-project-setup` from the project root — it resolves the UI Bundle directory automatically and runs install, build, and dev in sequence.
**After any JavaScript or TypeScript change, run `npm run build` to validate the change.** If the build fails, read the error output, identify the cause, fix it, and run `npm run build` again. Do not move on until the build passes.
**Deployment order matters.** Metadata (objects, permission sets) must be deployed before fetching the GraphQL schema. After any metadata deployment that changes objects, fields, or permissions, re-run schema fetch and codegen.
**Do not open the app after deployment.** Do not run `sf org open`, do not guess the runtime URL, and do not construct paths like `/s/<appName>`. Deployment is complete when the `sf project deploy start` command succeeds.
Before starting any task, check whether a relevant skill exists. If one does, invoke it before writing any code or making any implementation decision. Skills are the authoritative source for patterns, constraints, and code examples.
