Extending Nx with Plugins
Nx's core functionality focuses on task running and understanding your project and task graph. Nx plugins leverage that functionality to enforce best practices, seamlessly integrate tooling and allow developers to get up and running quickly.
As your repository grows, you'll discover more reasons to create your own plugin
- You can help encourage your coworkers to consistently follow best practices by creating code generators that are custom built for your repository.
- You can remove duplicate configuration and ensure accurate caching settings by writing your own inferred tasks.
- For organizations with multiple monorepos, you can encourage consistency across repositories by providing a repository preset and writing migrations that will help keep every project in sync.
- You can write a plugin that integrates a tool or framework into Nx and then share your plugin with the broader community.
Create Your Own Plugin
Get started developing your own plugin with a few terminal commands:
❯
npx create-nx-plugin my-plugin
❯
npx nx add @nx/plugin
❯
npx nx g plugin tools/my-plugin
Learn by Doing
You can follow along with one of the step by step tutorials below that is focused on a particular use-case. These tutorials expect you to already have the following skills:
- Run tasks with Nx and configure Nx to infers tasks for you
- Use code generators
- Understand the project graph
- Write TypeScript code
Create Your First Code Generator
Wire up a new generator with this terminal command:
❯
npx nx g generator my-plugin/src/generators/library-with-readme
Understand the Generator Functionality
This command will register the generator in the plugin's generators.json
file and create some default generator code in the library-with-readme
folder. The libraryWithReadmeGenerator
function in the generator.ts
file is where the generator functionality is defined.
1export async function libraryWithReadmeGenerator(
2 tree: Tree,
3 options: LibraryWithReadmeGeneratorSchema
4) {
5 const projectRoot = `libs/${options.name}`;
6 addProjectConfiguration(tree, options.name, {
7 root: projectRoot,
8 projectType: 'library',
9 sourceRoot: `${projectRoot}/src`,
10 targets: {},
11 });
12 generateFiles(tree, path.join(__dirname, 'files'), projectRoot, options);
13 await formatFiles(tree);
14}
15
This generator calls the following functions:
addProjectConfiguration
- Create a new project configured for TypeScript code.generateFiles
- Create files in the new project based on the template files in thefiles
folder.formatFiles
- Format the newly created files with Prettier.
You can find more helper functions in the Nx Devkit reference documentation.
Create a README Template File
We can remove the generated index.ts.template
file and add our own README.md.template
file in the files
folder.
1# <%= name %>
2
3This was generated by the `library-with-readme` generator!
4
The template files that are used in the generateFiles
function can inject variables and functionality using the EJS syntax. Our README template will replace <%= name %>
with the name specified in the generator. Read more about the EJS syntax in the creating files with a generator recipe.
Run Your Generator
You can test your generator in dry-run mode with the following command:
❯
npx nx g my-plugin:library-with-readme mylib --dry-run
If you're happy with the files that are generated, you can actually run the generator by removing the --dry-run
flag.
Next Steps
- Browse the plugin registry to find one that suits your needs.
- Sign up for Nx Enterprise to get dedicated support from Nx team members.
- Collaborate on the Nx Discord to work with other plugin authors.