forcedotcom/sf-skills / plugins/builder/experience-react/skills/experience-ui-bundle-salesforce-data-access
experience-ui-bundle-salesforce-data-access
VerifiedMUST activate whenever a uiBundles/*/src/ project reads, writes, or displays Salesforce data — INCLUDING building a page, list, table, card grid, dashboard, or form that shows, filters, counts, or edits records of any object (e.g. Property__c, Account, Case), even when the prompt names only the UI or the object and never says query, GraphQL, or SDK. Records behind such a component come from Salesforce, so use this ALONGSIDE experience-ui-bundle-frontend-generate: that skill styles the component, this one wires its data. Also triggers on @salesforce/platform-sdk imports, sdk.graphql.query / mutate / sdk.fetch calls, *.graphql files, or stale data needing force-refresh. New read/write work uses the current @salesforce/platform-sdk API; migrate only EXISTING old @salesforce/sdk-data callable code. Not for pure styling/layout with no records, app shell, file upload, or auth/search scaffolding. DO NOT TRIGGER for OAuth, object/field schema changes, Bulk/Tooling/Metadata API, or declarative automation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 29.6 KB |
| references/caching.md | markdown | 8.8 KB |
| references/graphiti-cli.md | markdown | 19.5 KB |
| references/graphql-hand-authoring.md | markdown | 14.9 KB |
| references/migration.md | markdown | 6.0 KB |
| references/rest-and-integration.md | markdown | 6.7 KB |
| references/sdk-api.md | markdown | 4.9 KB |
| scripts/graphql-search.shexecutable | script | 7.6 KB |
references/sdk-api.md
View on GitHub# The Data SDK operational guide
> **Behavior mirror — `@salesforce/platform-sdk` `docs/data/`, as of v11.70.0.** When the package
> is installed, its shipped `docs/data/` folder is the authoritative, version-current source
> ([tier-2b](../SKILL.md#ground-the-sdk-behavior-on-the-installed-docs-tier-2b)) — let it win. This
> file restates that behavior as a self-contained fallback for when the folder is absent (older SDK,
> or a types-only build); it reflects the SDK version above and may lag a newer install.
The installed `@salesforce/platform-sdk` declarations own the current call contract: exports,
`query`/`mutate` signatures, options bags, result types, `CacheControl`, and
`NodeOfConnection`. Read `dist/core/data.d.ts` and `dist/data/index.d.ts` first and let them win
over this guide ([tier-2a](../SKILL.md#ground-the-sdk-contract-on-the-installed-types-tier-2a)).
For cache strategy see [caching.md](caching.md); for old `@salesforce/sdk-data` conversion see
[migration.md](migration.md).
This reference keeps only decisions and runtime behaviors that the declarations do not fully
express.
## `sdk.graphql!` vs guard
`sdk.graphql` is optional on surfaces that do not support data operations. Whether to assert it
after `createDataSDK()` is a surface decision:
```typescript
const result = await sdk.graphql!.query<...>({ query, variables });
```
Use `!` only if the bundle is WebApp-exclusive; otherwise guard. The spine's
[Surfaces](../SKILL.md#surfaces--sdkgraphql-vs-guard) table is the routing. A bare
`sdk.graphql!` that later ships to another surface throws `Cannot read properties of undefined`
at runtime, and TypeScript cannot catch it because `!` silences that check.
```typescript
// `!` form — WebApp-only bundles; every shipped WebApp consumer uses it.
const result = await sdk.graphql!.query<...>({ query, variables });
// Portable guard form — safe on every surface. Use when the bundle is not WebApp-exclusive.
if (!sdk.graphql) {
// No data SDK on this surface — degrade gracefully (render empty, throw, or feature-flag off).
return;
}
const result = await sdk.graphql.query<...>({ query, variables });
```
(The same `!`-vs-guard call applies to `sdk.fetch!`.)
## `QueryResult<T>` — the reactive query handle
`QueryResult` shape and core behavior belong to the installed TSDoc. Two behaviors it does not
spell out:
- Each `subscribe` is **independent** — unsubscribing one leaves the others live — and it does
**not** fire on registration, only on later snapshots. Set initial state from the awaited
snapshot, not from the subscriber.
- `result.refresh()` broadcasts the new snapshot to **all** current subscribers, not just the
caller.
*When* to reach for `subscribe`/`refresh` over the default cache, plus the uncached-surface
caveats, is a strategy call — see [caching.md](caching.md).
## `cacheControl` — the per-call cache policy
The installed `CacheControl` TSDoc defines the supported values and their behavior. It does not
name the `only-if-cached` miss error type or prescribe its handling:
An `only-if-cached` miss is not an exception — the Promise resolves and the miss surfaces on
`result.errors` as a `DataNotFoundError`. This is offline-first: a miss is **expected, not an
error**. Check `result.errors`, render an empty state, and **do not fall back to a network read**
— a fallback defeats the point of `only-if-cached`:
```typescript
const result = await sdk.graphql!.query({ query: GET_ACCOUNTS, variables, cacheControl: "only-if-cached" });
if (result.errors?.length) {
// cold cache — render the empty state. Do NOT fall back to the network; that defeats offline-first.
return renderEmptyState();
}
```
Which policy fits which goal (force-refresh button, offline-first, fast-changing data) is a
strategy call — see the decision matrix in [caching.md](caching.md).
## HTTP 200 ≠ success — always read `errors`
The installed TSDoc establishes that GraphQL and parse failures resolve through
`result.errors`. Choose the product-appropriate stance; all inspect `result.errors`:
```typescript
// Strict — any errors = failure
if (result.errors?.length) throw new Error(result.errors.map((e) => e.message).join("; "));
// Tolerant — log, use whatever data came back (partial success)
if (result.errors?.length) console.warn("GraphQL partial errors:", result.errors);
// Discriminated — fail only when NO data returned
if (!result.data && result.errors?.length) {
throw new Error(result.errors.map((e) => e.message).join("; "));
}
```
## Generated types
Run `npm run graphql:codegen` and use its generated operation types for **both** the
[Read workflow](../SKILL.md#read-workflow) (`query<Q, V>`) and the
[Write workflow](../SKILL.md#write-workflow) (`mutate<M, V>`). The installed declaration gives
the current generic placement; `NodeOfConnection` (read-side — it unwraps a Connection, which
only `query` returns) is defined there too.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |