Nx plugin authoring

Nx Plugin Authoring

Navigation hub for creating custom Nx plugins, generators, and executors.

When to Use

• You need to scaffold files/projects with repeatable conventions (generators).
• You need custom task execution logic (executors).
• You are building reusable plugin automation for Nx workspaces.
• You want to enforce organization-specific standards and patterns.

When Not to Use

• The task is generic Nx workspace setup unrelated to custom plugin development.
• You only need to use existing plugins, not create new ones.

Principles

• Keep plugins as orchestration tools, not business-logic containers.
• Prefer small, composable generation steps over large mutation passes.
• Keep executors deterministic and cache-aware.
• Use Tree API exclusively for filesystem operations in generators.

Workflow

1. Create Plugin Structure

Start new workspace with plugin:

npx create-nx-plugin my-plugin

Add plugin to existing workspace:

npx nx add @nx/plugin
npx nx g plugin tools/my-plugin

2. Build Generators

Create a generator:

npx nx g generator my-plugin/src/generators/library-with-readme

Implement with Tree API:

• Use tree.write, generateFiles, updateJson for filesystem edits
• Define typed schema with required fields
• Add templates with EJS syntax
• Validate with --dry-run before execution

Validate: Run npx nx g my-plugin:library-with-readme mylib --dry-run

Stop if: Unexpected files appear or required options fail validation

3. Build Executors

Create executor structure:

mkdir -p tools/executors/my-executor

Implement with ExecutorContext:

• Define schema.json with required fields and defaults
• Return { success: boolean } from executor
• Use package notation for registration
• Declare outputs for cache awareness

Validate: Run npx nx run my-project:my-target --help

Stop if: Executor fails to resolve or schema is invalid

4. Test and Publish

Run tests:

npx nx test my-plugin

Validate in real workspace:

npx nx g my-plugin:my-generator sample --dry-run
npx nx run my-project:my-target

Quick Commands

npx create-nx-plugin my-plugin

npx nx add @nx/plugin

npx nx g generator my-plugin/src/generators/my-gen

npx nx g my-plugin:my-gen sample --dry-run

npx nx run my-project:my-target --skip-nx-cache

npx nx reset

rg -n "generateFiles|updateJson|readProjectConfiguration" plugins tools

Anti-Patterns

NEVER modify files outside the Tree API

• WHY: direct filesystem writes bypass dry-run and change tracking.
• BAD: writeFileSync("libs/my-lib/src/index.ts", content).
• GOOD: tree.write("libs/my-lib/src/index.ts", content).

NEVER hardcode project paths in generator logic

• WHY: brittle paths fail when workspace layout evolves.
• BAD: fixed libs/my-lib/... writes.
• GOOD: derive paths from readProjectConfiguration(tree, name).root.

NEVER skip schema validation and typed options

• WHY: invalid inputs fail late with unclear errors.
• BAD: schema: any and no guardrails.
• GOOD: typed schema.json with required fields, types, defaults, descriptions.

NEVER generate across project boundaries without explicit checks

• WHY: hidden boundary violations introduce circular dependencies.
• BAD: generator writes imports into disallowed scopes without verification.
• GOOD: verify tags and dependency direction before cross-scope imports.

NEVER mutate project configuration blindly

• WHY: naive updates remove existing targets/tags.
• BAD: overwrite full project.json.
• GOOD: const config = readProjectConfiguration(tree, name); config.targets.build = {...}; updateProjectConfiguration(tree, name, config);.

NEVER put business logic directly inside executor entrypoints

• WHY: bloated executors are hard to test and reuse.
• BAD: 200 lines of transformation logic in executor.ts.
• GOOD: delegate to composable library functions.

NEVER use relative executor references in targets

• WHY: relative paths are fragile across workspace changes.
• BAD: "executor": "../../tools/executors:task".
• GOOD: "executor": "@scope/tools:task".

NEVER omit outputs and dependencies semantics for cacheable work

• WHY: Nx cache quality depends on deterministic inputs and outputs.
• BAD: no outputs declared, implicit file writes.
• GOOD: declare outputs in target config: "outputs": ["{options.outputPath}"].

NEVER block executor runs with synchronous file I/O in hot paths

• WHY: sync I/O hurts parallel throughput.
• BAD: fs.readFileSync in main execution flow.
• GOOD: await fs.promises.readFile with structured error handling.

NEVER skip formatFiles after generating code

• WHY: inconsistent formatting causes noisy diffs and CI failures.
• BAD: generateFiles() without calling formatFiles(tree).
• GOOD: await generateFiles(...); await formatFiles(tree);.

NEVER ignore existing project structure when generating files

• WHY: overwriting existing files destroys user work.
• BAD: tree.write(path, content) without checking tree.exists(path).
• GOOD: if (tree.exists(path)) { throw new Error('File already exists'); }.

NEVER forget to export generator/executor from plugin index

• WHY: unregistered functions cannot be invoked by Nx CLI.
• BAD: generator implemented but missing from src/index.ts and generators.json.
• GOOD: export in src/index.ts and register in generators.json with factory path.

Constraint vs Flexibility Guidelines

Hard Constraints (MUST)

Generators:

• MUST use Tree API for filesystem edits
• MUST validate generator options via schema and explicit guards
• MUST respect Nx project graph boundaries and existing tags
• MUST test with --dry-run before broad rollouts

Executors:

• MUST return { success: boolean } from executor function
• MUST use package notation for executor references in targets
• MUST declare outputs for cacheable tasks
• MUST implement schema validation with required fields

Flexible Choices (CAN)

• CAN choose template style (EJS-heavy vs minimal placeholders)
• CAN choose option naming conventions if documented in schema
• CAN compose other generators to reduce duplication
• CAN delegate executor work to external libraries

Fallback Behaviors

Missing Input	Fallback
directory omitted in generator	Use workspace default location
optional flags omitted	Apply safe schema defaults
custom template not provided	Generate minimal boilerplate
executor outputs not declared	No cache, always re-run

References

Getting Started

Topic	Reference
Plugin scaffolding and structure	references/plugin-scaffolding.md
Core concepts	knowledge-base/concepts.md

Generators

Topic	Reference
Generator implementation guide	references/generators-guide.md
Tree API patterns	references/tree-api-reference.md
Template engine guidance	references/template-engine-guide.md
Template system details	knowledge-base/template-system.md

Executors

Topic	Reference
Executor implementation guide	references/executors-guide.md
ExecutorContext API usage	references/executor-context-api.md
Executor schema design	references/executor-schema-design.md

Shared Resources

Topic	Reference
Schema design patterns	references/schema-design-patterns.md
Utility helpers	knowledge-base/utilities.md
Testing and troubleshooting	references/testing-and-troubleshooting.md

• Nx Plugin Development
• Nx Devkit API
• Enforce Best Practices Tutorial
• Tool Integration Tutorial
• Local Executors Recipe
• Plugin Registry