fe-lwc-skill 1.0.0

package/README.md

@@ -0,0 +1,56 @@
+# fe-lwc-skill
+
+Salesforce LWC Frontend Skill for AI Agents — installs structured rule files for Lightning Web Components development into your project's agent config directory.
+
+## Install
+
+```bash
+# Auto-detect agent runtime (Claude Code, Cursor, Gemini CLI, Continue.dev, Copilot)
+npx fe-lwc-skill
+
+# Install to a specific path
+npx fe-lwc-skill --target .claude/skills/fe-lwc
+
+# Overwrite existing install
+npx fe-lwc-skill --force
+```
+
+## Supported runtimes
+
+| Runtime        | Auto-detected via | Installs to                    |
+| -------------- | ----------------- | ------------------------------ |
+| Claude Code    | `.claude/`        | `.claude/skills/fe-lwc/`       |
+| Gemini CLI     | `.gemini/`        | `.gemini/skills/fe-lwc/`       |
+| Cursor         | `.cursor/`        | `.cursor/rules/fe-lwc/`        |
+| Continue.dev   | `.continue/`      | `.continue/rules/fe-lwc/`      |
+| GitHub Copilot | `.github/`        | `.github/instructions/fe-lwc/` |
+
+If multiple runtimes are detected, the skill is installed to all of them.
+
+## What's included
+
+```
+skill/
+├── SKILL.md                        # Agent entry point
+└── rules/
+    ├── data-wire-vs-imperative.md
+    ├── data-lds-first.md
+    ├── data-error-handling.md
+    ├── template-directives.md
+    ├── template-form-pattern.md
+    ├── template-dom-query.md
+    ├── events-custom-event.md
+    ├── events-lms.md
+    ├── design-token-slds.md
+    └── design-token-dxp.md
+```
+
+## After install
+
+Reference the skill in your `CLAUDE.md` / `AGENTS.md`:
+
+```markdown
+## Skills
+
+- LWC Frontend: `.claude/skills/fe-lwc/SKILL.md`
+```

package/bin/index.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+import { cpSync, mkdirSync, existsSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SKILL_NAME = "fe-lwc";
+
+/**
+ * Known agent runtimes and where they expect skill/rule files.
+ * Add new entries here as new agents emerge.
+ */
+const AGENT_RUNTIMES = [
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    markerDir: ".claude",
+    skillPath: `.claude/skills/${SKILL_NAME}`,
+  },
+  {
+    id: "gemini",
+    label: "Gemini CLI",
+    markerDir: ".gemini",
+    skillPath: `.gemini/skills/${SKILL_NAME}`,
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    markerDir: ".cursor",
+    skillPath: `.cursor/rules/${SKILL_NAME}`,
+  },
+  {
+    id: "continue",
+    label: "Continue.dev",
+    markerDir: ".continue",
+    skillPath: `.continue/rules/${SKILL_NAME}`,
+  },
+  {
+    id: "copilot",
+    label: "GitHub Copilot",
+    markerDir: ".github",
+    skillPath: `.github/instructions/${SKILL_NAME}`,
+  },
+];
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const skillSrc = join(__dirname, "../skill");
+const cwd = process.cwd();
+
+function install(destPath, { force = false } = {}) {
+  const abs = resolve(cwd, destPath);
+
+  if (existsSync(abs)) {
+    if (!force) {
+      console.log(`  ⚠️  Already exists: ${destPath}`);
+      console.log(`      Use --force to overwrite.`);
+      return false;
+    }
+    rmSync(abs, { recursive: true, force: true });
+  }
+
+  mkdirSync(abs, { recursive: true });
+  cpSync(skillSrc, abs, { recursive: true });
+  console.log(`  ✅ Installed → ${destPath}`);
+  return true;
+}
+
+function printHelp() {
+  console.log(`
+Usage:
+  npx ${SKILL_NAME}-skill [options]
+
+Options:
+  --target <path>   Install to a specific directory (relative to project root)
+  --force           Overwrite if skill already exists
+  --help            Show this message
+
+Examples:
+  npx fe-lwc-skill                          # auto-detect agent runtimes
+  npx fe-lwc-skill --target .claude/skills/fe-lwc
+  npx fe-lwc-skill --target .gemini/skills/fe-lwc --force
+
+Supported runtimes (auto-detected):
+${AGENT_RUNTIMES.map((r) => `  ${r.label.padEnd(18)} → ${r.skillPath}`).join("\n")}
+`);
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+  printHelp();
+  process.exit(0);
+}
+
+const force = args.includes("--force");
+const targetIdx = args.indexOf("--target");
+
+console.log(`\n🔧 fe-lwc-skill installer\n`);
+
+// ── Mode 1: explicit --target ─────────────────────────────────────────────────
+if (targetIdx !== -1) {
+  const target = args[targetIdx + 1];
+
+  if (!target || target.startsWith("--")) {
+    console.error("❌ --target requires a path argument.");
+    console.error("   Example: --target .claude/skills/fe-lwc\n");
+    process.exit(1);
+  }
+
+  install(target, { force });
+  process.exit(0);
+}
+
+// ── Mode 2: auto-detect ───────────────────────────────────────────────────────
+const detected = AGENT_RUNTIMES.filter(({ markerDir }) => existsSync(join(cwd, markerDir)));
+
+if (detected.length === 0) {
+  console.log("⚠️  No known agent config directory found in this project.");
+  console.log("   Looked for:", AGENT_RUNTIMES.map((r) => r.markerDir).join(", "));
+  console.log("");
+  console.log("   Use --target to install manually:");
+  console.log(`   npx ${SKILL_NAME}-skill --target .claude/skills/${SKILL_NAME}\n`);
+  process.exit(1);
+}
+
+console.log(`Found ${detected.length} agent runtime(s):\n`);
+
+let installedCount = 0;
+for (const runtime of detected) {
+  process.stdout.write(`  [${runtime.label}] `);
+  const ok = install(runtime.skillPath, { force });
+  if (ok) installedCount++;
+}
+
+console.log("");
+if (installedCount > 0) {
+  console.log(`🎉 Done! Installed to ${installedCount} location(s).`);
+  console.log(`   The agent will now load LWC rules from the skill directory.\n`);
+} else {
+  console.log(`Nothing was installed. Run with --force to overwrite existing installs.\n`);
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "fe-lwc-skill",
+  "version": "1.0.0",
+  "description": "LWC Frontend Skill for AI Agents (Claude Code, Cursor, Gemini CLI, Continue.dev)",
+  "type": "module",
+  "bin": {
+    "fe-lwc-skill": "./bin/index.js"
+  },
+  "files": [
+    "bin/",
+    "skill/"
+  ],
+  "keywords": [
+    "lwc",
+    "salesforce",
+    "lightning-web-components",
+    "ai-skill",
+    "claude-code",
+    "cursor",
+    "gemini"
+  ],
+  "license": "MIT"
+}

package/skill/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: fe-lwc
+description: Generate Lightning Web Components (LWC) for Salesforce Experience Cloud portals and Lightning App Builder, following scalable architecture, performance optimization, and Salesforce platform best practices.
+---
+
+# LWC Frontend Development
+
+Before writing any LWC code, you MUST read the relevant rule files below.
+
+## Rules & Patterns
+
+### Always read these first:
+
+- Read `rules/design-token-dxp.md` and `rules/design-token-slds.md` before any UI styling
+- Read `rules/data-lds-first.md` before any data fetching
+- Read `rules/template-form-pattern.md` before building forms
+- **Creating a new LWC?** Always scaffold with the CLI first — replace `<componentName>` with the actual component name from the prompt:
+  ```bash
+  sf lightning generate component --type lwc --name <componentName> --output-dir force-app/main/default/lwc
+  ```
+- For every TypeScript LWC component created, always add a .gitignore entry for the generated JavaScript file.
+
+### Read based on task:
+
+- Wire vs imperative: read `rules/data-wire-vs-imperative.md`
+- Custom events: read `rules/events-custom-event.md`
+- LMS: read `rules/events-lms.md`
+- Template directives: read `rules/template-directives.md`
+- DOM querying: read `rules/template-dom-querying.md`
+- Track/immutable: read `rules/template-track-immutable.md`
+- Error handling: read `rules/data-error-handling.md`
+
+---
+
+# When to Apply
+
+Reference these guidelines when:
+
+- Writing a new LWC component for an **Experience Cloud portal** (LWR runtime)
+- Writing a custom component for a **Salesforce Lightning App** (App Builder)
+- Implementing data fetching with `@wire` or imperative Apex calls
+- Reviewing or refactoring existing LWC code for consistency and performance
+
+---
+
+# Core Principles
+
+All Lightning Web Components should follow these engineering principles to ensure scalability, maintainability, and platform consistency.
+
+- **LDS First** — Prefer Lightning Data Service (`lightning/uiRecordApi`) for standard CRUD operations before writing Apex controllers.
+- **LWR Optimized** — Components must be optimized for Lightning Web Runtime (LWR).
+- **Platform Native First** — Always prefer standard Salesforce capabilities before implementing custom solutions.
+- **Performance Focused** — Avoid unnecessary re-renders, excessive DOM queries, and large reactive states.
+
+---
+
+# Quick Reference
+
+## Data Patterns
+
+| Rule                      | Description                                                                                                         |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `data-lds-first`          | Use `lightning/uiRecordApi` for standard CRUD before reaching for Apex                                              |
+| `data-wire-vs-imperative` | Use `@wire` for declarative data binding; use imperative calls when you need explicit control (e.g. on user action) |
+| `data-error-handling`     | Always handle wire/Apex errors using the `reduceErrors` utility; never silently swallow errors                      |
+
+## Template Standards
+
+| Rule                       | Description                                                                                                      |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `template-directives`      | Use `lwc:if` / `lwc:elseif` / `lwc:else` / `for:each` + `for:item` — never the deprecated `if:true` / `if:false` |
+| `template-track-immutable` | Avoid unnecessary `@track`; trigger reactivity through immutable updates (`[...arr]`, `{...obj}`)                |
+| `template-form-pattern`    | Use a single `handleChange` method keyed on `event.target.name`; keep form state in one object                   |
+| `template-dom-querying`    | Target elements with `data-id` attributes and `this.template.querySelector()`; avoid class/tag selectors         |
+
+## Component Communication
+
+| Rule                  | Description                                                                                                                                   |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `events-custom-event` | Dispatch custom events with explicit `bubbles` and `composed` flags; use kebab-case or camelCase event names                                  |
+| `events-lms`          | Use Lightning Message Service (LMS) for cross-region communication on App Builder and Experience Cloud pages; avoid direct component coupling |
+
+## Design System
+
+| Rule                | Description                                                                                                                                                                                                         |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `design-token-dxp`  | Use `dxp-text-*` classes for typography in HTML templates, `--dxp-s-text-*` hooks in component CSS, and `--dxp-g-*` color hooks — never hardcode hex values; define site-wide overrides in Head Markup `:root` only |
+| `design-token-slds` | Apply SLDS utility classes for spacing and layout before writing any custom CSS                                                                                                                                     |

package/skill/rules/data-error-handling.md

@@ -0,0 +1,297 @@
+# data-error-handling
+
+**Impact: HIGH**
+
+Unhandled errors are the most common silent failure in LWC. In LWC, `@wire` errors were frequently ignored — the component simply rendered nothing, leaving the user with a blank screen and no explanation. This rule covers how to handle errors consistently across wire adapters, imperative Apex calls, and form validation.
+
+> **Rule:**
+>
+> - Always check `error` on every `@wire` result — never assume `data` is always present.
+> - Handle the loading state too — when both `data` and `error` are `undefined`, the wire is still pending.
+> - Use `reduceErrors` to extract readable messages from any Salesforce error shape.
+> - Show a **toast** for Apex/server errors.
+> - Show **inline messages** for form validation errors.
+
+---
+
+## The `reduceErrors` utility
+
+Salesforce errors can come in many shapes — a wire `FetchResponse`, an imperative `AuraHandledException`, or a list of field-level errors from `createRecord`. `reduceErrors` normalizes all of them into a simple string array.
+
+Copy this utility once into your project at `lwc/utils/errorUtils.ts`:
+
+```typescript
+// utils/errorUtils.ts
+
+interface SalesforceError {
+  body?: { message?: string } | Array<{ message: string }>;
+  message?: string;
+  statusText?: string;
+}
+
+/**
+ * Reduces one or more LDS errors into a string array of error messages.
+ */
+export function reduceErrors(errors: SalesforceError | SalesforceError[]): string[] {
+  if (!Array.isArray(errors)) {
+    errors = [errors];
+  }
+
+  return errors
+    .filter(Boolean)
+    .map((error) => {
+      if (Array.isArray(error.body)) {
+        return error.body.map((e) => e.message);
+      }
+      if (error.body && typeof error.body.message === "string") {
+        return error.body.message;
+      }
+      if (typeof error.message === "string") {
+        return error.message;
+      }
+      return error.statusText ?? "Unknown error";
+    })
+    .reduce<string[]>((acc, val) => acc.concat(val), [])
+    .filter((message): message is string => !!message);
+}
+```
+
+---
+
+## Case 1: Ignoring `@wire` errors (and missing loading state)
+
+**Incorrect — blank screen when wire fails; no loading state:**
+
+```typescript
+// patientSummary.ts
+import { LightningElement, api, wire } from "lwc";
+import getPatientSummary from "@salesforce/apex/PatientController.getPatientSummary";
+
+// @ts-ignore — decorator typing limitation in current Developer Preview
+export default class PatientSummary extends LightningElement {
+  // @ts-ignore
+  @api recordId: string;
+
+  // @ts-ignore
+  @wire(getPatientSummary, { recordId: "$recordId" })
+  summary: { data?: PatientSummary; error?: unknown };
+
+  // summary.error is never checked
+  // loading state (data === undefined && error === undefined) never handled
+}
+```
+
+**Correct — handle loading, data, and error states:**
+
+```typescript
+// patientSummary.ts
+import { LightningElement, api, wire } from "lwc";
+import { ShowToastEvent } from "lightning/platformShowToastEvent";
+import getPatientSummary from "@salesforce/apex/PatientController.getPatientSummary";
+import { reduceErrors } from "c/utils";
+
+interface PatientSummaryRecord {
+  Name: string;
+}
+
+// @ts-ignore
+export default class PatientSummary extends LightningElement {
+  // @ts-ignore
+  @api recordId: string;
+
+  summary: PatientSummaryRecord | null = null;
+  isLoading: boolean = true;
+
+  // @ts-ignore
+  @wire(getPatientSummary, { recordId: "$recordId" })
+  public handleSummary({ data, error }: { data?: PatientSummaryRecord; error?: unknown }): void {
+    this.isLoading = false;
+    if (data) {
+      this.summary = data;
+    } else if (error) {
+      this.dispatchEvent(
+        new ShowToastEvent({
+          title: "Error loading patient",
+          message: reduceErrors(error).join(", "),
+          variant: "error",
+        }),
+      );
+    }
+  }
+}
+```
+
+```html
+<!-- patientSummary.html -->
+<template>
+  <template lwc:if="{isLoading}">
+    <lightning-spinner alternative-text="Loading"></lightning-spinner>
+  </template>
+
+  <template lwc:elseif="{summary}">
+    <p>{summary.Name}</p>
+  </template>
+
+  <template lwc:else>
+    <p>No patient data available.</p>
+  </template>
+</template>
+```
+
+---
+
+## Case 2: Imperative Apex call without error handling
+
+**Incorrect — no try/catch, unhandled promise rejection:**
+
+```typescript
+// appointmentSearch.ts
+import { LightningElement } from "lwc";
+import searchAppointments from "@salesforce/apex/AppointmentController.searchAppointments";
+
+// @ts-ignore
+export default class AppointmentSearch extends LightningElement {
+  appointments: unknown[] = [];
+
+  public async handleSearch(): Promise<void> {
+    // If this throws, nothing catches it — silent failure.
+    this.appointments = await searchAppointments({ term: this.searchTerm });
+  }
+}
+```
+
+**Correct — try/catch with toast on error:**
+
+```typescript
+// appointmentSearch.ts
+import { LightningElement } from "lwc";
+import { ShowToastEvent } from "lightning/platformShowToastEvent";
+import searchAppointments from "@salesforce/apex/AppointmentController.searchAppointments";
+import { reduceErrors } from "c/utils";
+
+interface AppointmentRecord {
+  Id: string;
+  Name: string;
+}
+
+// @ts-ignore
+export default class AppointmentSearch extends LightningElement {
+  searchTerm: string = "";
+  appointments: AppointmentRecord[] = [];
+  isLoading: boolean = false;
+
+  public handleChange(event: Event): void {
+    this.searchTerm = (event.target as HTMLInputElement).value;
+  }
+
+  public async handleSearch(): Promise<void> {
+    this.isLoading = true;
+    try {
+      this.appointments = await searchAppointments({ term: this.searchTerm });
+    } catch (error) {
+      this.dispatchEvent(
+        new ShowToastEvent({
+          title: "Search failed",
+          message: reduceErrors(error).join(", "),
+          variant: "error",
+        }),
+      );
+    } finally {
+      this.isLoading = false;
+    }
+  }
+}
+```
+
+---
+
+## Case 3: Form validation — inline error, not toast
+
+**Incorrect — toast for a form validation error:**
+
+```typescript
+// bookingForm.ts
+public async handleSubmit(event: Event): Promise<void> {
+    event.preventDefault();
+    if (!this.formState.date) {
+        this.dispatchEvent(
+            new ShowToastEvent({ title: 'Date is required', variant: 'error' })
+        );
+        return;
+    }
+}
+```
+
+**Correct — inline error using `setCustomValidity` + `reportValidity`:**
+
+```typescript
+// bookingForm.ts
+import { LightningElement } from "lwc";
+
+interface BookingFormState {
+  date: string;
+}
+
+// @ts-ignore
+export default class BookingForm extends LightningElement {
+  formState: BookingFormState = { date: "" };
+
+  public handleChange(event: Event): void {
+    const target = event.target as HTMLInputElement;
+    this.formState = { ...this.formState, [target.name]: target.value };
+  }
+
+  public handleSubmit(event: Event): void {
+    event.preventDefault();
+
+    const dateInput = this.template.querySelector<HTMLInputElement>('[data-id="date-input"]');
+    if (!dateInput) return;
+
+    if (!this.formState.date) {
+      dateInput.setCustomValidity("Please select an appointment date.");
+      dateInput.reportValidity();
+      return;
+    }
+
+    dateInput.setCustomValidity("");
+    this.submitBooking();
+  }
+
+  private submitBooking(): void {
+    // submit logic
+  }
+}
+```
+
+```html
+<!-- bookingForm.html -->
+<template>
+  <form onsubmit="{handleSubmit}">
+    <lightning-input
+      data-id="date-input"
+      name="date"
+      type="date"
+      label="Appointment Date"
+      value="{formState.date}"
+      onchange="{handleChange}">
+    </lightning-input>
+    <lightning-button type="submit" variant="brand" label="Book"></lightning-button>
+  </form>
+</template>
+```
+
+---
+
+## Quick Decision Guide
+
+| Situation                                  | Error Pattern                                 |
+| ------------------------------------------ | --------------------------------------------- |
+| `@wire` result — data/error both undefined | Show loading spinner                          |
+| `@wire` returns error                      | Wire function handler + toast                 |
+| Imperative Apex throws                     | `try/catch` + toast                           |
+| Form field fails validation                | `setCustomValidity` + `reportValidity` inline |
+| Multiple errors from LDS                   | `reduceErrors(error).join(', ')`              |
+
+---
+
+**Reference:** [Handle Errors in Lightning Data Service — Salesforce LWC Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/data-error.html)