Home / lwc / wire-service-patterns

wire-service-patterns

Use when designing or reviewing Lightning Web Components that use `@wire`, Lightning Data Service, UI API, or the GraphQL wire adapter, especially for reactive parameters, cache behavior, and refresh strategy. Triggers: 'wire service', 'refreshApex', 'reactive parameter', 'getRecord', 'wire vs imperative Apex', 'cacheable=true', 'notifyRecordUpdateAvailable', 'wired data is read-only', 'getPicklistValues recordTypeId'. NOT for forcing a refresh after DML — use lwc/lwc-wire-refresh-patterns. NOT for imperative Apex on a click — use lwc/lwc-imperative-apex.

• v1.2.0
• Salesforce Spring '25+
• Updated 2026-09-05
• Performance
• Reliability
• User Experience

• wire-service
• lightning-data-service
• refreshapex
• reactive-parameters
• graphql-wire
• cacheable-apex

Open the skill folder on GitHub

Use this skill when the LWC data path needs to be intentional rather than incidental. The wire service is excellent for declarative, cache-aware reads, but only if the component understands immutability, reactive parameters, and when wire adapters will or will not re-evaluate. Use it when the LWC is not updating when data changes—often because the wire adapter isn't re-evaluating or a refresh wasn't triggered.

Before Starting

• Is the component only reading Salesforce data, or does it also perform writes that should happen imperatively?
• Is the best data source a base component, a UI API wire adapter, an Apex wire adapter, or the GraphQL wire adapter?
• What event should actually refresh the data: parameter change, record change notification, or an explicit refresh call?

Questions to Ask Before Configuring

Ask these before the first @wire is written. Every row traces to a documented platform behaviour in references/gotchas.md that punishes the default assumption.

What a proper wire design adds over just making it work: the config's completeness, the copy boundary and the post-write refresh become three written decisions with a checker rule and a Jest assertion behind each, so a later edit that breaks one fails a test instead of producing stale UI nobody can reproduce.

Core Concepts

Wire Is A Provisioning Model, Not A Lifecycle Hook

Wire adapters provision data when their configuration is complete and when Salesforce determines fresh data should be emitted. The component should not assume wire execution timing matches connectedCallback() or renderedCallback(). The framework owns when data arrives.

Knowing the concrete init sequence is what lets you debug the classic "flash of undefined data" bug. For a Lightning Data Service wire the order is:

1. constructor() runs.
2. LDS provisions an empty placeholder — an object where both data and error are undefined. This happens before your first render, so the wired property is defined-but-empty, not missing.
3. connectedCallback(), render(), and renderedCallback() fire in that order. On this first pass the real data has not arrived yet — data is still undefined.
4. Data becomes available from the adapter asynchronously and is set on the data property (with error remaining undefined).
5. If the template consumes that data, render() and renderedCallback() fire again.

Guarding the template on data being truthy — or handling undefined in renderedCallback() — is what prevents the empty first pass from rendering as broken UI. A wired function is looser still: it "is invoked whenever a value is available, which can be before or after the component is connected or rendered."

Wire Emissions Are Multiple, Asynchronous, And Unordered

A wire is a stream, not a single resolved value. An LDS wire can emit data multiple times without the component changing its configuration; LDS controls those emits and they aren't tied to the LWC lifecycle. That is why renderedCallback() can fire repeatedly for reasons the component never initiated — a cache update elsewhere in the app can push a fresh value.

Wire adapter calls are also asynchronous unless the data is already cached, so the order of response and promise resolution is not sequential. Do not write logic that assumes wire A resolves before wire B, or that a wired value is present just because an imperative promise resolved. Each emission is a newer, immutable version of the previous value — treat the property as a read-only stream you react to, never a variable you populate at a known moment.

Reactive Parameters Must Become Real Values

Dynamic wire parameters prefixed with $ only work when the underlying values are defined. If a required reactive parameter is undefined, the wire adapter is not evaluated. This is one of the most common reasons a wire "doesn't fire."

Three things narrow that rule and are worth holding separately:

• $ is top-level only. Nesting it inside an array or object literal makes it a literal string, not a reference. Build the whole collection as one reactive property instead.
• null is not undefined. For a wired Apex method, a null parameter calls the method; only undefined suppresses the call. The Apex method therefore has to tolerate null.
• Reactive means re-provisioned. When the value changes, new data is provisioned and the render cycle runs again — so never assign a reactive config property from inside renderedCallback().

Private properties, getter-setter pairs, and @api properties can all be reactive config values.

Property Form Versus Function Form

The data and error property names are hardcoded in the API for both forms. The GraphQL wire adapter is the one exception: it uses errors, for compatibility with the GraphQL response specification.

cacheable=true Is The Contract That Makes @wire(apexMethod) Legal

An Apex method can only be wired if it is annotated @AuraEnabled(cacheable=true), and it can only be marked cacheable if it does not mutate data. That single annotation is what splits an LWC's Apex surface in two: cacheable reads may be wired or called imperatively, and everything that writes must be imperative. Apex limits apply per invocation, so two wired methods are two separate limit contexts, not one.

Two Data Sources Means Two Caches

LDS manages its own data; Apex data is unmanaged and must be refreshed by the component. That produces a three-way routing rule after any write:

Refresh once, after the mutating operation completes. Never poll with setTimeout() or setInterval() — if you cannot tell when a mutation finishes, give the user a refresh button instead. Apex and LDS do not share a cache at all, so a component that reads the same data through both can show two different answers.

Wired Data Should Be Treated As Immutable Input

The wire service gives the component data to render, not mutable state to edit in place. Provisioned objects are wrapped in a read-only proxy; assigning into them raises Invalid mutation … is read-only. Make a shallow copy before transforming — and remember that shallow copies do not copy nested objects, so a spread of a UI API record leaves the fields object still frozen.

Wire And Imperative Calls Solve Different Problems

Use wire for cache-aware reads and declarative reactivity. Use imperative Apex or LDS mutation APIs for creates, updates, deletes, and explicit user-triggered actions. Imperative is also the only option for objects UI API does not support, for loading records by criteria, for transactional multi-record work, and for anything that must run at a moment you choose.

Common Patterns

UI API Wire For Record Reads

When to use: The component reads record data and should inherit Lightning Data Service caching, sharing, CRUD, and FLS behavior.

How it works: Use adapters such as getRecord or object-info wires with schema imports and reactive record identifiers. Prefer fields over layoutTypes; use optionalFields for anything the running user may not be able to see, since a missing field in fields is an error while a missing optionalField is simply absent.

Why not the alternative: Custom Apex for standard record reads adds avoidable maintenance and can bypass built-in data protections.

Wire Chained Into Wire

When to use: One adapter's output is another's required input — the canonical case being getObjectInfo → defaultRecordTypeId → getPicklistValues.

How it works: Assign the intermediate value to a reactive property in the first wire's handler and reference it as $prop in the second. The second wire simply does not fire until the first lands, which is the gate working, not a bug.

Why not the alternative: Hardcoding a record type Id works until someone adds a record type. The master record type is 012000000000000AAA only when there is no default.

Imperative Mutation Plus Controlled Refresh

When to use: A user action updates data and the component must then refresh its wired state.

How it works: Perform the write imperatively, then refresh each stale cache with its own function per the routing table above. A component with both an Apex wire and a UI API wire over the same record needs both calls.

Why not the alternative: Expecting the wire adapter to notice every asynchronous server-side change leads to stale UI — an Apex trigger or auto-launched flow that changes the record does not re-evaluate the wire at all.

GraphQL Wire For Multi-Entity Read Models

When to use: The component needs a richer read model than individual UI API wires can express cleanly, or it needs filtering, ordering, pagination, or dynamic record Ids.

How it works: Use the GraphQL wire adapter, remember that the response exposes errors instead of error, and keep the component read-focused. lwc/lwc-graphql-wire owns the query shape and pagination.

Decision Guidance

Recommended Workflow

1. Settle the adapter before the code. Answer the seven questions above, checking the

   object against UI API support and the write path against cacheable=true. Record the answers in templates/wire-service-patterns-template.md; the Data Path table is the contract the rest of the steps implement.

2. Choose property form or function form deliberately, using the table in Core Concepts.

   If the component will ever call refreshApex(), it needs the function form and a wiredXResult field assigned before destructuring.

3. Build from references/code-examples.md. It carries the deployable slice: the

   cacheable=true controller plus its test, the bundle with getRecord on $recordId, the getObjectInfo → getPicklistValues chain, the function-form Apex wire, the spread-copy boundary, the js-meta.xml, package.xml, and the deploy order. Reuse templates/lwc/patterns/wireServicePattern.js for the minimal property-form read and templates/lwc/component-skeleton/ for the loading and error shell.

4. Model loading, empty and error as three states, not two. Before the first emission

   both data and error are undefined; that is not an error. Branch on the provisioned result's presence, and normalise error.body for the array-versus-object split — or import the shared errorUtils module from lwc/lwc-error-boundaries.

5. Write the refresh path at the same time as the write path. One call per stale cache,

   chosen from the routing table. No setTimeout / setInterval polling.

6. Pin the behaviour with the six Jest cases in references/code-examples.md § 5 —

   loading before any emit, a getRecord.emit() render, a copy-not-mutate assertion, empty versus loading, an Apex-shaped error, and a post-save assertion that refreshApex got the provisioned object and notifyRecordUpdateAvailable got [{ recordId }]. lwc/lwc-testing owns the harness and jest.config.js.

7. Run the checker over the source tree:

   python3 scripts/check_wire_service_patterns.py --manifest-dir force-app --strict. It flags a wired Apex method that is not cacheable=true (ERROR), in-place mutation of a wired result (ERROR), refreshApex() on something no wire provisioned, a $ nested inside a collection, a wired function that reads data but never error, an imperative write with no refresh call, a reactive config property assigned in renderedCallback(), and a string literal passed where a matching @api property exists.

Review Checklist

• [ ] The component uses wire only for read/provisioning use cases.
• [ ] Every wired Apex method is @AuraEnabled(cacheable=true) and does not mutate.
• [ ] Reactive parameters are defined intentionally and not left undefined accidentally.
• [ ] Every $ reference is a top-level config value, never nested in an array or object.
• [ ] Wired results are cloned before UI-specific mutation or sorting.
• [ ] Loading, empty, and error are three distinct rendered states.
• [ ] error.body handling branches on array versus object.
• [ ] Refresh after writes uses one function per cache and never polls.
• [ ] Schema imports are used where referential integrity matters.
• [ ] GraphQL wire consumers handle errors rather than assuming error.

Salesforce-Specific Gotchas

1. A wire adapter does not guarantee when data arrives — it can emit multiple times and is not tied to component lifecycle timing.
2. Undefined reactive parameters stop evaluation — many "wire isn't running" bugs are really incomplete configuration.
3. null and undefined behave differently for wired Apex params — null calls the method, undefined does not.
4. A nested $ is a literal string — ['$ids'] is passed verbatim, not resolved.
5. GraphQL wire returns errors, not error — assuming the standard wire error shape causes broken error handling.
6. Async changes outside the adapter do not auto-refresh — Apex-triggered or Flow-triggered server updates need an explicit refresh strategy.
7. refreshApex() on a non-Apex wire adapter is deprecated — use notifyRecordUpdateAvailable() for UI API reads.
8. renderedCallback() runs against undefined data on the first pass — LDS provisions an empty {data: undefined, error: undefined} placeholder before the real value arrives.

Full write-ups with grounding: references/gotchas.md.

Output Artifacts

Reference Files

Related Skills

• lwc/lwc-imperative-apex — use when the call is click-driven or non-cacheable; that skill owns the imperative side of the same Apex class.
• lwc/lwc-wire-refresh-patterns — use for RefreshView API and cross-component refresh; this skill covers refreshing after the component's own write.
• lwc/lwc-lds-writes — use when the write itself is createRecord / updateRecord / deleteRecord or a record form.
• lwc/lwc-graphql-wire — use when the read model is a GraphQL query, including pagination and errors handling.
• lwc/lwc-error-boundaries — use for the shared errorUtils normaliser and errorCallback; that skill owns error normalisation.
• lwc/lwc-testing — use for the Jest harness, jest.config.js, and mocking conventions.
• lwc/lwc-reactive-state-patterns — use when the question is component-local reactivity rather than server provisioning.
• lwc/lifecycle-hooks — use when render timing or cleanup is the real problem rather than provisioning strategy.
• apex/soql-security — use when the component relies on custom Apex reads that need secure data access review.
• lwc/lwc-offline-and-mobile — use when the wire strategy must also account for mobile or offline behavior.

Package files

• references/code-examples.md
• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/well-architected.md
• templates/wire-service-patterns-template.md
• scripts/check_wire_service_patterns.py