feat: initial single component preview

Author: bpbuch

command-snapshot.json

@@ -11,8 +11,8 @@
     "alias": [],
     "command": "lightning:dev:component",
     "flagAliases": [],
-    "flagChars": ["n", "o"],
-    "flags": ["flags-dir", "json", "name", "target-org"],
+    "flagChars": ["n"],
+    "flags": ["flags-dir", "json", "name"],
     "plugin": "@salesforce/plugin-lightning-dev"
   },
   {

messages/lightning.dev.component.md

@@ -4,16 +4,33 @@ Preview LWC components in isolation.
 
 # description
 
-Preview LWC components in isolation. Replacement for: https://developer.salesforce.com/docs/platform/sfvscode-extensions/guide/lwclocaldev.html
+Component preview launches an isolated development environment for Lightning Web Components, enabling rapid iteration without needing to deploy changes. The server provides real-time previews of your components through hot module replacement (HMR), automatically refreshing the view when source files are modified.
+
+When running the development server, these changes are immediately reflected:
+
+- Component template (HTML) modifications
+- Styling updates in component CSS files
+- JavaScript logic changes that don't modify the component's API
+- Adding or updating internal component dependencies
+- Modifying static resources used by the component
+
+See the LWC Development Guide for more information about component development best practices and limitations.
 
 # flags.name.summary
 
-Description of a flag.
+Name of a component to preview.
+
+# error.directory
+
+Unable to find components
 
-# flags.name.description
+# error.component
 
-More information about a flag. Don't repeat the summary.
+Unable to determine component name
 
 # examples
 
-- <%= config.bin %> <%= command.id %>
+- Select a component and launch the component preview:
+  <%= config.bin %> <%= command.id %>
+- Launch component preview for "myComponent":
+  <%= config.bin %> <%= command.id %> --name myComponent

messages/prompts.md

@@ -33,3 +33,7 @@ Which device do you want to use for the preview?
 # error.device.enumeration
 
 Unable to enumerate a list of available devices.
+
+# component.select
+
+Which Lightning Web Component would you like to preview (Use arrow keys)

src/commands/lightning/dev/component.ts

@@ -5,48 +5,80 @@
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
 import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
 import { Messages } from '@salesforce/core';
 import { cmpDev } from '@lwrjs/api';
+import { PromptUtils } from '../../../shared/promptUtils.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-lightning-dev', 'lightning.dev.component');
 
-export type LightningDevComponentResult = {
-  path: string;
-};
+const MODULES_DIR = './force-app/main/default/lwc';
 
-export default class LightningDevComponent extends SfCommand<LightningDevComponentResult> {
+function getDirectories(filePath: string): string[] {
+  try {
+    const items = fs.readdirSync(filePath);
+
+    const directories = items.filter((item) => fs.statSync(path.join(filePath, item)).isDirectory());
+
+    return directories;
+  } catch (error) {
+    return [];
+  }
+}
+
+export default class LightningDevComponent extends SfCommand<void> {
   public static readonly summary = messages.getMessage('summary');
   public static readonly description = messages.getMessage('description');
   public static readonly examples = messages.getMessages('examples');
 
   public static readonly flags = {
     name: Flags.string({
       summary: messages.getMessage('flags.name.summary'),
-      description: messages.getMessage('flags.name.description'),
       char: 'n',
-      required: false,
+      requiredOrDefaulted: false,
     }),
-    // TODO should this be required or optional?
-    // We don't technically need this if your components are simple / don't need any data from your org
-    'target-org': Flags.requiredOrg(),
   };
 
-  public async run(): Promise<LightningDevComponentResult> {
+  public async run(): Promise<void> {
     const { flags } = await this.parse(LightningDevComponent);
 
-    const name = flags.name ?? 'world';
-    this.log(`preview component: ${name}`);
+    let name = flags.name;
+    if (!name) {
+      const dirs = getDirectories(path.resolve(MODULES_DIR));
+      if (!dirs) {
+        throw new Error(messages.getMessage('error.directory'));
+      }
+
+      const components = dirs.map((dir) => {
+        const xmlPath = path.resolve(path.join(MODULES_DIR, dir, `${dir}.js-meta.xml`));
+        const xmlContent = fs.readFileSync(xmlPath, 'utf-8');
+        const label = xmlContent.match(/<masterLabel>(.*?)<\/masterLabel>/);
+        const description = xmlContent.match(/<description>(.*?)<\/description>/);
+
+        return {
+          name: dir,
+          label: label ? label[1] : '',
+          description: description ? description[1] : '',
+        };
+      });
+
+      name = await PromptUtils.promptUserToSelectComponent(components);
+      if (!name) {
+        throw new Error(messages.getMessage('error.component'));
+      }
+    }
+
+    this.log('Starting application on port 3000...');
+
+    const port = parseInt(process.env.PORT ?? '3000', 10);
 
-    // TODO implement me
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
     await cmpDev({
-      componentName: name,
+      mode: 'dev',
+      port,
+      name: `c/${name}`,
     });
-
-    return {
-      path: '',
-    };
   }
 }

src/commands/lightning/dev/site.ts

@@ -7,7 +7,7 @@
 import fs from 'node:fs';
 import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
 import { Messages } from '@salesforce/core';
-import { expDev, LocalDevOptions, setupDev } from '@lwrjs/api';
+import { expDev, SitesLocalDevOptions, setupDev } from '@lwrjs/api';
 import { OrgUtils } from '../../../shared/orgUtils.js';
 import { PromptUtils } from '../../../shared/promptUtils.js';
 import { ExperienceSite } from '../../../shared/experience/expSite.js';
@@ -86,7 +86,7 @@ export default class LightningDevSite extends SfCommand<void> {
 
       // Start the dev server
       const port = parseInt(process.env.PORT ?? '3000', 10);
-      const startupParams: LocalDevOptions = {
+      const startupParams: SitesLocalDevOptions = {
         sfCLI: true,
         authToken,
         open: process.env.OPEN_BROWSER === 'false' ? false : true,

src/shared/promptUtils.ts

@@ -90,6 +90,21 @@ export class PromptUtils {
     return response;
   }
 
+  public static async promptUserToSelectComponent(components: Array<Record<string, string>>): Promise<string> {
+    const choices = components.map((component) => ({
+      name: component.label.length > 0 ? component.label : component.name,
+      value: component.name,
+      description: component.description,
+    }));
+
+    const response = await select({
+      message: messages.getMessage('component.select'),
+      choices,
+    });
+
+    return response;
+  }
+
   // returns the shorthand version of a Version object (eg. 17.0.0 => 17, 17.4.0 => 17.4, 17.4.1 => 17.4.1)
   private static getShortVersion(version: Version | string): string {
     // TODO: consider making this function part of the Version class in @lwc-dev-mobile-core