/experience-ui-bundle-salesforce-data-access

name: experience-ui-bundle-salesforce-data-access
description: "MUST activate when a uiBundles/*/src/ project does ANY Salesforce record operation — reading, creating, updating, deleting, or caching/refreshing query results. Triggers: code importing @salesforce/platform-sdk, calls to sdk.graphql.query / sdk.graphql.mutate / sdk.fetch, *.graphql files, stale data needing a force-refresh, or wiring up a UI bundle's data layer to read, write, or refresh Salesforce records. The default for new read/write work is the Read/Write workflow with the current @salesforce/platform-sdk API; only follow the migration path when EXISTING code already uses the old @salesforce/sdk-data callable form. Not for building app shell/UI, styling, file upload, or auth/search scaffolding — use the other ui-bundle-* skills. DO NOT TRIGGER when: OAuth setup, schema changes, Bulk/Tooling/Metadata API, or declarative automation."
metadata:
  cliTools:
    - tool: ["node"]
      semver: ">=18.0.0"
    - tool: ["npm"]
      semver: ">=9.0.0"
    - tool: ["npx"]
      semver: ">=9.0.0"
    - tool: ["sf"]
      semver: ">=2.0.0"
  relatedSkills:
    - "platform-metadata-deploy"
  version: "2.1"

Salesforce Data Access (UI bundles)

All Salesforce data access in a UI bundle goes through the **`@salesforce/platform-sdk`** data SDK. The SDK handles auth, CSRF, and base-URL resolution, and — on the WebApp surface — caches every GraphQL query by default.

This file is the **workflow + guardrail spine**. Depth lives in linked docs:

• **[references/graphiti-cli.md](references/graphiti-cli.md)** — the **`graphiti` CLI** (`sf-gql-*`

commands) that compiles a small JSON spec into a schema-correct, guardrail-applied query + variables + types. The preferred way to author the GraphQL in steps below; falls back to the schema-grep script when unavailable.

• **[references/sdk-api.md](references/sdk-api.md)** — the new call API: `query`/`mutate`,

`QueryResult`, typing, error-handling stances.

• **[references/caching.md](references/caching.md)** — on-by-default cache + the **two refresh

modes** (`result.refresh`/`subscribe` vs per-call `cacheControl`).

• **[references/graphql-hand-authoring.md](references/graphql-hand-authoring.md)** — schema lookup, read /

mutation templates, every platform guardrail (`@optional`, pagination, limits, semi-join, wrappers, error table…).

• **[references/rest-and-integration.md](references/rest-and-integration.md)** — `sdk.fetch`,

the supported-API allowlist, and the reactive/lifecycle integration patterns.

• **[references/migration.md](references/migration.md)** — old `@salesforce/sdk-data` callable code

→ new namespace. The **only** place the dead API appears as usable code.

The one-paragraph mental model

`const sdk = await createDataSDK()`. Then `sdk.graphql` is a **namespace**, not a function: **`sdk.graphql!.query({...})`** for reads, **`sdk.graphql!.mutate({...})`** for writes. On WebApp, **every `query()` is cached by default** (300s). HTTP 200 never means success — always check `result.errors`. Verify every entity and field against the schema before you query it: one unverified field fails the *whole* query at runtime, and `schema.graphql` is too large to eyeball — look it up.

import { createDataSDK, gql } from "@salesforce/platform-sdk"; // gql tags the query string so codegen + eslint validate it

const sdk = await createDataSDK();
const result = await sdk.graphql!.query({ query: GET_ACCOUNTS, variables });
if (result.errors?.length) throw new Error(result.errors.map((e) => e.message).join("; "));
const rows = result.data?.uiapi?.query?.Account?.edges?.map((e) => e.node) ?? []; // unwrap edges/node; read field values via .value

Typed call params (`query<GetAccountsQuery, GetAccountsQueryVariables>`), the `CacheControl` type, and `NodeOfConnection<T>` (extracts a node type from a Connection for clean typing) all live in [references/sdk-api.md](references/sdk-api.md).

> **This changed (breaking — PR #502).** The previous callable `sdk.graphql(...)` form and the > previous package name are **dead** — the code above is the only correct form. If you encounter > the old API in existing code (or a stale `dist/` artifact), don't copy it; convert it per > [Working on existing code](#working-on-existing-code-migration). > > **`sdk.graphql!` is WebApp-only.** The non-null assertion above is correct *only* if the > bundle runs solely on WebApp. On other surfaces it can crash — decide before you write it. > See **[Surfaces — `!` vs guard](#surfaces--sdkgraphql-vs-guard)** below.

---

Surfaces — `sdk.graphql!` vs guard

`createDataSDK()` runs on multiple surfaces, and **`sdk.graphql` / `sdk.fetch` are genuinely optional** (typed `graphql?: …`). Whether you may assert them with `!` depends entirely on where the bundle runs — this is the one surface decision that turns into a *runtime crash* if you get it wrong, so make it explicitly before writing any `query`/`mutate` call:

| Surface(s) | `sdk.graphql` | Write | |---|---|---| | **WebApp only** | always present | `sdk.graphql!.query({...})` — `!` is safe; every shipped WebApp consumer uses it | | **Mosaic / OpenAI / MCPApps** (or any bundle that *might* run off-WebApp) | can be `undefined` | **guard first** (`if (!sdk.graphql) return …`), then call |

Rule of thumb: **if you cannot prove the bundle is WebApp-only, guard.** A bare `sdk.graphql!` that later ships to another surface throws `Cannot read properties of undefined` at runtime — TypeScript won't catch it because `!` silences exactly that check (same applies to `sdk.fetch!`). The portable guard snippet lives in [references/sdk-api.md](references/sdk-api.md#sdkgraphql-vs-guard).

---

Step 0 — Route the task

| The task is… | Go to | |---|---| | Read records | **[Read workflow](#read-workflow)** below | | Create / update / delete records | **[Write workflow](#write-workflow)** below | | Object/field metadata, picklist values, related-list metadat