Enforce Organizational Best Practices with a Local Plugin

Every repository has a unique set of conventions and best practices that developers need to learn in order to write code that integrates well with the rest of the code base. It is important to document those best practices, but developers don't always read the documentation and even if they have read the documentation, they don't consistently follow the documentation every time they perform a task. Nx allows you to encode these best practices in code generators that have been tailored to your specific repository.

In this tutorial, we will create a generator that helps enforce the follow best practices:

Every project in this repository should use Vitest for unit tests.
Every project in this repository should be tagged with a scope:* tag that is chosen from the list of available scopes.
Projects should be placed in folders that match the scope that they are assigned.
Vitest should clear mocks before running tests.

Get Started

Let's first create a new workspace with the create-nx-workspace command:

❯

npx create-nx-workspace myorg --preset=react-integrated --ci=github

Then we , install the @nx/plugin package and generate a plugin:

❯

npx nx add @nx/plugin

❯

npx nx g @nx/plugin:plugin recommended --directory=tools/recommended

This will create a recommended project that contains all your plugin code.

Create a Customized Library Generator

To create a new generator run:

❯

npx nx generate @nx/plugin:generator library --directory="tools/recommended/src/generators/library"

The new generator is located in tools/recommended/src/generators/library. The generator.ts file contains the code that runs the generator. We can delete the files directory since we won't be using it and update the generator.ts file with the following code:

tools/recommended/src/generators/library/generator.ts
import { Tree } from '@nx/devkit';
import { Linter } from '@nx/eslint';
import { libraryGenerator as reactLibraryGenerator } from '@nx/react';
import { LibraryGeneratorSchema } from './schema';

export async function libraryGenerator(
  tree: Tree,
  options: LibraryGeneratorSchema
) {
  const callbackAfterFilesUpdated = await reactLibraryGenerator(tree, {
    ...options,
    projectNameAndRootFormat: 'as-provided',
    linter: Linter.EsLint,
    style: 'css',
    unitTestRunner: 'vitest',
  });

  return callbackAfterFilesUpdated;
}

export default libraryGenerator;

Notice how this generator is calling the @nx/react plugin's library generator with a predetermined list of options. This helps developers to always create projects with the recommended settings.

We're returning the callbackAfterFilesUpdated function because the @nx/react:library generator sometimes needs to install packages from NPM after the file system has been updated by the generator. You can provide your own callback function instead, if you have tasks that rely on actual files being present.

To try out the generator in dry-run mode, use the following command:

❯

npx nx g @myorg/recommended:library test-library --dry-run

Remove the --dry-run flag to actually create a new project.

Add Generator Options

The schema.d.ts file contains all the options that the generator supports. By default, it includes only a name option. Let's add a directory option to pass on to the @nx/react generator.

tools/recommended/src/generators/library/schema.d.ts
export interface LibraryGeneratorSchema {
  name: string;
  directory?: string;
}

More details

The schema.d.ts file is used for type checking inside the implementation file. It should match the properties in schema.json.

The schema files not only provide structure to the CLI, but also allow Nx Console to show an accurate UI for the generator.

Nx Console UI for the library generator

Notice how we made the description argument optional in both the JSON and type files. If we call the generator without passing a directory, the project will be created in a directory with same name as the project. We can test the changes to the generator with the following command:

❯

npx nx g @myorg/recommended:library test-library --directory=nested/directory/test-library --dry-run

Choose a Scope

It can be helpful to tag a library with a scope that matches the application it should be associated with. With these tags in place, you can set up rules for how projects can depend on each other. For our repository, let's say the scopes can be store, api or shared and the default directory structure should match the chosen scope. We can update the generator to encourage developers to maintain this structure.

tools/recommended/src/generators/library/schema.d.ts
export interface LibraryGeneratorSchema {
  name: string;
  scope: string;
  directory?: string;
}

We can check that the scope logic is being applied correctly by running the generator again and specifying a scope.

❯

npx nx g @myorg/recommended:library test-library --scope=shared --dry-run

This should create the test-library in the shared folder.

Configure Tasks

You can also use your Nx plugin to configure how your tasks are run. Usually, organization focused plugins configure tasks by modifying the configuration files for each project. If you have developed your own tooling scripts for your organization, you may want to create an executor or infer tasks, but that process is covered in more detail in the tooling plugin tutorial.

Let's update our library generator to set the clearMocks property to true in the vitest configuration. First we'll run the reactLibraryGenerator and then we'll modify the created files.

tools/recommended/src/generators/library/generator.ts
import { formatFiles, Tree, runTasksInSerial } from '@nx/devkit';
import { Linter } from '@nx/eslint';
import { libraryGenerator as reactLibraryGenerator } from '@nx/react';
import { LibraryGeneratorSchema } from './schema';

export async function libraryGenerator(
  tree: Tree,
  options: LibraryGeneratorSchema
) {
  const directory = options.directory || `${options.scope}/${options.name}`;

  const tasks = [];
  tasks.push(
    await reactLibraryGenerator(tree, {
      ...options,
      tags: `scope:${options.scope}`,
      directory,
      projectNameAndRootFormat: 'as-provided',
      linter: Linter.EsLint,
      style: 'css',
      unitTestRunner: 'vitest',
    })
  );

  updateViteConfiguration(tree, directory);
  await formatFiles(tree);

  return runTasksInSerial(...tasks);
}

function updateViteConfiguration(tree, directory) {
  // Read the vite configuration file
  let viteConfiguration =
    tree.read(`${directory}/vite.config.ts`)?.toString() || '';

  // Modify the configuration
  // This is done with a naive search and replace, but could be done in a more robust way using AST nodes.
  viteConfiguration = viteConfiguration.replace(
    `globals: true,`,
    `globals: true,\n  clearMocks:true,`
  );

  // Write the modified configuration back to the file
  tree.write(`${directory}/vite.config.ts`, viteConfiguration);
}

export default libraryGenerator;

We updated the generator to use some new helper functions from the Nx devkit. Here are a few functions you may find useful. See the full API reference for all the options.

runTasksInSerial - Allows you to collect many callbacks and return them all at the end of the generator.
formatFiles - Run Prettier on the repository
readProjectConfiguration - Get the calculated project configuration for a single project
updateNxJson - Update the nx.json file

Now let's check to make sure that the clearMocks property is set correctly by the generator. First, we'll commit our changes so far. Then, we'll run the generator without the --dry-run flag so we can inspect the file contents.

❯

git add .

❯

git commit -am "library generator"

❯

npx nx g @myorg/recommended:library store-test --scope=store

Next Steps

Now that we have a working library generator, here are some more topics you may want to investigate.

Generate files from EJS templates
Modify files with string replacement or AST transformations

Encourage Adoption

Once you have a set of generators in place in your organization's plugin, the rest of the work is all communication. Let your developers know that the plugin is available and encourage them to use it. These are the most important points to communicate to your developers:

Whenever there are multiple plugins that provide a generator with the same name, use the recommended version
If there are repetitive or error prone processes that they identify, ask the plugin team to write a generator for that process

Now you can go through all the README files in the repository and replace any multiple step instructions with a single line calling a generator.