feat: implement dual version support via NPM aliasing and dynamic loading

- Added aliased dependencies for @lwc/lwc-dev-server, @lwc/sfdc-lwc-compiler, and lwc
- Implemented DependencyLoader for dynamic runtime branching based on org API version
- Removed 'version channel' concept in favor of direct API version mapping
- Updated CLI commands to pass org connection for version detection
- Added .husky/check-versions.js to ensure dependency/metadata alignment
- Cleaned up unused VersionResolver and type utilities

Author: abdulsattar

.husky/check-versions.js

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import semver from 'semver';
+
+/**
+ * This script ensures that the aliased dependencies in package.json stay in sync
+ * with the versions defined in apiVersionMetadata.
+ */
+
+// Read package.json
+const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+const apiVersionMetadata = packageJson.apiVersionMetadata;
+
+if (!apiVersionMetadata) {
+  console.error('Error: missing apiVersionMetadata in package.json');
+  process.exit(1);
+}
+
+let hasError = false;
+
+// Iterate through each API version defined in metadata
+for (const [apiVersion, metadata] of Object.entries(apiVersionMetadata)) {
+  const expectedDeps = metadata.dependencies;
+  if (!expectedDeps) continue;
+
+  for (const [depName, expectedRange] of Object.entries(expectedDeps)) {
+    // For each dependency in metadata, find its aliased counterpart in package.json dependencies
+    // e.g. @lwc/lwc-dev-server -> @lwc/lwc-dev-server-65.0
+    const aliasName = `${depName}-${apiVersion}`;
+    const actualAliasValue = packageJson.dependencies[aliasName];
+
+    if (!actualAliasValue) {
+      console.error(`Error: Missing aliased dependency '${aliasName}' in package.json for API version ${apiVersion}`);
+      hasError = true;
+      continue;
+    }
+
+    // actualAliasValue looks like "npm:@lwc/lwc-dev-server@~13.2.x" or "npm:lwc@~8.23.x"
+    // We want to extract the version range after the last @
+    const match = actualAliasValue.match(/@([^@]+)$/);
+    if (!match) {
+      console.error(`Error: Could not parse version range from aliased dependency '${aliasName}': ${actualAliasValue}`);
+      hasError = true;
+      continue;
+    }
+
+    const actualRange = match[1];
+
+    // Compare the range in metadata with the range in the aliased dependency
+    if (!semver.intersects(expectedRange, actualRange)) {
+      console.error(
+        `Error: Version mismatch for '${aliasName}'. ` +
+          `Expected ${expectedRange} in apiVersionMetadata, but found ${actualRange} in dependencies.`,
+      );
+      hasError = true;
+    }
+  }
+}
+
+if (hasError) {
+  console.error(
+    '\nWhen updating LWC dependencies, you must ensure that the versions in apiVersionMetadata match the aliased dependencies in package.json.',
+  );
+  process.exit(1);
+}
+
+process.exit(0);

.husky/pre-commit

@@ -1,4 +1,7 @@
 #!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 
+# Run the custom version check script
+node .husky/check-versions.js
+
 yarn lint && yarn pretty-quick --staged

command-snapshot.json

@@ -4,23 +4,23 @@
     "command": "lightning:dev:app",
     "flagAliases": [],
     "flagChars": ["i", "n", "o", "t"],
-    "flags": ["device-id", "device-type", "flags-dir", "name", "target-org", "version-channel"],
+    "flags": ["device-id", "device-type", "flags-dir", "name", "target-org"],
     "plugin": "@salesforce/plugin-lightning-dev"
   },
   {
     "alias": [],
     "command": "lightning:dev:component",
     "flagAliases": [],
     "flagChars": ["c", "n", "o"],
-    "flags": ["api-version", "client-select", "flags-dir", "json", "name", "target-org", "version-channel"],
+    "flags": ["api-version", "client-select", "flags-dir", "json", "name", "target-org"],
     "plugin": "@salesforce/plugin-lightning-dev"
   },
   {
     "alias": [],
     "command": "lightning:dev:site",
     "flagAliases": [],
     "flagChars": ["l", "n", "o"],
-    "flags": ["flags-dir", "get-latest", "guest", "name", "ssr", "target-org", "version-channel"],
+    "flags": ["flags-dir", "get-latest", "guest", "name", "ssr", "target-org"],
     "plugin": "@salesforce/plugin-lightning-dev"
   }
 ]

messages/lightning.dev.app.md

@@ -31,14 +31,6 @@ Type of device to display the app preview.
 
 ID of the mobile device to display the preview if device type is set to `ios` or `android`. The default value is the ID of the first available mobile device.
 
-# flags.version-channel.summary
-
-Manually specify which version channel to use (latest, prerelease, or next).
-
-# flags.version-channel.description
-
-Override automatic version detection and force a specific dependency channel. Useful for testing and debugging. Valid values: "latest", "prerelease", "next".
-
 # error.fetching.app-id
 
 Unable to determine App Id for %s

messages/lightning.dev.component.md

@@ -24,14 +24,6 @@ Name of a component to preview.
 
 Launch component preview without selecting a component
 
-# flags.version-channel.summary
-
-Manually specify which version channel to use (latest, prerelease, or next).
-
-# flags.version-channel.description
-
-Override automatic version detection and force a specific dependency channel. Useful for testing and debugging. Valid values: "latest", "prerelease", "next".
-
 # error.directory
 
 Unable to find components

messages/lightning.dev.site.md

@@ -33,14 +33,6 @@ Preview the site as a guest user (rather than an authenticated user).
 
 Preview the SSR bundle
 
-# flags.version-channel.summary
-
-Manually specify which version channel to use (latest, prerelease, or next).
-
-# flags.version-channel.description
-
-Override automatic version detection and force a specific dependency channel. Useful for testing and debugging. Valid values: "latest", "prerelease", "next".
-
 # examples
 
 - Select a site to preview from the org "myOrg":

package.json

@@ -8,13 +8,13 @@
     "@inquirer/prompts": "^5.3.8",
     "@inquirer/select": "^2.4.7",
     "@lwc/lwc-dev-server": "~13.3.8",
-    "@lwc/lwc-dev-server-latest": "npm:@lwc/lwc-dev-server@~13.2.x",
-    "@lwc/lwc-dev-server-next": "npm:@lwc/lwc-dev-server@~13.3.x",
-    "@lwc/lwc-dev-server-prerelease": "npm:@lwc/lwc-dev-server@~13.3.x",
+    "@lwc/lwc-dev-server-65.0": "npm:@lwc/lwc-dev-server@~13.2.x",
+    "@lwc/lwc-dev-server-66.0": "npm:@lwc/lwc-dev-server@~13.3.x",
+    "@lwc/lwc-dev-server-67.0": "npm:@lwc/lwc-dev-server@~13.3.x",
     "@lwc/sfdc-lwc-compiler": "~13.3.8",
-    "@lwc/sfdc-lwc-compiler-latest": "npm:@lwc/sfdc-lwc-compiler@~13.2.x",
-    "@lwc/sfdc-lwc-compiler-next": "npm:@lwc/sfdc-lwc-compiler@~13.3.x",
-    "@lwc/sfdc-lwc-compiler-prerelease": "npm:@lwc/sfdc-lwc-compiler@~13.3.x",
+    "@lwc/sfdc-lwc-compiler-65.0": "npm:@lwc/sfdc-lwc-compiler@~13.2.x",
+    "@lwc/sfdc-lwc-compiler-66.0": "npm:@lwc/sfdc-lwc-compiler@~13.3.x",
+    "@lwc/sfdc-lwc-compiler-67.0": "npm:@lwc/sfdc-lwc-compiler@~13.3.x",
     "@lwrjs/api": "0.18.3",
     "@oclif/core": "^4.5.6",
     "@salesforce/core": "^8.24.0",
@@ -24,9 +24,9 @@
     "axios": "^1.13.2",
     "glob": "^13.0.0",
     "lwc": "~8.27.0",
-    "lwc-latest": "npm:lwc@~8.23.x",
-    "lwc-next": "npm:lwc@~8.24.x",
-    "lwc-prerelease": "npm:lwc@~8.24.x",
+    "lwc-65.0": "npm:lwc@~8.23.x",
+    "lwc-66.0": "npm:lwc@~8.24.x",
+    "lwc-67.0": "npm:lwc@~8.24.x",
     "node-fetch": "^3.3.2",
     "open": "^10.2.0",
     "xml2js": "^0.6.2"
@@ -52,7 +52,7 @@
     "typescript": "^5.5.4"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "files": [
     "/lib",
@@ -241,65 +241,27 @@
     }
   },
   "apiVersionMetadata": {
-    "channels": {
-      "latest": {
-        "supportedApiVersions": [
-          "65.0"
-        ],
-        "dependencies": {
-          "@lwc/lwc-dev-server": "~13.2.x",
-          "@lwc/sfdc-lwc-compiler": "~13.2.x",
-          "lwc": "~8.23.x"
-        }
-      },
-      "prerelease": {
-        "supportedApiVersions": [
-          "66.0"
-        ],
-        "dependencies": {
-          "@lwc/lwc-dev-server": "~13.3.x",
-          "@lwc/sfdc-lwc-compiler": "~13.3.x",
-          "lwc": "~8.24.x"
-        }
-      },
-      "next": {
-        "supportedApiVersions": [
-          "67.0"
-        ],
-        "dependencies": {
-          "@lwc/lwc-dev-server": "~13.3.x",
-          "@lwc/sfdc-lwc-compiler": "~13.3.x",
-          "lwc": "~8.24.x"
-        }
+    "65.0": {
+      "dependencies": {
+        "@lwc/lwc-dev-server": "~13.2.x",
+        "@lwc/sfdc-lwc-compiler": "~13.2.x",
+        "lwc": "~8.23.x"
       }
     },
-    "defaultChannel": "latest",
-    "versionToTagMappings": [
-      {
-        "versionNumber": "62.0",
-        "tagName": "v1"
-      },
-      {
-        "versionNumber": "63.0",
-        "tagName": "v2"
-      },
-      {
-        "versionNumber": "64.0",
-        "tagName": "v3"
-      },
-      {
-        "versionNumber": "65.0",
-        "tagName": "latest"
-      },
-      {
-        "versionNumber": "66.0",
-        "tagName": "prerelease"
-      },
-      {
-        "versionNumber": "67.0",
-        "tagName": "next"
+    "66.0": {
+      "dependencies": {
+        "@lwc/lwc-dev-server": "~13.3.x",
+        "@lwc/sfdc-lwc-compiler": "~13.3.x",
+        "lwc": "~8.24.x"
       }
-    ]
+    },
+    "67.0": {
+      "dependencies": {
+        "@lwc/lwc-dev-server": "~13.3.x",
+        "@lwc/sfdc-lwc-compiler": "~13.3.x",
+        "lwc": "~8.24.x"
+      }
+    }
   },
   "exports": "./lib/index.js",
   "type": "module",

src/commands/lightning/dev/app.ts

@@ -30,7 +30,6 @@ import { startLWCServer } from '../../../lwc-dev-server/index.js';
 import { PreviewUtils } from '../../../shared/previewUtils.js';
 import { PromptUtils } from '../../../shared/promptUtils.js';
 import { MetaUtils } from '../../../shared/metaUtils.js';
-import { VersionChannel } from '../../../shared/versionResolver.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-lightning-dev', 'lightning.dev.app');
@@ -70,12 +69,6 @@ export default class LightningDevApp extends SfCommand<void> {
       summary: messages.getMessage('flags.device-id.summary'),
       char: 'i',
     }),
-    'version-channel': Flags.string({
-      summary: messages.getMessage('flags.version-channel.summary'),
-      description: messages.getMessage('flags.version-channel.description'),
-      options: ['latest', 'prerelease', 'next'],
-      required: false,
-    }),
   };
 
   public async run(): Promise<void> {
@@ -118,8 +111,6 @@ export default class LightningDevApp extends SfCommand<void> {
     const ldpServerUrl = PreviewUtils.generateWebSocketUrlForLocalDevServer(platform, serverPorts, logger);
     logger.debug(`Local Dev Server url is ${ldpServerUrl}`);
 
-    const versionChannel = flags['version-channel'] as VersionChannel | undefined;
-
     if (platform === Platform.desktop) {
       await this.desktopPreview(
         targetOrg,
@@ -130,7 +121,6 @@ export default class LightningDevApp extends SfCommand<void> {
         ldpServerUrl,
         appId,
         logger,
-        versionChannel
       );
     } else {
       await this.mobilePreview(
@@ -145,7 +135,6 @@ export default class LightningDevApp extends SfCommand<void> {
         appId,
         deviceId,
         logger,
-        versionChannel
       );
     }
   }
@@ -159,7 +148,6 @@ export default class LightningDevApp extends SfCommand<void> {
     ldpServerUrl: string,
     appId: string | undefined,
     logger: Logger,
-    versionChannelOverride?: VersionChannel
   ): Promise<void> {
     if (!appId) {
       logger.debug('No Lightning Experience application name provided.... using the default app instead.');
@@ -175,7 +163,7 @@ export default class LightningDevApp extends SfCommand<void> {
       ldpServerUrl,
       ldpServerId,
       appId,
-      targetOrgArg
+      targetOrgArg,
     );
 
     // Start the LWC Dev Server
@@ -188,7 +176,6 @@ export default class LightningDevApp extends SfCommand<void> {
       serverPorts,
       undefined,
       undefined,
-      versionChannelOverride
     );
 
     // Open the browser and navigate to the right page
@@ -207,7 +194,6 @@ export default class LightningDevApp extends SfCommand<void> {
     appId: string | undefined,
     deviceId: string | undefined,
     logger: Logger,
-    versionChannelOverride?: VersionChannel
   ): Promise<void> {
     try {
       // Verify that user environment is set up for mobile (i.e. has right tooling)
@@ -278,7 +264,7 @@ export default class LightningDevApp extends SfCommand<void> {
           platform,
           logger,
           this.spinner,
-          this.progress
+          this.progress,
         );
 
         // on iOS the bundle comes as a ZIP archive so we need to extract it first
@@ -307,7 +293,6 @@ export default class LightningDevApp extends SfCommand<void> {
         serverPorts,
         certData,
         undefined,
-        versionChannelOverride
       );
 
       // Launch the native app for previewing (launchMobileApp will show its own spinner)
@@ -316,7 +301,7 @@ export default class LightningDevApp extends SfCommand<void> {
         ldpServerUrl,
         ldpServerId,
         appName,
-        appId
+        appId,
       );
       const targetActivity = (appConfig as AndroidAppPreviewConfig)?.activity;
       const targetApp = targetActivity ? `${appConfig.id}/${targetActivity}` : appConfig.id;