@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/generating-lwc-components/references/cli-commands.md

@@ -0,0 +1,545 @@
+<!-- Parent: generating-lwc-components/SKILL.md -->
+# Salesforce CLI Commands for LWC Development
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Create component | `sf template generate lightning component --name myComp --type lwc` |
+| Create FlexiPage | `sf template generate flexipage --name MyPage --template DefaultAppPage` |
+| Run all tests | `sf force lightning lwc test run` |
+| Preview a component locally | `sf lightning dev component --target-org my-sandbox` |
+| Preview an app locally | `sf lightning dev app --target-org my-sandbox` |
+| Preview an Experience Cloud site locally | `sf lightning dev site --target-org my-sandbox` |
+| Deploy component | `sf project deploy start --source-dir force-app/.../lwc/myComp` |
+| Create message channel | Manual XML: `force-app/.../messageChannels/MyChannel.messageChannel-meta.xml` |
+
+---
+
+## Component Generation
+
+### Create New LWC
+
+```bash
+# Basic component
+sf template generate lightning component \
+  --name accountList \
+  --type lwc \
+  --output-dir force-app/main/default/lwc
+
+# Creates:
+# force-app/main/default/lwc/accountList/
+# ├── accountList.js
+# ├── accountList.html
+# └── accountList.js-meta.xml
+```
+
+### Generate with Jest Test
+
+```bash
+# The test file must be created manually in __tests__ folder
+mkdir -p force-app/main/default/lwc/accountList/__tests__
+touch force-app/main/default/lwc/accountList/__tests__/accountList.test.js
+```
+
+---
+
+## Testing
+
+### Run All Jest Tests
+
+```bash
+sf force lightning lwc test run
+```
+
+### Run Specific Test File
+
+```bash
+sf force lightning lwc test run \
+  --spec force-app/main/default/lwc/accountList/__tests__/accountList.test.js
+```
+
+### Watch Mode (Development)
+
+```bash
+# Re-runs tests when files change
+sf force lightning lwc test run --watch
+```
+
+### Coverage Report
+
+```bash
+# Generate HTML coverage report
+sf force lightning lwc test run --coverage
+# Report at: coverage/lcov-report/index.html
+```
+
+### Debug Tests
+
+```bash
+# Run with Node debugger
+sf force lightning lwc test run --debug
+
+# Then in Chrome: chrome://inspect
+```
+
+### Update Snapshots
+
+```bash
+sf force lightning lwc test run --update-snapshot
+```
+
+---
+
+## Linting
+
+### Run ESLint
+
+> **Note**: `sf lightning lint` does not exist. Use `npx eslint` directly or `sf code-analyzer run`.
+
+```bash
+# Lint LWC files with ESLint (requires @salesforce/eslint-config-lwc)
+npx eslint force-app/main/default/lwc
+
+# Lint specific component
+npx eslint force-app/main/default/lwc/accountList
+
+# Auto-fix issues
+npx eslint force-app/main/default/lwc --fix
+
+# Or use Code Analyzer (includes ESLint + PMD + RetireJS)
+sf code-analyzer run --workspace force-app/main/default/lwc
+```
+
+---
+
+## Deployment
+
+### Deploy Single Component
+
+```bash
+sf project deploy start \
+  --source-dir force-app/main/default/lwc/accountList \
+  --target-org my-sandbox
+```
+
+### Deploy Multiple Components
+
+```bash
+sf project deploy start \
+  --source-dir force-app/main/default/lwc/accountList \
+  --source-dir force-app/main/default/lwc/accountForm \
+  --target-org my-sandbox
+```
+
+### Deploy with Related Apex
+
+```bash
+sf project deploy start \
+  --source-dir force-app/main/default/lwc/accountList \
+  --source-dir force-app/main/default/classes/AccountController.cls \
+  --target-org my-sandbox
+```
+
+### Validate Without Deploying
+
+```bash
+sf project deploy start \
+  --source-dir force-app/main/default/lwc \
+  --target-org my-sandbox \
+  --dry-run
+```
+
+---
+
+## Retrieval
+
+### Retrieve Component from Org
+
+```bash
+sf project retrieve start \
+  --metadata LightningComponentBundle:accountList \
+  --target-org my-sandbox \
+  --output-dir force-app/main/default
+```
+
+### Retrieve All LWC
+
+```bash
+sf project retrieve start \
+  --metadata LightningComponentBundle \
+  --target-org my-sandbox
+```
+
+---
+
+## Local Development
+
+### Preview Components Locally
+
+> **Note**: `sf lightning dev-server` was deprecated. In current SF CLI releases, Local Dev commands are installed just-in-time on first use via the Local Dev plugin.
+
+```bash
+# Preview an LWC component in isolation
+sf lightning dev component --name myComp --target-org my-sandbox
+
+# Launch component preview and choose the component interactively
+sf lightning dev component --target-org my-sandbox
+
+# Preview a Lightning Experience app locally
+sf lightning dev app --target-org my-sandbox
+
+# Preview an Experience Cloud site locally
+sf lightning dev site --name "Partner Central" --target-org my-sandbox
+```
+
+These commands start long-running local preview sessions with hot reload. Use `sf project deploy start` for changes that Local Dev can't reflect automatically.
+
+---
+
+## Message Channels
+
+### Create Message Channel
+
+> **Note**: There is no `sf lightning generate messageChannel` command. Message Channels are created as metadata XML files manually.
+
+```bash
+# Create the directory if it doesn't exist
+mkdir -p force-app/main/default/messageChannels
+
+# Create the XML file manually:
+# force-app/main/default/messageChannels/RecordSelected.messageChannel-meta.xml
+```
+
+### Deploy Message Channel
+
+```bash
+sf project deploy start \
+  --metadata LightningMessageChannel:RecordSelected__c \
+  --target-org my-sandbox
+```
+
+---
+
+## Debugging
+
+### Open Component in Browser
+
+```bash
+# Open Lightning App Builder
+sf org open --target-org my-sandbox --path /lightning/setup/FlexiPageList/home
+```
+
+### View Debug Logs
+
+```bash
+# Tail logs while testing
+sf apex tail log --target-org my-sandbox --color
+```
+
+### Check Deployment Errors
+
+```bash
+# If deployment fails, check status
+sf project deploy report --job-id <job-id>
+```
+
+---
+
+## Package Development
+
+### Create Unlocked Package
+
+```bash
+# Create package
+sf package create \
+  --name "My LWC Package" \
+  --package-type Unlocked \
+  --path force-app
+
+# Create version
+sf package version create \
+  --package "My LWC Package" \
+  --installation-key test1234 \
+  --wait 10
+```
+
+---
+
+## Jest Configuration
+
+### Setup Jest (if not already configured)
+
+```bash
+# Install Jest dependencies
+npm install @salesforce/sfdx-lwc-jest --save-dev
+
+# Add to package.json scripts
+{
+  "scripts": {
+    "test:unit": "sfdx-lwc-jest",
+    "test:unit:watch": "sfdx-lwc-jest --watch",
+    "test:unit:debug": "sfdx-lwc-jest --debug",
+    "test:unit:coverage": "sfdx-lwc-jest --coverage"
+  }
+}
+```
+
+### Jest Config (jest.config.js)
+
+```javascript
+const { jestConfig } = require('@salesforce/sfdx-lwc-jest/config');
+
+module.exports = {
+    ...jestConfig,
+    roots: ['<rootDir>/force-app'],
+    modulePathIgnorePatterns: ['<rootDir>/.localdevserver'],
+    testPathIgnorePatterns: [
+        '<rootDir>/node_modules/',
+        '<rootDir>/.sfdx/',
+        '<rootDir>/.agents/',
+        '<rootDir>/.cursor/',
+        '<rootDir>/.claude/',
+        '<rootDir>/.pi/'
+    ],
+    testTimeout: 10000
+};
+```
+
+If you copy example tests from `generating-lwc-components/assets/`, rename the `.example` file after placing it in your component's `__tests__` folder.
+
+---
+
+## Useful Patterns
+
+### Deploy and Test Flow
+
+```bash
+# 1. Run local tests
+sf force lightning lwc test run
+
+# 2. Deploy to sandbox
+sf project deploy start \
+  --source-dir force-app/main/default/lwc/myComponent \
+  --target-org my-sandbox
+
+# 3. Open org to test
+sf org open --target-org my-sandbox
+```
+
+### CI/CD Pipeline Pattern
+
+```bash
+#!/bin/bash
+
+# Lint
+npx eslint ./force-app/main/default/lwc || exit 1
+
+# Test
+sf force lightning lwc test run --coverage || exit 1
+
+# Validate deployment
+sf project deploy start \
+  --source-dir force-app/main/default/lwc \
+  --target-org ci-sandbox \
+  --dry-run \
+  --json || exit 1
+
+# Deploy if validation passes
+sf project deploy start \
+  --source-dir force-app/main/default/lwc \
+  --target-org ci-sandbox \
+  --json
+```
+
+### Watch and Auto-Deploy
+
+```bash
+# Using nodemon or similar
+npx nodemon \
+  --watch "force-app/main/default/lwc/**/*" \
+  --exec "sf project deploy start --source-dir force-app/main/default/lwc --target-org my-sandbox"
+```
+
+---
+
+## Troubleshooting
+
+### Component Not Visible in App Builder
+
+1. Check `isExposed` is `true` in meta.xml
+2. Check `targets` include the desired location
+3. Verify deployment was successful
+
+```bash
+# Re-deploy with verbose output
+sf project deploy start \
+  --source-dir force-app/main/default/lwc/myComponent \
+  --target-org my-sandbox \
+  --verbose
+```
+
+### Jest Tests Not Finding Component
+
+If Jest reports errors from `.agents/`, `.cursor/`, `.claude/`, or `.pi/`, it is discovering files outside your real Salesforce source tree. Scope Jest to `force-app` and ignore agent folders.
+
+```bash
+# Clear Jest cache
+npx jest --clearCache
+
+# Re-run tests
+sf force lightning lwc test run
+```
+
+### Wire Service Not Working
+
+1. Verify `cacheable=true` on Apex method
+2. Check reactive parameter has `$` prefix
+3. Verify Apex method is accessible
+
+```bash
+# Test Apex method directly
+sf apex run --target-org my-sandbox <<< "System.debug(MyController.getRecords());"
+```
+
+### Deployment Conflicts
+
+```bash
+# Check what's different
+sf project retrieve start \
+  --metadata LightningComponentBundle:myComponent \
+  --target-org my-sandbox \
+  --output-dir temp-retrieve
+
+# Compare and resolve
+diff -r force-app/main/default/lwc/myComponent temp-retrieve/force-app/.../myComponent
+```
+
+---
+
+## Static Analysis (Code Analyzer v5)
+
+### Salesforce Code Analyzer
+
+Code Analyzer v5 (`@salesforce/plugin-code-analyzer`) validates LWC files for SLDS 2 compliance, accessibility, and security.
+
+```bash
+# Install Code Analyzer v5 plugin
+sf plugins install @salesforce/plugin-code-analyzer
+
+# Run scan on LWC components
+sf code-analyzer run \
+  --workspace force-app/main/default/lwc \
+  --output-file lwc-scan-results.html
+
+# Run with specific rules
+sf code-analyzer run \
+  --workspace force-app/main/default/lwc \
+  --rule-selector "Category:Best Practices,Security"
+```
+
+> **Migration from sfdx-scanner**: v5 uses `--workspace` instead of `--target`, `--output-file` instead of `--outfile` (format inferred from extension), `--view` for table/detail display, and `--rule-selector` instead of `--engine`/`--category`.
+
+### SLDS 2 Compliance Checks
+
+```bash
+# Check for hardcoded colors (breaks dark mode)
+rg -n '#[0-9A-Fa-f]{3,8}' force-app/main/default/lwc/**/*.css
+
+# Find deprecated SLDS 1 tokens
+rg -n '\-\-lwc\-' force-app/main/default/lwc/**/*.css
+
+# Find missing alternative-text on icons
+rg -n '<lightning-icon' force-app/main/default/lwc/**/*.html | \
+  rg -v 'alternative-text'
+
+# Check for !important overrides
+rg -n '!important' force-app/main/default/lwc/**/*.css
+```
+
+### Dark Mode Validation
+
+```bash
+# Find all hardcoded colors that may break dark mode
+rg -n 'rgb\(|rgba\(|#[0-9A-Fa-f]{3,8}' \
+  force-app/main/default/lwc/**/*.css \
+  --glob '!**/node_modules/**'
+
+# Verify CSS variables usage (SLDS 2 global hooks)
+rg -n '\-\-slds-g-color' force-app/main/default/lwc/**/*.css
+```
+
+---
+
+## GraphQL Debugging
+
+### GraphQL Wire Service
+
+```bash
+# View GraphQL queries in debug mode (enable in Setup → Debug Logs)
+sf apex tail log --target-org my-sandbox --color
+# Note: Debug levels are configured via TraceFlag records in Setup, not CLI flags
+
+# Test GraphQL query via Anonymous Apex (for syntax validation)
+sf apex run --target-org my-sandbox <<'EOF'
+// GraphQL syntax can't be tested directly in Apex
+// But you can verify field access:
+System.debug([SELECT Id, Name FROM Account LIMIT 1]);
+EOF
+```
+
+### GraphQL Troubleshooting
+
+| Issue | Possible Cause | Solution |
+|-------|---------------|----------|
+| "Field not found" | FLS restriction | Check user has read access |
+| "Object not supported" | GraphQL scope | Not all objects support GraphQL |
+| Cursor pagination fails | Invalid cursor | Use exact cursor from `pageInfo.endCursor` |
+| Null data | Query error | Check `errors` array in wire result |
+
+### Monitor GraphQL Performance
+
+```bash
+# Open Developer Console for network inspection
+sf org open --target-org my-sandbox \
+  --path /lightning/setup/ApexDebugLogDetail/home
+
+# View Event Monitoring logs (if enabled)
+sf data query \
+  --query "SELECT EventType, LogDate FROM EventLogFile WHERE EventType='LightningPageView' ORDER BY LogDate DESC LIMIT 5" \
+  --target-org my-sandbox
+```
+
+---
+
+## Workspace API (Console Apps)
+
+### Console Detection
+
+```bash
+# Check if an app is a Console app
+sf data query \
+  --query "SELECT DeveloperName, NavType FROM AppDefinition WHERE NavType='Console'" \
+  --target-org my-sandbox
+
+# List all Lightning Apps
+sf data query \
+  --query "SELECT DeveloperName, NavType, Label FROM AppDefinition ORDER BY Label" \
+  --target-org my-sandbox
+```
+
+### Console App Testing
+
+```bash
+# Open Service Console
+sf org open --target-org my-sandbox \
+  --path /lightning/app/standard__ServiceConsole
+
+# Open Sales Console
+sf org open --target-org my-sandbox \
+  --path /lightning/app/standard__SalesConsole
+
+# Open custom console app
+sf org open --target-org my-sandbox \
+  --path /lightning/app/c__MyConsoleApp
+```