@salesforce/webapp-template-cli-experimental 1.33.6 → 1.34.0

package/README.md

@@ -1453,6 +1453,159 @@ it("should merge routes correctly", () => {
 });
 ```
 
+## Nx Plugin Executors
+
+This package provides Nx executors for integrating the template CLI with Nx workspaces. The executors automate applying patches and building feature apps within the monorepo.
+
+### Available Executors
+
+#### `apply-patches`
+
+Applies template patches to create feature apps. This executor wraps the `apply-patches` CLI command and automatically determines paths based on the Nx project configuration.
+
+**Usage in `package.json`:**
+
+```json
+{
+  "nx": {
+    "targets": {
+      "build": {
+        "executor": "@salesforce/webapp-template-cli-experimental:apply-patches"
+      }
+    }
+  }
+}
+```
+
+**Options:**
+
+- `baseAppPath` (string, optional): Path to the base app directory (relative to workspace root)
+  - Default: `"packages/template/base-app/base-react-app"`
+- `reset` (boolean, optional): Reset target directory to base app state before applying patches
+  - Default: `true`
+- `skipDependencyChanges` (boolean, optional): Skip installing dependencies from package.json
+  - Default: `false`
+- `outputDir` (string, optional): Output directory name (relative to project root)
+  - Default: `"dist"`
+
+**Example with options:**
+
+```json
+{
+  "nx": {
+    "targets": {
+      "build": {
+        "executor": "@salesforce/webapp-template-cli-experimental:apply-patches",
+        "options": {
+          "reset": true,
+          "skipDependencyChanges": false,
+          "outputDir": "dist"
+        }
+      }
+    }
+  }
+}
+```
+
+**Workspace-level configuration (`nx.json`):**
+
+You can set default options for all projects in `nx.json`:
+
+```json
+{
+  "targetDefaults": {
+    "@salesforce/webapp-template-cli-experimental:apply-patches": {
+      "cache": true,
+      "inputs": [
+        "{projectRoot}/src/**/*",
+        "{projectRoot}/feature.ts",
+        "{projectRoot}/package.json",
+        "{workspaceRoot}/packages/template/base-app/base-react-app/**/*"
+      ],
+      "outputs": ["{projectRoot}/dist"],
+      "options": {
+        "reset": true,
+        "skipDependencyChanges": false
+      }
+    }
+  }
+}
+```
+
+#### `build-dist-app`
+
+Builds the application in the dist folder by running `npm ci` and `npm run build`. This executor is useful for building feature apps after patches have been applied.
+
+**Usage in `package.json`:**
+
+```json
+{
+  "nx": {
+    "targets": {
+      "test": {
+        "executor": "@salesforce/webapp-template-cli-experimental:build-dist-app"
+      }
+    }
+  }
+}
+```
+
+**Options:**
+
+This executor has no configurable options. It automatically determines the build path based on the project structure.
+
+**Workspace-level configuration (`nx.json`):**
+
+```json
+{
+  "targetDefaults": {
+    "@salesforce/webapp-template-cli-experimental:build-dist-app": {
+      "cache": true,
+      "inputs": ["{projectRoot}/dist/**/*"],
+      "outputs": ["{projectRoot}/dist"],
+      "dependsOn": ["build"]
+    }
+  }
+}
+```
+
+### Running Executors
+
+Once configured, you can run the executors using Nx:
+
+```bash
+# Apply patches to a feature project
+nx build feature-react-global-search
+
+# Build the dist app
+nx test feature-react-global-search
+
+# Run both in sequence (test depends on build)
+nx run-many -t build test
+```
+
+### How It Works
+
+1. **apply-patches executor**:
+   - Reads project configuration from Nx workspace
+   - Determines feature path and base app path
+   - Calls the CLI's `applyPatchesCommand` function
+   - Creates the dist directory with merged feature and base app files
+
+2. **build-dist-app executor**:
+   - Locates the built application in `dist/force-app/main/default/webapplications/<project-name>/`
+   - Runs `npm ci` to install dependencies
+   - Runs `npm run build` to build the application
+   - Suitable for CI/CD pipelines and automated testing
+
+### Benefits
+
+- **Nx Caching**: Both executors support Nx caching for faster builds
+- **Dependency Graph**: Nx understands dependencies between features and builds them in correct order
+- **Workspace Integration**: Seamlessly integrates with Nx workspace commands
+- **Type Safety**: Full TypeScript support with schema validation
+- **Incremental Builds**: Only rebuilds projects when inputs change
+
 ## Development
 
 ```bash

package/dist/nx-plugin/executors/apply-patches/executor.d.ts

@@ -0,0 +1,20 @@
+import { type ExecutorContext } from "@nx/devkit";
+import type { ApplyPatchesExecutorOptions } from "./schema";
+/**
+ * Result of the executor
+ */
+export interface ApplyPatchesExecutorResult {
+    success: boolean;
+}
+/**
+ * Nx executor for applying template patches
+ *
+ * This executor wraps the apply-patches CLI command and automatically determines paths
+ * based on the Nx project configuration.
+ *
+ * @param options - Executor options
+ * @param context - Nx executor context
+ * @returns Executor result with success status
+ */
+export default function runExecutor(options: ApplyPatchesExecutorOptions, context: ExecutorContext): Promise<ApplyPatchesExecutorResult>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/nx-plugin/executors/apply-patches/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../../src/nx-plugin/executors/apply-patches/executor.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,eAAe,EAAU,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,0BAA0B;IAC1C,OAAO,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAA8B,WAAW,CACxC,OAAO,EAAE,2BAA2B,EACpC,OAAO,EAAE,eAAe,GACtB,OAAO,CAAC,0BAA0B,CAAC,CAgErC"}

package/dist/nx-plugin/executors/apply-patches/executor.js

@@ -0,0 +1,73 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { execSync } from "child_process";
+import { join } from "path";
+import { logger } from "@nx/devkit";
+/**
+ * Nx executor for applying template patches
+ *
+ * This executor wraps the apply-patches CLI command and automatically determines paths
+ * based on the Nx project configuration.
+ *
+ * @param options - Executor options
+ * @param context - Nx executor context
+ * @returns Executor result with success status
+ */
+export default async function runExecutor(options, context) {
+    try {
+        // Validate that we have a project name
+        if (!context.projectName) {
+            logger.error("Project name is required");
+            return { success: false };
+        }
+        // Get project configuration
+        const project = context.projectGraph?.nodes[context.projectName];
+        if (!project) {
+            logger.error(`Project ${context.projectName} not found in project graph`);
+            return { success: false };
+        }
+        // Get workspace root (absolute path)
+        const workspaceRoot = context.root;
+        // Get project root (relative to workspace root)
+        const projectRoot = project.data.root;
+        // Build paths for CLI command
+        const baseAppPath = options.baseAppPath || "packages/template/base-app/base-react-app";
+        const outputDir = options.outputDir || "dist";
+        logger.info(`Applying patches for ${context.projectName}...`);
+        logger.info(`  Feature path: ${projectRoot}`);
+        logger.info(`  Base app: ${baseAppPath}`);
+        logger.info(`  Output: ${join(projectRoot, outputDir)}`);
+        // Execute the CLI command via npx tsx
+        const cliPath = "packages/template/cli/src/index.ts";
+        const outputPath = join(projectRoot, outputDir);
+        /*
+         * Unfortunately using applyPatchesCommand directly encounters module import errors
+         * when it comes to `feature.ts`
+         */
+        // Build command with arguments
+        let command = `npx tsx ${cliPath} apply-patches ${projectRoot} ${baseAppPath} ${outputPath}`;
+        // Add flags
+        if (options.reset !== false) {
+            command += " --reset";
+        }
+        if (options.skipDependencyChanges) {
+            command += " --skip-dependency-changes";
+        }
+        logger.info(`  Executing: ${command}`);
+        execSync(command, {
+            cwd: workspaceRoot,
+            stdio: "inherit",
+            env: process.env,
+        });
+        return { success: true };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Failed to apply patches: ${errorMessage}`);
+        return { success: false };
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/nx-plugin/executors/apply-patches/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../src/nx-plugin/executors/apply-patches/executor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAwB,MAAM,EAAE,MAAM,YAAY,CAAC;AAU1D;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,WAAW,CACxC,OAAoC,EACpC,OAAwB;IAExB,IAAI,CAAC;QACJ,uCAAuC;QACvC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YAC1B,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;YACzC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC3B,CAAC;QAED,4BAA4B;QAC5B,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACjE,IAAI,CAAC,OAAO,EAAE,CAAC;YACd,MAAM,CAAC,KAAK,CAAC,WAAW,OAAO,CAAC,WAAW,6BAA6B,CAAC,CAAC;YAC1E,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC3B,CAAC;QAED,qCAAqC;QACrC,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;QAEnC,gDAAgD;QAChD,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAEtC,8BAA8B;QAC9B,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,2CAA2C,CAAC;QACvF,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;QAE9C,MAAM,CAAC,IAAI,CAAC,wBAAwB,OAAO,CAAC,WAAW,KAAK,CAAC,CAAC;QAC9D,MAAM,CAAC,IAAI,CAAC,mBAAmB,WAAW,EAAE,CAAC,CAAC;QAC9C,MAAM,CAAC,IAAI,CAAC,eAAe,WAAW,EAAE,CAAC,CAAC;QAC1C,MAAM,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;QAEzD,sCAAsC;QACtC,MAAM,OAAO,GAAG,oCAAoC,CAAC;QACrD,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QAEhD;;;WAGG;QAEH,+BAA+B;QAC/B,IAAI,OAAO,GAAG,WAAW,OAAO,kBAAkB,WAAW,IAAI,WAAW,IAAI,UAAU,EAAE,CAAC;QAE7F,YAAY;QACZ,IAAI,OAAO,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;YAC7B,OAAO,IAAI,UAAU,CAAC;QACvB,CAAC;QACD,IAAI,OAAO,CAAC,qBAAqB,EAAE,CAAC;YACnC,OAAO,IAAI,4BAA4B,CAAC;QACzC,CAAC;QAED,MAAM,CAAC,IAAI,CAAC,gBAAgB,OAAO,EAAE,CAAC,CAAC;QAEvC,QAAQ,CAAC,OAAO,EAAE;YACjB,GAAG,EAAE,aAAa;YAClB,KAAK,EAAE,SAAS;YAChB,GAAG,EAAE,OAAO,CAAC,GAAG;SAChB,CAAC,CAAC;QAEH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,MAAM,CAAC,KAAK,CAAC,4BAA4B,YAAY,EAAE,CAAC,CAAC;QACzD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC3B,CAAC;AACF,CAAC"}

package/dist/nx-plugin/executors/build-dist-app/executor.d.ts

@@ -0,0 +1,19 @@
+import { type ExecutorContext } from "@nx/devkit";
+import type { BuildDistAppExecutorOptions } from "./schema";
+/**
+ * Result of the executor
+ */
+export interface BuildDistAppExecutorResult {
+    success: boolean;
+}
+/**
+ * Nx executor for building the application in the dist folder
+ *
+ * This executor navigates to the project's dist folder and runs npm ci followed by npm run build.
+ *
+ * @param options - Executor options
+ * @param context - Nx executor context
+ * @returns Executor result with success status
+ */
+export default function runExecutor(options: BuildDistAppExecutorOptions, context: ExecutorContext): Promise<BuildDistAppExecutorResult>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/nx-plugin/executors/build-dist-app/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../../src/nx-plugin/executors/build-dist-app/executor.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,eAAe,EAAU,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,0BAA0B;IAC1C,OAAO,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAA8B,WAAW,CACxC,OAAO,EAAE,2BAA2B,EACpC,OAAO,EAAE,eAAe,GACtB,OAAO,CAAC,0BAA0B,CAAC,CAyDrC"}

package/dist/nx-plugin/executors/build-dist-app/executor.js

@@ -0,0 +1,63 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { execSync } from "child_process";
+import { join, basename } from "path";
+import { logger } from "@nx/devkit";
+/**
+ * Nx executor for building the application in the dist folder
+ *
+ * This executor navigates to the project's dist folder and runs npm ci followed by npm run build.
+ *
+ * @param options - Executor options
+ * @param context - Nx executor context
+ * @returns Executor result with success status
+ */
+export default async function runExecutor(options, context) {
+    try {
+        // Validate that we have a project name
+        if (!context.projectName) {
+            logger.error("Project name is required");
+            return { success: false };
+        }
+        // Get project configuration
+        const project = context.projectGraph?.nodes[context.projectName];
+        if (!project) {
+            logger.error(`Project ${context.projectName} not found in project graph`);
+            return { success: false };
+        }
+        // Get workspace root (absolute path)
+        const workspaceRoot = context.root;
+        // Get project root (relative to workspace root)
+        const projectRoot = project.data.root;
+        // Get the folder name from the project root path
+        const projectFolderName = basename(projectRoot);
+        // Build the path to the dist folder (static path)
+        const targetPath = join(workspaceRoot, projectRoot, "dist/force-app/main/default/webapplications", projectFolderName);
+        logger.info(`Building application in ${targetPath}...`);
+        // Execute npm ci
+        logger.info("Running npm ci...");
+        execSync("npm ci", {
+            cwd: targetPath,
+            stdio: "inherit",
+            env: process.env,
+        });
+        // Execute npm run build
+        logger.info("Running npm run build...");
+        execSync("npm run build", {
+            cwd: targetPath,
+            stdio: "inherit",
+            env: process.env,
+        });
+        logger.info("Build completed successfully");
+        return { success: true };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Failed to build dist app: ${errorMessage}`);
+        return { success: false };
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/nx-plugin/executors/build-dist-app/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../src/nx-plugin/executors/build-dist-app/executor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AACtC,OAAO,EAAwB,MAAM,EAAE,MAAM,YAAY,CAAC;AAU1D;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,WAAW,CACxC,OAAoC,EACpC,OAAwB;IAExB,IAAI,CAAC;QACJ,uCAAuC;QACvC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YAC1B,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;YACzC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC3B,CAAC;QAED,4BAA4B;QAC5B,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACjE,IAAI,CAAC,OAAO,EAAE,CAAC;YACd,MAAM,CAAC,KAAK,CAAC,WAAW,OAAO,CAAC,WAAW,6BAA6B,CAAC,CAAC;YAC1E,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC3B,CAAC;QAED,qCAAqC;QACrC,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;QAEnC,gDAAgD;QAChD,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAEtC,iDAAiD;QACjD,MAAM,iBAAiB,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;QAEhD,kDAAkD;QAClD,MAAM,UAAU,GAAG,IAAI,CACtB,aAAa,EACb,WAAW,EACX,6CAA6C,EAC7C,iBAAiB,CACjB,CAAC;QAEF,MAAM,CAAC,IAAI,CAAC,2BAA2B,UAAU,KAAK,CAAC,CAAC;QAExD,iBAAiB;QACjB,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QACjC,QAAQ,CAAC,QAAQ,EAAE;YAClB,GAAG,EAAE,UAAU;YACf,KAAK,EAAE,SAAS;YAChB,GAAG,EAAE,OAAO,CAAC,GAAG;SAChB,CAAC,CAAC;QAEH,wBAAwB;QACxB,MAAM,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;QACxC,QAAQ,CAAC,eAAe,EAAE;YACzB,GAAG,EAAE,UAAU;YACf,KAAK,EAAE,SAAS;YAChB,GAAG,EAAE,OAAO,CAAC,GAAG;SAChB,CAAC,CAAC;QAEH,MAAM,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;QAC5C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,MAAM,CAAC,KAAK,CAAC,6BAA6B,YAAY,EAAE,CAAC,CAAC;QAC1D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC3B,CAAC;AACF,CAAC"}

package/executors.json

@@ -0,0 +1,14 @@
+{
+  "executors": {
+    "apply-patches": {
+      "implementation": "./src/nx-plugin/executors/apply-patches/executor.ts",
+      "schema": "./src/nx-plugin/executors/apply-patches/schema.json",
+      "description": "Applies template patches to create feature apps"
+    },
+    "build-dist-app": {
+      "implementation": "./src/nx-plugin/executors/build-dist-app/executor.ts",
+      "schema": "./src/nx-plugin/executors/build-dist-app/schema.json",
+      "description": "Builds the application in the dist folder by running npm ci and npm run build"
+    }
+  }
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@salesforce/webapp-template-cli-experimental",
-  "version": "1.33.6",
+  "version": "1.34.0",
   "description": "CLI tool for applying feature patches to base apps",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "executors.json"
   ],
   "publishConfig": {
     "access": "public"
@@ -13,6 +14,7 @@
   "bin": {
     "apply-patches": "./dist/index.js"
   },
+  "executors": "./executors.json",
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",
@@ -24,10 +26,12 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
+    "@nx/devkit": "^20.8.4",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "fs-extra": "^11.2.0",
     "ts-morph": "^27.0.2",
+    "tslib": "^2.8.1",
     "turbowatch": "^2.29.4"
   },
   "devDependencies": {
@@ -41,5 +45,5 @@
     "typescript": "~5.9.3",
     "vitest": "^4.0.17"
   },
-  "gitHead": "bdeda861b2f911cd48fe9379102c2e83a5e769a0"
+  "gitHead": "78cd04e09a42d965201f46edd5850465f7eda353"
 }