Build Lightning Web Components for Spring '26 — the data-access ladder from `lightning-record-form` and Lightning Data Service to wired and imperative Apex, composition and events, `lwc:if`/`for:each`/`lwc:ref`/`lwc:on`, dynamic components, refreshing with `refreshApex`, `notifyRecordUpdateAvailable` and `RefreshEvent`, Lightning Message Service, `js-meta.xml` targets and `targetConfigs`, Flow screen and Experience Cloud components, SLDS 2 styling hooks, accessibility and Lightning Web Security.
When agents use itUse this whenever the user writes or fixes an LWC — a `.html` template, a `.js` controller, a `js-meta.xml`, a `@wire`, `lightning-datatable`, `lightning-record-edit-form`, a `CustomEvent`, a Lightning Message Channel, `loadScript` for a third-party library — or asks "how do I do X in LWC", why a wire returns undefined, or how to expose a component in App Builder or an LWR site. For tests use `salesforce-frontend-testing`; to choose between LWC, Flow and off-platform UI use `salesforce-frontend-architecture`.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill lwc-development -a github-copilot
# or with the org installer (adds .github/skills/lwc-development):
npx -y github:AGCO-Global/org-skills add skill lwc-development
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the salesforce-lwc-skills plugin, which bundles all Salesforce / LWC skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install salesforce-lwc-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill lwc-development -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill lwc-development -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill lwc-development -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill lwc-development -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the lwc-development folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
Skill contents
LWC Development
Targets: Salesforce Spring '26 (API 66.0), LWC API 66 · Verified: 2026-09 against https://developer.salesforce.com (Lightning Web Components Developer Guide) and the Spring '26 developer release notes
LWC is standard web components on a platform that punishes sloppy data access with governor limits, sharing violations and slow pages. Get data through the platform's cached services first and write Apex last: every @AuraEnabled method is code somebody has to secure, test and keep.
1. Decide first
Question
Default
Change when
How do I read or write record data?
Lightning Data Service — lightning-record-form / getRecord / updateRecord
The query needs filters, joins or aggregation the UI API cannot express → Apex @AuraEnabled(cacheable=true); several objects in one shaped read → lightning/uiGraphQLApi
Wire or imperative?
@wire for data that must stay in sync
User-triggered reads (search on click) and every mutation → imperative await; then refresh (section 4)
Where does the component live?
Declared targets in js-meta.xml, plus targetConfigs properties so admins configure it
Never override base-component internals or ship hard-coded SLDS class replacements
Third-party JavaScript
Static resource + loadScript
Dynamic component loading is different and supported — <lwc:component lwc:is={ctor}> with the lightning__dynamicComponent capability
Local feedback loop
sf lightning dev app / sf lightning dev component (Local Dev)
Jest for behaviour (salesforce-frontend-testing); a scratch org for anything LDS-heavy
2. A component that is actually complete
orderSummary.js — wired record read, imperative mutation, error branch:
import { LightningElement, api, wire } from 'lwc';
import { getRecord, getFieldValue, notifyRecordUpdateAvailable } from 'lightning/uiRecordApi';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';
import approveOrder from '@salesforce/apex/OrderController.approveOrder';
import STATUS_FIELD from '@salesforce/schema/Order__c.Status__c';
import TOTAL_FIELD from '@salesforce/schema/Order__c.Total__c';
const FIELDS = [STATUS_FIELD, TOTAL_FIELD];
export default class OrderSummary extends LightningElement {
@api recordId;
@api title = 'Order summary';
order;
error;
busy = false;
@wire(getRecord, { recordId: '$recordId', fields: FIELDS })
wiredOrder({ data, error }) {
this.order = data;
this.error = error;
}
get status() {
return getFieldValue(this.order, STATUS_FIELD);
}
// templates cannot negate, so expose the value the markup binds to
get notApprovable() {
return this.busy || this.status !== 'Submitted';
}
get message() {
return this.error?.body?.message ?? this.error?.message ?? 'Unknown error';
}
async handleApprove() {
this.busy = true;
try {
await approveOrder({ orderId: this.recordId });
await notifyRecordUpdateAvailable([{ recordId: this.recordId }]);
this.dispatchEvent(new ShowToastEvent({ title: 'Order approved', variant: 'success' }));
} catch (e) {
this.error = e;
this.dispatchEvent(new ShowToastEvent({
title: 'Could not approve', message: this.message, variant: 'error' }));
} finally {
this.busy = false;
}
}
}
The matching orderSummary.html and orderSummary.js-meta.xml (with apiVersion, targets, targetConfigs for a record page and an LWR site) are in references/component-example.md.
3. Templates and composition
lwc:if / lwc:elseif / lwc:else (if:true is legacy), for:each with a stable key that is not the index, lwc:ref instead of querySelector.
Public API is @api properties and methods with JSDoc; derived values are getters, never stored state. Fields are reactive, but arrays and objects need reassignment (this.items = [...this.items, row]), not mutation.
Events: lowercase name, no on prefix, bubbles: false, composed: false unless it genuinely must cross a boundary. lwc:on={handlers} attaches listeners from an object when the event names are computed at runtime, and the engine removes them on destroy.
Lifecycle: connectedCallback for subscriptions and one-time setup, renderedCallback only with a guard flag, disconnectedCallback to unsubscribe. Never fetch data in renderedCallback. Labels come from @salesforce/label/c.…, assets from @salesforce/resourceUrl, conditional UI from @salesforce/userPermission/….
4. Keeping data fresh
After a mutation the component made, refresh deliberately: refreshApex(this.wiredResult) for wired Apex, notifyRecordUpdateAvailable([{ recordId }]) for LDS-backed wires whose record changed server-side, and a RefreshEvent from lightning/refresh when a whole view (including Aura and standard components around you) must refresh. Wired Apex must be cacheable=true, and a cacheable method cannot do DML — split reads and mutations into different methods. Wire parameters are reactive with $recordId; guard against undefined on the first render. Full patterns, including GraphQL wires and pagination, in references/data-and-refresh.md.
5. Platform surfaces
App Builder: expose @api recordId / @api objectApiName, declare typed targetConfigs properties with defaults, and set isExposed to true only when placement is intended. apiVersion is required to save changes — keep it on the current release.
Flow screens: lightning__FlowScreen, @api inputs and outputs, FlowAttributeChangeEvent on every change, FlowNavigationNextEvent for navigation, @api validate() for screen validation.
Experience Cloud (LWR): declare lightningCommunity__Page for the drag-and-drop entry and lightningCommunity__Default for the editable properties. Navigate with lightning/navigation using comm__namedPage for site pages and standard__webPage for external URLs — never standard__app or standard__navItemPage, which assume the internal app. Guest-user access is a sharing question, and public pages carry a performance budget.
Quick actions: lightning__RecordAction with actionType="ScreenAction", closed with CloseActionScreenEvent. Agentforce: lightning__AgentforceInput / lightning__AgentforceOutput for components used inside agent actions.
Use only targets from the documented list — invented targets deploy and then silently never appear.
6. Security and styling
Lightning Web Security is the runtime in current orgs (Locker only where the org has not switched). No eval, no innerHTML with user data, third-party JS from static resources with loadScript/loadStyle and a CSP Trusted Site. @api inputs on a public site are user input — validate on the server. CRUD/FLS is enforced in Apex with USER_MODE; hiding a field in the template is not a control. Styling: base components first, SLDS 2 hooks for customisation, shared CSS through a style-only module (static stylesheets = [shared]), icon-only buttons always with alternative-text. SLDS 2 migration steps and the SLDS Linter are in references/slds2-and-styling.md.
7. Deliverable format
## Data decision — which rung of the ladder and why Apex was or wasn't needed
## Files — .html, .js, .js-meta.xml (apiVersion, targets, targetConfigs), plus the Apex controller
## States — loading, empty, error, no-access; which base components render them
## Refresh — what is refreshed after each mutation and with which API
## Tests — pointer to salesforce-frontend-testing for the Jest cases to add
Checklist
Data comes from the highest rung that works; Apex has a stated reason
Wired Apex is cacheable=true and free of DML; mutations are imperative
js-meta.xml has apiVersion, real targets from the documented list, and typed targetConfigs
lwc:if/lwc:else used, for:each keys stable, arrays reassigned not mutated
renderedCallback guarded; no data fetching in it; subscriptions removed in disconnectedCallback
Every mutation is followed by the right refresh call
Error, loading and empty states are rendered, with error.body.message flattened
Labels, URLs and record types are not hard-coded
Third-party JS loads from a static resource; no eval, no CDN
Base components used; icon-only buttons have alternative-text; SLDS 2 hooks instead of class overrides
Anti-patterns
Apex for what lightning-record-form or getRecord already does → climb down the ladder.
@wire on a non-cacheable method, or DML in a cacheable one → split read and write methods.
Fetching in renderedCallback → connectedCallback or a wire; guard every renderedCallback.
Mutating an array in place → reassign so the template re-renders.
A pub/sub helper or window globals → Lightning Message Service.
Invented js-meta.xml targets (there is no lightning__ServiceCloud) → use the documented list.
Rejecting all dynamic imports → dynamic components are supported with lwc:component/lwc:is; only third-party scripts must come from static resources.
Hand-built inputs and buttons → base components, which already handle a11y and theming.
Returning thousands of rows to a datatable → server-side pagination.
Go deeper
references/component-example.md — the full three-file component, the Flow-screen variant and the LWR variant with targetConfigs.
references/data-and-refresh.md — the data-access ladder in detail, GraphQL wires, refresh APIs, LMS, pagination and debounce.
Sibling skills: salesforce-frontend-architecture for choosing the surface and packaging, salesforce-frontend-testing for Jest and browser tests, apex-development for the controller, salesforce-security for LWS and guest users, salesforce-code-review for pull requests, salesforce-org-conventions for the org's naming and mandated patterns.
---
name: lwc-development
description: >
Build Lightning Web Components for Spring '26 — the data-access ladder from `lightning-record-form` and Lightning Data Service to wired and imperative Apex, composition and events, `lwc:if`/`for:each`/`lwc:ref`/`lwc:on`, dynamic components, refreshing with `refreshApex`, `notifyRecordUpdateAvailable` and `RefreshEvent`, Lightning Message Service, `js-meta.xml` targets and `targetConfigs`, Flow screen and Experience Cloud components, SLDS 2 styling hooks, accessibility and Lightning Web Security. Use this whenever the user writes or fixes an LWC — a `.html` template, a `.js` controller, a `js-meta.xml`, a `@wire`, `lightning-datatable`, `lightning-record-edit-form`, a `CustomEvent`, a Lightning Message Channel, `loadScript` for a third-party library — or asks "how do I do X in LWC", why a wire returns undefined, or how to expose a component in App Builder or an LWR site. For tests use `salesforce-frontend-testing`; to choose between LWC, Flow and off-platform UI use `salesforce-frontend-architecture`.
metadata:
technology: Salesforce
type: development
---
# LWC Development
> **Targets:** Salesforce Spring '26 (API 66.0), LWC API 66 · **Verified:** 2026-09 against https://developer.salesforce.com (Lightning Web Components Developer Guide) and the Spring '26 developer release notes
LWC is standard web components on a platform that punishes sloppy data access with governor limits, sharing violations and slow pages. Get data through the platform's cached services first and write Apex last: every `@AuraEnabled` method is code somebody has to secure, test and keep.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| How do I read or write record data? | **Lightning Data Service** — `lightning-record-form` / `getRecord` / `updateRecord` | The query needs filters, joins or aggregation the UI API cannot express → Apex `@AuraEnabled(cacheable=true)`; several objects in one shaped read → `lightning/uiGraphQLApi` |
| Wire or imperative? | `@wire` for data that must stay in sync | User-triggered reads (search on click) and every mutation → imperative `await`; then refresh (section 4) |
| Where does the component live? | Declared `targets` in `js-meta.xml`, plus `targetConfigs` properties so admins configure it | Flow screen → `lightning__FlowScreen`; LWR site → `lightningCommunity__Page` **and** `lightningCommunity__Default` (only `__Default` exposes editable properties) |
| Component talks to another component | Parent ↔ child with `@api` and `CustomEvent` | Unrelated components on a page → **Lightning Message Service**; never a pub/sub helper or `window` state |
| Custom UI or base component? | **Lightning base components** — accessible, themed, mobile-tested | Only build raw markup when no base component fits; then own the a11y work |
| Styling | SLDS utility classes + **SLDS 2 styling hooks** (`--slds-g-*`, `--slds-c-*`) | Never override base-component internals or ship hard-coded SLDS class replacements |
| Third-party JavaScript | Static resource + `loadScript` | Dynamic *component* loading is different and supported — `<lwc:component lwc:is={ctor}>` with the `lightning__dynamicComponent` capability |
| Local feedback loop | `sf lightning dev app` / `sf lightning dev component` (Local Dev) | Jest for behaviour (`salesforce-frontend-testing`); a scratch org for anything LDS-heavy |
## 2. A component that is actually complete
`orderSummary.js` — wired record read, imperative mutation, error branch:
```js
import { LightningElement, api, wire } from 'lwc';
import { getRecord, getFieldValue, notifyRecordUpdateAvailable } from 'lightning/uiRecordApi';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';
import approveOrder from '@salesforce/apex/OrderController.approveOrder';
import STATUS_FIELD from '@salesforce/schema/Order__c.Status__c';
import TOTAL_FIELD from '@salesforce/schema/Order__c.Total__c';
const FIELDS = [STATUS_FIELD, TOTAL_FIELD];
export default class OrderSummary extends LightningElement {
@api recordId;
@api title = 'Order summary';
order;
error;
busy = false;
@wire(getRecord, { recordId: '$recordId', fields: FIELDS })
wiredOrder({ data, error }) {
this.order = data;
this.error = error;
}
get status() {
return getFieldValue(this.order, STATUS_FIELD);
}
// templates cannot negate, so expose the value the markup binds to
get notApprovable() {
return this.busy || this.status !== 'Submitted';
}
get message() {
return this.error?.body?.message ?? this.error?.message ?? 'Unknown error';
}
async handleApprove() {
this.busy = true;
try {
await approveOrder({ orderId: this.recordId });
await notifyRecordUpdateAvailable([{ recordId: this.recordId }]);
this.dispatchEvent(new ShowToastEvent({ title: 'Order approved', variant: 'success' }));
} catch (e) {
this.error = e;
this.dispatchEvent(new ShowToastEvent({
title: 'Could not approve', message: this.message, variant: 'error' }));
} finally {
this.busy = false;
}
}
}
```
The matching `orderSummary.html` and `orderSummary.js-meta.xml` (with `apiVersion`, `targets`, `targetConfigs` for a record page and an LWR site) are in `references/component-example.md`.
## 3. Templates and composition
- `lwc:if` / `lwc:elseif` / `lwc:else` (`if:true` is legacy), `for:each` with a stable `key` that is not the index, `lwc:ref` instead of `querySelector`.
- Public API is `@api` properties and methods with JSDoc; derived values are getters, never stored state. Fields are reactive, but arrays and objects need **reassignment** (`this.items = [...this.items, row]`), not mutation.
- Events: lowercase name, no `on` prefix, `bubbles: false, composed: false` unless it genuinely must cross a boundary. `lwc:on={handlers}` attaches listeners from an object when the event names are computed at runtime, and the engine removes them on destroy.
- Lifecycle: `connectedCallback` for subscriptions and one-time setup, `renderedCallback` only with a guard flag, `disconnectedCallback` to unsubscribe. **Never fetch data in `renderedCallback`.** Labels come from `@salesforce/label/c.…`, assets from `@salesforce/resourceUrl`, conditional UI from `@salesforce/userPermission/…`.
## 4. Keeping data fresh
After a mutation the component made, refresh deliberately: `refreshApex(this.wiredResult)` for wired **Apex**, `notifyRecordUpdateAvailable([{ recordId }])` for LDS-backed wires whose record changed server-side, and a `RefreshEvent` from `lightning/refresh` when a whole view (including Aura and standard components around you) must refresh. Wired Apex must be `cacheable=true`, and a cacheable method cannot do DML — split reads and mutations into different methods. Wire parameters are reactive with `$recordId`; guard against `undefined` on the first render. Full patterns, including GraphQL wires and pagination, in `references/data-and-refresh.md`.
## 5. Platform surfaces
- **App Builder**: expose `@api recordId` / `@api objectApiName`, declare typed `targetConfigs` properties with defaults, and set `isExposed` to `true` only when placement is intended. `apiVersion` is required to save changes — keep it on the current release.
- **Flow screens**: `lightning__FlowScreen`, `@api` inputs and outputs, `FlowAttributeChangeEvent` on every change, `FlowNavigationNextEvent` for navigation, `@api validate()` for screen validation.
- **Experience Cloud (LWR)**: declare `lightningCommunity__Page` for the drag-and-drop entry and `lightningCommunity__Default` for the editable properties. Navigate with `lightning/navigation` using `comm__namedPage` for site pages and `standard__webPage` for external URLs — never `standard__app` or `standard__navItemPage`, which assume the internal app. Guest-user access is a sharing question, and public pages carry a performance budget.
- **Quick actions**: `lightning__RecordAction` with `actionType="ScreenAction"`, closed with `CloseActionScreenEvent`. **Agentforce**: `lightning__AgentforceInput` / `lightning__AgentforceOutput` for components used inside agent actions.
- Use only targets from the documented list — invented targets deploy and then silently never appear.
## 6. Security and styling
Lightning Web Security is the runtime in current orgs (Locker only where the org has not switched). No `eval`, no `innerHTML` with user data, third-party JS from static resources with `loadScript`/`loadStyle` and a CSP Trusted Site. `@api` inputs on a public site are user input — validate on the server. CRUD/FLS is enforced in Apex with `USER_MODE`; hiding a field in the template is not a control. Styling: base components first, SLDS 2 hooks for customisation, shared CSS through a style-only module (`static stylesheets = [shared]`), icon-only buttons always with `alternative-text`. SLDS 2 migration steps and the SLDS Linter are in `references/slds2-and-styling.md`.
## 7. Deliverable format
```
## Data decision — which rung of the ladder and why Apex was or wasn't needed
## Files — .html, .js, .js-meta.xml (apiVersion, targets, targetConfigs), plus the Apex controller
## States — loading, empty, error, no-access; which base components render them
## Refresh — what is refreshed after each mutation and with which API
## Tests — pointer to salesforce-frontend-testing for the Jest cases to add
```
## Checklist
- [ ] Data comes from the highest rung that works; Apex has a stated reason
- [ ] Wired Apex is `cacheable=true` and free of DML; mutations are imperative
- [ ] `js-meta.xml` has `apiVersion`, real targets from the documented list, and typed `targetConfigs`
- [ ] `lwc:if`/`lwc:else` used, `for:each` keys stable, arrays reassigned not mutated
- [ ] `renderedCallback` guarded; no data fetching in it; subscriptions removed in `disconnectedCallback`
- [ ] Every mutation is followed by the right refresh call
- [ ] Error, loading and empty states are rendered, with `error.body.message` flattened
- [ ] Labels, URLs and record types are not hard-coded
- [ ] Third-party JS loads from a static resource; no `eval`, no CDN
- [ ] Base components used; icon-only buttons have `alternative-text`; SLDS 2 hooks instead of class overrides
## Anti-patterns
- **Apex for what `lightning-record-form` or `getRecord` already does** → climb down the ladder.
- **`@wire` on a non-cacheable method, or DML in a cacheable one** → split read and write methods.
- **Fetching in `renderedCallback`** → `connectedCallback` or a wire; guard every `renderedCallback`.
- **Mutating an array in place** → reassign so the template re-renders.
- **A pub/sub helper or `window` globals** → Lightning Message Service.
- **Invented `js-meta.xml` targets** (there is no `lightning__ServiceCloud`) → use the documented list.
- **Rejecting all dynamic imports** → dynamic *components* are supported with `lwc:component`/`lwc:is`; only third-party *scripts* must come from static resources.
- **Hand-built inputs and buttons** → base components, which already handle a11y and theming.
- **Returning thousands of rows to a datatable** → server-side pagination.
## Go deeper
- `references/component-example.md` — the full three-file component, the Flow-screen variant and the LWR variant with `targetConfigs`.
- `references/data-and-refresh.md` — the data-access ladder in detail, GraphQL wires, refresh APIs, LMS, pagination and debounce.
- `references/slds2-and-styling.md` — SLDS 2 hooks and migration checklist, SLDS Linter, shared stylesheets, accessibility rules.
- Sibling skills: `salesforce-frontend-architecture` for choosing the surface and packaging, `salesforce-frontend-testing` for Jest and browser tests, `apex-development` for the controller, `salesforce-security` for LWS and guest users, `salesforce-code-review` for pull requests, `salesforce-org-conventions` for the org's naming and mandated patterns.