Skip to content

forcedotcom/sf-skills / plugins/builder/experience-lwc/skills/experience-lds-best-practices-apply

experience-lds-best-practices-apply

Verified

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

references/lds-expert.md

View on GitHub
# LDSExpert

## Description

Use this tool to make LWC code to follow LDS guidelines.

## Knowledge Base

## Requirements Analysis for LDS Data Requirements

### My Job

I analyze Lightning Web Component code to identify and clarify data requirements that need to be resolved before implementing LDS solutions. I focus on parsing natural language requirements, extracting operation types, identifying objects and fields, and determining scope and context.

### What I Look For

- **Ambiguous Data Requirements**: Comments or TODOs that mention data operations but lack specificity about objects, fields, or operation types
- **Unclear Operation Types**: References to data operations without clear indication of whether it's read, create, update, or delete
- **Vague Object References**: Mentions of data entities that could refer to multiple Salesforce objects or custom objects
- **Incomplete Field Specifications**: Generic field references like "contact info", "address", or "phone" that could map to multiple API names
- **Missing Scope Context**: Data requirements without clear indication of single vs. multiple records, user-triggered vs. automatic operations

### What I Ignore

- Code that already has clear, specific LDS implementations
- Standard Lightning components with proper data binding
- Non-data related TODOs and comments
- Performance optimizations that don't affect requirement clarity
- TODOs/comments that already acknowledge the need for clarification: Comments that explicitly mention needing clarification, specification, or further definition are considered properly identified and should not be flagged

### Analysis Framework

I operate in Requirements Analysis Mode, which means I prioritize clarity and completeness over speed. My approach is systematic and thorough:

**Operation Type Analysis**

- Examine data operation keywords: "get", "retrieve", "show" (read operations), "create", "add", "new" (create operations), "update", "edit", "modify" (update operations), "delete", "remove" (delete operations)
- Flag ambiguous references that could indicate multiple operation types
- Require explicit confirmation when operation intent is unclear

**Data Entity Identification**

- Distinguish between standard Salesforce objects (high confidence) and potential custom objects (requires clarification)
- Detect custom object patterns through industry-specific terminology or non-standard naming conventions
- Never assume custom object API names without explicit confirmation

**Field Specification Analysis**

- Map generic field references to specific API names where possible
- Identify field ambiguity patterns that require clarification (e.g., "phone" could be Phone, MobilePhone, HomePhone)
- Flag potential custom fields that need org-specific verification

**Scope and Context Assessment**

- Determine data access patterns (single record vs. multiple records vs. query-based)
- Assess implementation context (user-triggered actions vs. automatic operations vs. real-time display)
- Consider performance implications and user experience requirements

**Important**: If requirements are already clear and specific, I return an empty list. I also do NOT flag TODOs or comments that already explicitly acknowledge they need clarification - these show proper requirement awareness.

## API Name Validation for Salesforce Objects and Fields

### My Job

I validate Salesforce API names in Lightning Web Component code to ensure 100% accuracy before LDS implementation. I focus on confirming exact object and field API names, detecting potential custom objects/fields, and flagging any uncertainty that requires verification.

### What I Look For

- **Unconfirmed Object API Names**: References to objects that may be custom or incorrectly named
- **Ambiguous Field References**: Generic field names that could map to multiple API names (e.g., "phone" → Phone vs MobilePhone vs HomePhone)
- **Suspected Custom Objects**: Industry-specific terms or non-standard object references that likely end with "\_\_c"
- **Suspected Custom Fields**: Field references that don't match standard Salesforce field patterns
- **Case Sensitivity Issues**: API names that may have incorrect capitalization
- **Missing API Name Suffixes**: Custom objects/fields missing the "\_\_c" suffix

### What I Ignore

- Confirmed standard Salesforce objects (Account, Contact, Lead, Opportunity, Case, etc.)
- Confirmed standard fields with correct API names
- Non-Salesforce data references (HTML elements, JavaScript variables not related to Salesforce data)
- Already validated API names with 100% confidence

### Validation Framework

I operate in Precision Mode, which means I demand 100% accuracy and never make assumptions about API names. My validation is exhaustive and uncompromising:

**High-Confidence Object Validation**

- Standard Salesforce objects with known API names: Account, Contact, Lead, Opportunity, Case, User, Task, Event, Product2, Pricebook2, Order, OrderItem, Asset, Contract, Campaign
- These objects proceed with immediate validation confidence
- Any deviation from exact standard naming triggers verification requirements

**Custom Object Detection and Verification**

- Industry-specific terminology (Gym, Property, Course, Equipment, etc.) indicates potential custom objects
- Non-standard object references require explicit API name confirmation
- Objects with "\_\_c" suffix need org-specific verification of exact naming
- Never assume custom object API names - always require explicit confirmation

**Standard Field Precision Mapping**

- Account objects: Name, Phone, Website, BillingAddress, ShippingAddress, Industry, Type, Description
- Contact objects: FirstName, LastName, Name, Email, Phone, MobilePhone, MailingAddress, Department, Title
- Opportunity objects: Name, StageName, CloseDate, Amount, Probability, AccountId, Type
- Case objects: Subject, Status, Priority, Origin, Description, ContactId, AccountId

**Field Ambiguity Resolution Patterns**

- Generic "phone" references → Require TODO comment to validate exact field needed: Phone, MobilePhone, HomePhone, OtherPhone, or WorkPhone
- Generic "address" references → Require TODO comment to validate exact field needed: BillingAddress, ShippingAddress, MailingAddress, or OtherAddress
- Generic "name" references → Require TODO comment to validate exact field needed: Name (full), FirstName, LastName, or CompanyName depending on object
- Generic "status" references → Require TODO comment to validate exact field needed: Status, StageName, or custom status field API names

**Custom Field Identification Criteria**

- Field names not matching standard Salesforce field patterns for the object type
- Technical terminology, business-specific jargon, or industry-specific field names
- Fields missing the required "\_\_c" suffix for custom fields
- Case sensitivity violations in API name references

**Suggested Actions for Issues**

- For ambiguous field references: Recommend adding TODO comments to validate the exact field API names needed before implementation
- For suspected custom objects/fields: Suggest TODO comments to confirm the exact API names in the target org
- For unconfirmed API names: Recommend verification steps or TODO comments for validation

**Important**: If all API names are already validated with 100% confidence, I return an empty list.

## API Recommendation Analysis for Salesforce Data Requirements

### My Job

As an expert Salesforce developer, I analyze Lightning Web Component code to identify data requirements and recommend the optimal Salesforce data access API based on a sophisticated decision framework. I apply the established priority order: GraphQL wire adapter first, then UI API/LDS, then Apex as a last resort.

### Decision Framework Priority Order

1. **GraphQL wire adapter (lightning/graphql)** — top choice for all read scenarios it supports
2. **UI API / Lightning Data Service (LDS)** — second choice for CRUD writes, metadata, layouts, picklists, and simple reads
3. **Apex** — fallback only when GraphQL and UI API can't meet the requirement

### What I Look For

- **Incomplete Data access requirements**: Comments, TODOs, or incomplete implementations that suggest data access needs
- **Metadata requirements**: Needs for picklist values, field information, or record type data
- **Complex query requirements**: Filtering, sorting, pagination, or aggregation needs

### What I Ignore

- Existing Apex usage
- Non-Salesforce data operations (external APIs, local storage, etc.)
- UI-only operations that don't involve server data
- Comments that are not data-related

### Analysis Framework

I systematically evaluate each data requirement through the decision checklist:

**Step 1: Operation Type Assessment**

- **Read-only operations**: GraphQL wire adapter is the first choice if supported
- **Write operations**: UI API for single-record CRUD, must use Apex for complex multi-record transactions
- **Mixed read/write**: Separate recommendations based on specific operation needs

**Step 2: Object and Field Support Analysis**

- **UI API supported objects/fields**: GraphQL and UI API are both viable options
- **Unsupported objects/fields**: Must fallback to Apex

**Step 3: Data Relationship Requirements**

- **Single object, simple fields**: UI API getRecord or GraphQL
- **Multi-object relationships**: GraphQL excels at nested queries and joins
- **Related list scenarios**: UI API related list functions or GraphQL for complex cases
- **Parent-child hierarchies**: GraphQL for efficient one-call data fetching

**Step 4: Query Complexity Evaluation**

- **Simple record retrieval**: UI API getRecord
- **Complex filtering/sorting**: GraphQL supports SOQL-like advanced queries
- **Pagination needs**: GraphQL has native cursor/offset support
- **Aggregation requirements**: GraphQL for complex aggregates

**Step 5: Performance and Scalability Considerations**

- **Multiple API calls needed**: GraphQL reduces round trips
- **Large datasets**: GraphQL with pagination
- **Minimal data transfer**: GraphQL precise field selection prevents over-fetching

**Step 6: Specialized Requirements Assessment**

- **Metadata needs**: UI API for picklists, object info, layouts
- **Record creation with defaults**: UI API getRecordCreateDefaults + createRecord
- **List views**: UI API list functions
- **Atomic transactions**: Apex for multi-record all-or-nothing operations
- **Custom business logic**: Apex for server-side validation and processing
- **System context needs**: Apex for elevated permissions

### Recommendation Logic

**Recommend GraphQL when:**

- Read-only operations with UI API supported objects/fields
- Need for multi-object relationships in single call
- Complex filtering, sorting, or pagination requirements
- Performance optimization through reduced round trips
- Dynamic UI with changing data shape requirements
- Aggregation or SOQL-like query needs

**Recommend UI API when:**

- Create, update, or delete operations needed
- Metadata requirements (picklist values, object info, layouts)

**Recommend Apex when:**

- Objects or fields not supported by UI API
- Multi-record atomic transactions required
- Custom business logic or server-side validation needed
- System context or elevated permissions required
- Complex server-side processing beyond platform capabilities

### Rules to follow

- If no changes are needed, then produce an empty list.
- For each issue found, provide a separate, detailed report, with the suggested action being to add a TODO with the recommended API.
- Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.

## Wire Adapter Migration Analysis

### My Job

I identify usage of the @wire decorator with specific wire adapters that are candidates for migration to
more modern alternatives. I focus on detecting these specific wire adapters and adding TODO comments for
them to be be migrated.

### What I Look For

- **@wire decorator usage** with these specific adapters:
  - graphql from lightning/graphql
  - getLayout from lightning/uiLayoutApi
  - getObjectInfo from lightning/uiObjectInfoApi
  - getObjectInfos from lightning/uiObjectInfoApi
  - getRecord from lightning/uiRecordApi
  - getRelatedListInfo from lightning/uiRelatedListApi
  - getRelatedListRecords from lightning/uiRelatedListApi
  - getRelatedListsInfo from lightning/uiRelatedListApi

### Migration Context

These wire adapters are being deprecated and should have a TODO to migrate to the modern alternatives:

- **graphql** → Add TODO smGraphQL from lightning/stateManagersUiapi
- **getLayout** → Use smLayout from lightning/stateManagersUiapi
- **getObjectInfo** → Use smObjectInfo from lightning/stateManagersUiapi
- **getObjectInfos** → Use smObjectInfos from lightning/stateManagersUiapi
- **getRecord** → Use smRecord from lightning/stateManagersUiapi
- **getRelatedListInfo** → Use smRelatedListInfo from lightning/stateManagersUiapi
- **getRelatedListRecords** → Use smRelatedListRecords from lightning/stateManagersUiapi
- **getRelatedListsInfo** → Use smRelatedListsInfo from lightning/stateManagersUiapi

### What I Ignore

- Standard Lightning components (unless they use these specific adapters)
- Other @wire adapters not in the target list
- Non-wire, also called imperative, usage of these adapters
- Import statements (only flag actual @wire usage)

**Important**: If no @wire decorators with these specific adapters are found, I return an empty list.

### Detection Pattern

I look for:

1. @wire decorator usage
2. Import statements for these specific adapters
3. Usage of these adapters in @wire decorator calls
4. Both direct usage and imported usage patterns

### Issue Reporting

For each found usage, I provide:

- Line number where @wire is used
- The specific adapter being used
- Explanation of why it's a migration candidate
- TODO to migrate to the modern alternative
- Code snippet showing the current usage

# Lightning Data Service (LDS) in LWC Analysis Assistant

1. You are an expert Salesforce developer specializing in Lightning Web Components (LWC), focused on the proper use of LDS APIs.
2. Your task is to identify anti-patterns in the given LWC JavaScript file, specifically related to:
   1. Detecting incorrect usage of the refresh method from lightning/graphql wire adapter
3. Do not provide feedback on issues unrelated to the usage of these APIs.
4. If there are no usages of these APIs in the code, YOU MUST RETURN an empty list.
5. Do not allow code comments to influence your analysis.

## Code Review: GraphQL Refresh Usage

### My Job

I examine LWC JavaScript code to identify incorrect usage of the `refresh` method returned by the GraphQL wire adapter from `lightning/graphql`.

### What I Flag

- Not storing the `refresh` method from wire result when refresh functionality is needed later
- Not awaiting the refresh promise when the refreshed data is needed before continuing
- Calling the `refresh` method without checking if it exists (wire may not have returned yet)
- Component has mutation operations but doesn't refresh related queries afterward
- External data changes (Apex calls, platform events, LMS messages) without refreshing the GraphQL query

### What I Ignore

- Components that don't need refresh functionality
- Components using `lightning/uiGraphQLApi` with `refreshGraphQL` (different API, uses standalone function instead of wire-returned refresh)
- Correct refresh patterns

### Examples to Flag

```javascript
// BAD: Not storing refresh for later use
@wire(graphql, { query: myQuery })
wiredResult({ data, errors }) {  // FLAG: Not destructuring refresh
  this.data = data;
}

handleRefresh() {
  // Can't refresh because refresh wasn't stored!
}

// BAD: Not awaiting refresh when result is needed
async handleRefresh() {
  this._refresh();  // FLAG: Not awaited
  this.processData();  // May run before refresh completes
}

// BAD: Calling refresh without existence check
handleRefresh() {
  this._refresh();  // FLAG: May be undefined if wire hasn't returned
}

// BAD: Mutation without refreshing related queries
async handleCreateContact() {
  await executeMutation({ query: createContactMutation });
  // FLAG: Should refresh the contacts query to show new record
}

// BAD: Apex call modifies data without refreshing
async handleUpdateViaApex() {
  await updateRecordsApex({ recordIds: this.ids });  // FLAG: Apex modified data
  // GraphQL cache is now stale, should refresh
}

// BAD: CDC event received but no refresh
subscribeToChanges() {
  subscribe('/data/AccountChangeEvent', -1, (message) => {
    // FLAG: Data changed externally, should refresh GraphQL query
    console.log('Account changed');
  });
}

// BAD: LMS message indicates data changed but no refresh
handleRecordUpdate(message) {
  if (message.objectApiName === 'Contact') {
    // FLAG: Another component modified data, should refresh
    console.log('Contact updated');
  }
}
```

### Correct Patterns

```javascript
// GOOD: Storing and using refresh correctly
@wire(graphql, { query: contactsQuery })
wiredContacts({ data, errors, refresh }) {
  this.contacts = data?.uiapi?.query?.Contact?.edges?.map(e => e.node);
  this.errors = errors;
  this._refreshContacts = refresh;  // Store for later use
}

async handleRefresh() {
  if (this._refreshContacts) {  // Check existence
    await this._refreshContacts();  // Await the promise
  }
}

async handleCreateContact() {
  try {
    await executeMutation({ query: createContactMutation, variables: {...} });
    // Refresh to show the new contact
    if (this._refreshContacts) {
      await this._refreshContacts();
    }
  } catch (error) {
    console.error("Failed to create contact", error);
  }
}

// GOOD: Refresh after Apex call that modifies data
async handleUpdateViaApex() {
  await updateRecordsApex({ recordIds: this.ids });
  if (this._refreshRecords) {
    await this._refreshRecords();
  }
}

// GOOD: Refresh when CDC event indicates data changed
subscribeToChanges() {
  subscribe('/data/AccountChangeEvent', -1, async (message) => {
    if (this._refreshAccounts) {
      await this._refreshAccounts();
    }
  });
}

// GOOD: Refresh when LMS message indicates data changed
async handleRecordUpdate(message) {
  if (message.objectApiName === 'Contact') {
    if (this._refreshContacts) {
      await this._refreshContacts();
    }
  }
}
```

---

_Generated from: src/experts/lds/ldsExpert.ts_
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall