/experience-lds-best-practices-apply

name: experience-lds-best-practices-apply
description: "Use when reviewing or implementing Lightning Data Service best practices in an LWC (.js, .html, .js-meta.xml) — UIAPI vs Apex, refreshApex / notifyRecordUpdateAvailable, @salesforce/schema imports, LDS record-form data patterns. TRIGGER on \"apply LDS best practices to this LWC\", \"review this LWC for LDS best-practice issues\", \"review this component for Lightning Data Service issues\", \"UIAPI or Apex for this data?\", \"fix stale data after record save\", \"sync LDS cache\", \"use @salesforce/schema for field names\", \"choose between getRecord and Apex\". DO NOT TRIGGER when building a new LWC (use experience-lwc-generate), applying SLDS design tokens (use design-systems-slds-apply), picking or wiring a `lightning-*` base component's props/events/slots generically (use experience-lwc-base-components-integrate — this skill covers only the LDS data-layer rationale, even when the fix involves a base record form), or for security / RTL / accessibility reviews (separate passes)."
metadata:
  version: "1.0"
  domains: ["Experience", "Platform"]
  relatedSkills:
    - design-systems-slds-apply
    - experience-lwc-base-components-integrate
    - experience-lwc-generate

<!-- adk-managed-skill -->

Applying LDS Best Practices

Apply the Lightning Data Service guidelines to a Lightning Web Component. Three pillars: **data consistency**, **referential integrity**, and **UIAPI vs Apex**. Focused on the UI API path — GraphQL and upstream data-requirements analysis are handled out-of-band.

When to Use

• Reviewing a component's data layer for LDS compliance (hand-rolled forms, stringly-typed field names, un-synchronized Apex + LDS, Apex overuse).
• Implementing CRUD on standard or custom objects.
• Deciding between `getRecord`, `getRecords`, `createRecord`, `updateRecord`, `deleteRecord`, base record form components, or Apex.
• Fixing stale-data bugs after record mutation.
• Adding schema imports (`@salesforce/schema/...`) to replace hard-coded field/object names.

Do NOT use this skill for:

• GraphQL query/mutation generation — handled out-of-band today.
• Upstream data-requirements discovery — handled out-of-band today.
• SLDS class / design-token work (use `design-systems-slds-apply`).
• Accessibility, security, or RTL review — those are separate passes run with their own tooling.

Prerequisites

• Component path.
• Understanding of the component's data operations (read / write / both) and whether Apex is already involved.
• Access to the org's schema for `@salesforce/schema` imports (Setup → Object Manager → `<Object>` → Details → API Name; or, when GraphQL serves the read, an SDL pulled from the target org).

Knowledge Bases

• [references/lds-expert.md](references/lds-expert.md) — authoritative LDS knowledge (patterns, adapters, caching, mutation flows).
• [references/lds-data-consistency.md](references/lds-data-consistency.md) — cache invalidation, `refreshApex`, `notifyRecordUpdateAvailable`, wire result propagation.
• [references/lds-referential-integrity.md](references/lds-referential-integrity.md) — `@salesforce/schema` imports, field constants, object-name resolution, and their propagation through refactors.

**Per-adapter API reference** — [references/adapter-apis.md](references/adapter-apis.md) holds Syntax / Parameters / Returns / Usage for every UI API adapter, grouped by family (`uiRecordApis`, `uiListsApis`, `uiRelatedListApis`, `uiObjectInfoApis`). Each adapter is a `` # `<name>` `` block; grep for the backticked name (e.g. `` # `getRecord` ``) to jump to its entry. Read this before wiring an adapter; do not paraphrase from memory.

**Type catalog** — [references/wire-adapter-types.md](references/wire-adapter-types.md) holds every type the adapters return (`Record`, `ObjectInfo`, `FieldValue`, etc.), grouped by category and rendered with the same formatter the legacy MCP tool used. Grep for `## <TypeName>` to jump to a specific entry.

Read the applicable reference before editing code.

Core Principles

1. Prefer **LDS/UIAPI** for CRUD on standard and custom objects. Use Apex **only** when business logic or bulk operations exceed LDS capabilities. 2. Always keep rendered data fresh with `refreshApex(wiredResult)` **or** `notifyRecordUpdateAvailable([{ recordId }])` after any mutation. 3. Import object and field references from `@salesforce/schema` — not string literals. This protects the component against metadata renames. 4. Favor base record form components (`lightning-record-form`, `lightning-record-edit-form`, `lightning-record-view-form`) for single-record UIs. They ship with validation, SLDS styling, accessibility, and field-level security.

Review Checklist

Answer **Yes / No** to each. Any **Yes** triggers a refactor.

1. Hand-rolling forms instead of base components

• Does the component implement a custom form for single-record CRUD where `lightning-record-form`, `lightning-record-edit-form`, or `lightning-record-view-form` would suffice?
• Does validation logic duplicate what base record form components provide natively?
• Are standard SLDS styles recreated manually instead of leveraging the styling baked into base components?

2. Not importing references

• Are object or field API names referenced as hard-coded strings?
• In templates, are field values accessed directly via expressions like `record.data.fields.Name.value` without schema imports?
• Does the JS file lack any `@salesforce/schema` import even though it interacts with Salesforce fields?

3. Mixing Apex and LDS without synchronization

• Does the component read via LDS and mutate the same record through Apex without a subsequent cache refresh?
• Does it fetch through Apex yet rely on the LDS cache for display without synchronizing after updates?
• Do multiple data sources touch the same object without an explicit refresh strategy?

4. Overusing Apex

• Does the component call Apex solely to retrieve or update a