Create a Custom Plugin Preset

When you create a new nx workspace, you run the command: npx create-nx-workspace. This command accepts a --preset option, for example: npx create-nx-workspace --preset=react-standalone. This preset option is pointing to a special generator function (remember, a generator is a function that simplifies an entire code generation script into a single function) that Nx will call when this npx create-nx-workspace command is run, that will generate your initial workspace.

What is a preset?

At its core, a preset is a special generator that is shipped as part of an Nx Plugin package.

All first-party Nx presets are built into Nx itself, but you can create your own plugin and create a generator with the magic name: preset. Once you've published your plugin on npm, you can now run the create-nx-workspace command with the preset option set to the name of your published package.

To use a concrete example, let's look at the qwik-nx Nx community plugin. They include a preset generator that you can use to create a new Nx workspace with Qwik support.

npx create-nx-workspace --preset=qwik-nx

Create a new Nx plugin

If you don't have an existing plugin you can create one by running

npx create-nx-plugin my-org --pluginName my-plugin

Creating a "Preset" generator

To create our preset inside of our plugin we can run

nx generate @nx/plugin:generator --name=preset --project=happynrwl

Nx 15 and lower use @nrwl/ instead of @nx/
Double check

The word preset is required for the name of this generator

You should have a similar structure to this:

1happynrwl/ 2 ├── e2e 3 ├── jest.config.js 4 ├── jest.preset.js 5 ├── nx.json 6 ├── package-lock.json 7 ├── package.json 8 ├── packages 9 │ └── happynrwl 10 │ ├── src 11 │ │ ├── executors 12 │ │ ├── generators 13 │ │ │ ├── happynrwl 14 │ │ │ └── preset // <------------- Here 15 │ │ └── index.ts 16 ├── tools 17 └── tsconfig.base.json 18

After the command is finished, the preset generator is created under the folder named preset. The generator.ts provides an entry point to the generator. This file contains a function that is called to perform manipulations on a tree that represents the file system. The schema.json provides a description of the generator, available options, validation information, and default values.

Here is the sample generator function which you can customize to meet your needs.

1export default async function (tree: Tree, options: PresetGeneratorSchema) { 2 const normalizedOptions = normalizeOptions(tree, options); 3 addProjectConfiguration(tree, normalizedOptions.projectName, { 4 root: normalizedOptions.projectRoot, 5 projectType: 'application', 6 sourceRoot: `${normalizedOptions.projectRoot}/src`, 7 targets: { 8 exec: { 9 executor: 'nx:run-commands', 10 options: { 11 command: `node ${projectRoot}/src/index.js`, 12 }, 13 }, 14 }, 15 tags: normalizedOptions.parsedTags, 16 }); 17 addFiles(tree, normalizedOptions); 18 await formatFiles(tree); 19} 20

To get an in-depth guide on customizing/running or debugging your generator see local generators.

Usage

Before you are able to use your newly created preset you must package and publish it to a registry.

After you have published your plugin to a registry you can now use your preset when creating a new workspace

npx create-nx-workspace my-workspace --preset=my-plugin-name