Org Skills

lwc-development

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.

Download .zip Raw Source
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.

npx skills add AGCO-Global/org-skills --skill lwc-development
# user-level instead of project-level:
npx skills add AGCO-Global/org-skills --skill lwc-development -g

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 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:

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.

References

Deeper material the agent loads only when needed.