CMA Debugging

Create Magento App is a Node.js application and can be debugged just like any other Node.js application without any additional configuration. The easiest and the preferred way of debugging CMA is via VSCode.

In order to debug with VSCode, you will need Node.js 11 or late and the setup is very simple:

  1. Open up package.json in the project root folder.

  2. The "Debug" button will appear above the "scripts" section.

  3. Press the "Debug" button and select a script that you want to debug.

  4. Set breakpoints and happy debugging!

During the CMA runtime, a list of steps or tasks is displayed in the terminal, which further simplifies the process of identifying the problem. The code for each task is isolated into its own file or function and is easily accessible in the code. Create Magento App is using @scandipwa/magento-scripts package that is located inside the node_modules folder to store all of the logic.

Identifying the problem

In case the CMA installation failed, one of the tasks will be marked with a red cross. This is the task where something went wrong:

CMA installation has failed at one of the tasks

Most of the time, you will be given a human-readable error message explaining the problem and offering a solution. In case of an unexpected error, however, you might not be given any viable information and an immediate solution.

In order to debug CMA installation, the only thing you need to know is the name of the task, "Configuring PHP extensions" in my case. As mentioned above, all of the related code is located inside of node_modules/@scandipwa/magento-scripts folder and we will need to find that particular task in the code.

Finding the task using VSCode

In most cases, a task can be found using the search functionality of your code editor. In some cases, however, the name of the task is set dynamically, such as "Using PHP version 7.4.13, checking extensions...". With this particular task, you can either search for just "Using PHP version" to find the place where it's set or find the task manually in the list of tasks.

The list of all tasks for a command is located inside the corresponding file in the node_modules/@scandipwa/magento-scripts/lib/tasks folder. As I am trying to debug the yarn start command, I can find the list of tasks in the node_modules/@scandipwa/magento-scripts/lib/tasks/start.js file.

Tasks for CMA start command

From the start command output, I know that the task that didn't run correctly went right after the "Saving Configuration" task that is easily locatable in the task list (line 33). And this means that the failed task is visible in the code by the name of installPhp. From that file, I can find the place where the computed task title is created,

Place where the task name is generated

And I can immediately see what's run next. In this case, a new task is executed, which happens to be the "Configuring PHP extensions" task that failed during the build. Now I am able to set the breakpoint inside of that task

Setting the breakpoint inside of the failed task

Debugging

Now I can run the debugger from the package.json in the project root.

Running the debugger from package.json using the "Debug" button

The breakpoint will be triggered and now I will be able to debug the task line by line to identify and solve the problem.

Breakpoint triggered during the "yarn start" script