white-bricks

Introduction

This is a short guide to help us understand how we can deciper an existing Nx plugin, to figure out what it does. A basic understanding of Nx plugins will be useful to the reader.

Understanding the Plugin’s Behavior

Entrypoint

The best place to start our investigation is with a few files at the root of the plugin.

  • generators.json
  • migrations.json
  • executors.json

These are the entrypoints that define all tasks that the plugin will be able to undertake.

Each contains a json structure that usually links to the related folders (but not necessarily):

Entrypoint Example

For example, generators.json might have the following contents:

{
  "generators": {
    "my-generator": {
      "factory": "./src/generators/my-generator/generator",
      "schema": "./src/generators/my-generator/schema.json",
      "description": "my-generator generator"
    }
  }
}

Notice how we define the factory and schema as paths. These suggest that we can put generator files anywhere we want – but in the name of your own/team’s future sanity, it might be best to avoid doing that.

Entrypoints define the API of the Plugin

The way we interact with the plugin is defined by what we find in each of these entrypoint files mentioned above. These entrypoints hence define the Application Programming Interface or API of our plugin.

Take the example of a command to run a plugin generator:

npx nx generate @nx/web:application

This will search for a generator called “application” in the generator.json file, trace the factory and schema paths, and use this to run a generator.

In our entrypoint example above, the command to run the “my-generator” generator would be something like the following:

npx nx generate <plugin-name>:my-generator

The concept is similiar for migrations, which we can run from the command line, and executors, which we use to define targets.

Pay special attention to init

A special generator is the init generator, which by convention will run on npm install <plugin-name> in the workspace. This generator is used by a plugin to modify a workspace during installation (including the nx.json workspace configuration file), to enable the plugin’s functionality.

This generator is defined like any other as init in generator.json, and conventionally has its implementation found in the src/generators/init folder.

Pitfall: confusion about the project.json file at the plugin root

Most developers familiar with Nx will know about the nx.json and project.json files that provide metadata for an Nx workspace.

Contrary to expectations, the project.json file in most plugin repositories (e.g. @nx/webpack) are not related to our investigation into its behavior. This is because this file is not part of the final plugin that will be built, but rather part of the plugin’s development tooling that builds the final plugin.

In other words, the project.json file at the root of the plugin exists because many plugin developers use Nx to manage their own plugin workspaces. This file hence contributes to the development of the plugin, but not its use.

This is also true for other files like tsconfig.json, jest.config.ts, etc, that would be used in the project’s development.

More Resources

For a better understanding of how Nx plugins work, there is a great tutorial for them in the Nx documentation. Here you can find information about generators, migrations, etc.

Hope this helped to give you a boost.