Skip to content

forcedotcom/sf-skills / plugins/builder/experience-react/skills/experience-ui-bundle-salesforce-data-access

experience-ui-bundle-salesforce-data-access

Verified

MUST 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.

FileKindSize
SKILL.mdskill md29.6 KB
references/caching.mdmarkdown8.8 KB
references/graphiti-cli.mdmarkdown19.5 KB
references/graphql-hand-authoring.mdmarkdown14.9 KB
references/migration.mdmarkdown6.0 KB
references/rest-and-integration.mdmarkdown6.7 KB
references/sdk-api.mdmarkdown4.9 KB
scripts/graphql-search.shexecutablescript7.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.
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall