How to Debug an Angular Schematic using Visual Studio Code

Get under the Angular Schematic hood with the Debugger and VS Code

Get under the Angular Schematic hood with the VS Code Debugger.

Being able to debug and walk through code as it executes is fundamental to our development workflow. It is an essential capability that allows us to debug and determine what the code is doing. It can be part of our testing workflow — attaching a debugger and walking through tests in specific scenarios.

Debugging also provides an opportunity to learn how code (that we didn’t implement) works. This is certainly the case with schematics. As Angular developers, we have certainly used schematics on a daily basis while using the Angular CLI. We create new workspaces, projects, services, components, modules, classes and more using the CLI - and we give little thought to what is going on behind the scenes.

However, understanding how schematics work allows us to appreciate the tooling that provides us with so much functionality. But it also helps to learn how to create our own schematics. Therefore, the purpose of this post is to demonstrate:

  • how to debug a schematic
  • configure Visual Studio Code to debug a node program (i.e., a schematic)
  • attach to a debugging process

When you run/execute a Schematic you are running a node program. The specific program we are running is schematic. So, to get started, we'll need a schematic project.


Tooling and Prerequisites

Before, we can create a schematic project using the schematic-cli, we'll need to make sure we have the following packages available to our development environment. Install the following packages using the -g to make them available globally.

npm install -g @angular-devkit/schematics
npm install -g @angular-devkit/schematics-cli

The tooling allows us to create a new schematic project using the schematics collection. Run the schematics command in a terminal.

The output is a list of options for the command.

If you run the --list-schematics option, you will see list of schematics that exist in the schematics collection.

schematics --list-schematics
blank
schematic

Use the schematic item in the collection to create a sample schematic collection with (3) schematics - these samples will assist us in getting familiar with how schematics work.

Note: remove the --dry-run option to create the project.
schematics schematic --name=schematics-debugged --dry-run

Our new schematics project is a collection of (3) schematics. Each of the (3) schematics in the sample project demonstrate various features of what schematics can do and how they can work together (composable schematics). This article will not go into the details of these schematics — it will focus on setting up the environment for debugging only.

Now that you have a new schematic project. You can build and test the the project using these commands:

npm run build
npm run test

Debugged

As mentioned earlier, when we execute the schematics command we are executing a node program and passing in some arguments. In this case, it is a schematic program. The arguments include the specific schematic item name and any other options that we want to pass in.

<program> [arguments...]

Create a new launch.json configuration for the project. The type of configuration to add is node.js - Launch Program. When this specific configuration is selected for debugging, we'll need to target the node program. In this case, it is the schematics.js (from the @angular-devkit/schematics-cli package). The program we want is a Javascript file in the binfolder of the package.

I simplified the access to this program by installing the @angular-devkit/schematics-cli package locally in the project. The program property of the launch configuration requires the file to be a full path to the location of the program or Javascript file. Use the ${workspaceFolder} to provide the full path to the workspace/project folder.

npm install -D @angular-devkit/schematics-cli
  • type: the value is node.
  • request: the value is launch.
  • name: the value can be anything specific to your project
  • program: add the path to the program with ${workspaceFolder}/node_modules/@angular-devkit/schematics-cli/bin/schematics.js
  • args: add each argument individually in the args array. Since we are already in the root of the project (package.json has a schematics property pointing to the collection.json file). You might need to modify the argument if the path to your schematic is different (i.e., if you using a workspace).
  • outFiles: add this property with an empty [].

Open the factory method of the schematic. Typically, this is the index.ts file. Add a break point within the function code.

Hit F5 and the debugger should launch and break on the break point in the factory method. You now have access to all of the secrets and cool things that Schematics can do. You can take a peek into the Tree and get some insight into what is going on behind the scenes.

Wrapping Up

Schematics debugged!!! Now we can use Visual Studio Code with our launch configuration to debug a node program. This provides us with the capabilities to learn and better understand how schematics work.

If you like this article, you might like the Angularlicious Podcast.

Resources