Nx Generator Generator

Adds an Nx Generator to a TypeScript project, to help you automate repetitive tasks such as scaffolding components or enforcing particular project structures.

Usage

Generate a Generator

You can generate a generator in two ways:

Run this generator@aws/nx-plugin:ts#nx-generator

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#nx-generator

yarn

$ yarn nx g @aws/nx-plugin:ts#nx-generator

npm

$ npx nx g @aws/nx-plugin:ts#nx-generator

bun

$ bunx nx g @aws/nx-plugin:ts#nx-generator

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - ts#nx-generator
5. Fill in the required parameters
6. Click Generate

Build your command5

projectRequired

nameRequired

description

directory

preferInstallDependencies

true

--dry-runYou can also perform a dry-run to see what files would be changed

Recommended Setup

We recommend using the ts#nx-plugin generator as the base project for any generators you create, since it also provides an MCP Server which helps AI to use your generators.

Options

Generator Options5 options

projectRequiredstring

TypeScript project to add the generator to. We recommend using the ts#nx-plugin generator to create this.

nameRequiredstring

Generator name

descriptionstring

A description of your generator

directorystring

The directory within the plugin project's source folder to add the generator to (default: <name>)

preferInstallDependenciesbooleanDefault: true

Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

The generator will create the following project files within the given project:

• Directorysrc/<name>/

  • schema.json Schema for input to your generator
  • schema.d.ts TypeScript types for your schema
  • generator.ts Stub generator implementation
  • generator.spec.ts Tests for your generator
  • README.md Documentation for your generator
  • Directoryfiles/

    • hello.ts.template Example template rendered by the stub generator
• src/index.ts Updated to export your generator
• generators.json Created or updated to define your generators
• project.json Updated to record the generator against the project
• package.json Created if absent, and pointed at generators.json

Local Generators

Dedicated Plugin Project

We recommend generating a dedicated TypeScript project for all your generators using the ts#nx-plugin generator first. For example:

Run this generator@aws/nx-plugin:ts#nx-plugin

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#nx-plugin

yarn

$ yarn nx g @aws/nx-plugin:ts#nx-plugin

npm

$ npx nx g @aws/nx-plugin:ts#nx-plugin

bun

$ bunx nx g @aws/nx-plugin:ts#nx-plugin

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - ts#nx-plugin
5. Fill in the required parameters
6. Click Generate

Build your command4

nameRequired

directory

subDirectory

preferInstallDependencies

true

--dry-runYou can also perform a dry-run to see what files would be changed

Select your local nx-plugin project when running the ts#nx-generator generator, and specify a name and optional directory and description.

Defining the Schema

The schema.json file defines the options that your generator accepts. It follows the JSON Schema format with Nx-specific extensions.

Basic Structure

A schema.json file has the following basic structure:

{
  "$schema": "https://json-schema.org/schema",
  "$id": "YourGeneratorName",
  "title": "Your Generator Title",
  "description": "Description of what your generator does",
  "type": "object",
  "properties": {
    // Your generator options go here
  },
  "required": ["requiredOption1", "requiredOption2"]
}

Simple Example

Here’s a simple example with a few basic options:

{
  "$schema": "https://json-schema.org/schema",
  "$id": "ComponentGenerator",
  "title": "Create a Component",
  "description": "Creates a new React component",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Component name",
      "x-priority": "important"
    },
    "directory": {
      "type": "string",
      "description": "Directory where the component will be created",
      "default": "src/components"
    },
    "withTests": {
      "type": "boolean",
      "description": "Whether to generate test files",
      "default": true
    }
  },
  "required": ["name"]
}

Interactive Prompts (CLI)

You can customise the prompts displayed when running your generator via the CLI by adding the x-prompt property:

"name": {
  "type": "string",
  "description": "Component name",
  "x-prompt": "What is the name of your component?"
}

For boolean options, you can use a yes/no prompt:

"withTests": {
  "type": "boolean",
  "description": "Whether to generate test files",
  "x-prompt": "Would you like to generate test files?"
}

Dropdown Selections

For options with a fixed set of choices, use enum so that users can select from one of the options.

"style": {
  "type": "string",
  "description": "The styling approach to use",
  "enum": ["css", "scss", "styled-components", "none"],
  "default": "css"
}

Project Selection Dropdown

A common pattern is to let users select from existing projects in the workspace:

"project": {
  "type": "string",
  "description": "The project to add the component to",
  "x-prompt": "Which project would you like to add the component to?",
  "x-dropdown": "projects"
}

The x-dropdown: "projects" property tells Nx to populate the dropdown with all projects in the workspace.

Positional Arguments

You can configure options to be passed as positional arguments when running the generator from the command line:

"name": {
  "type": "string",
  "description": "Component name",
  "x-priority": "important",
  "$default": {
    "$source": "argv",
    "index": 0
  }
}

This allows users to run your generator like nx g your-generator my-component instead of nx g your-generator --name=my-component.

Setting Priorities

Use the x-priority property to indicate which options are most important:

"name": {
  "type": "string",
  "description": "Component name",
  "x-priority": "important"
}

Options can have priorities of "important" or "internal". This helps Nx to order properties in the Nx VSCode extension and Nx CLI.

Default Values

You can provide default values for options:

"directory": {
  "type": "string",
  "description": "Directory where the component will be created",
  "default": "src/components"
}

More Information

For more details on schemas, refer to the Nx Generator Options documentation.

TypeScript Types with schema.d.ts

Along with schema.json, the generator creates a schema.d.ts file that provides TypeScript types for your generator options:

export interface YourGeneratorSchema {
  name: string;
  directory?: string;
  withTests?: boolean;
}

This interface is used in your generator implementation to provide type safety and code completion:

import { YourGeneratorSchema } from './schema';

export default async function (tree: Tree, options: YourGeneratorSchema) {
  // TypeScript knows the types of all your options
  const { name, directory = 'src/components', withTests = true } = options;
  // ...
}

Schema Changes

Whenever you modify schema.json, you must update schema.d.ts to match. This includes:

• Adding or removing properties
• Changing property types
• Making properties required or optional (use the ? suffix for optional properties)

The TypeScript interface should accurately reflect the structure defined in your JSON schema.

Implementing a Generator

After creating the new generator as above, you can write your implementation in generator.ts.

A generator is a function which mutates a virtual filesystem (the Tree), reading and writing files to make the desired changes. Changes from the Tree are only written to disk once the generator finishes executing, unless it is run in “dry-run” mode. An empty generator looks as follows:

export const myGenerator = async (tree: Tree, options: MyGeneratorSchema) => {
  // Use the tree to apply changes
};

export default myGenerator;

Here are some common operations you might want to perform in your generator:

Reading and Writing Files

// Read a file
const content = tree.read('path/to/file.ts', 'utf-8');

// Write a file
tree.write('path/to/new-file.ts', 'export const hello = "world";');

// Check if a file exists
if (tree.exists('path/to/file.ts')) {
  // Do something
}

Generating Files from Templates

You can generate files with the generateFiles utility from @nx/devkit. This allows you to define templates in EJS syntax, and substitute variables.

import { generateFiles, joinPathFragments } from '@nx/devkit';

// Generate files from templates
generateFiles(
  tree,
  joinPathFragments(import.meta.dirname, 'files'), // Template directory
  'path/to/output', // Output directory
  {
    // Variables to replace in templates
    name: options.name,
    nameCamelCase: camelCase(options.name),
    nameKebabCase: kebabCase(options.name),
    // Add more variables as needed
  },
);

Code Transforms with GritQL

You can use GritQL to declaratively search and transform source code in your generators. GritQL supports multiple languages including TypeScript, JavaScript, Python, HCL (Terraform), and more — so you can use the same pattern syntax across your entire stack.

The Nx Plugin for AWS exposes two helpers:

• applyGritQL(tree, filePath, pattern) — applies a GritQL rewrite pattern to a file and returns Promise<boolean> indicating whether changes were made
• matchGritQL(tree, filePath, pattern) — checks whether a GritQL pattern matches anywhere in a file and returns Promise<boolean>

import { applyGritQL, matchGritQL } from '@aws/nx-plugin/sdk/utils/ast';

// Replace a function call
await applyGritQL(
  tree,
  'src/app.ts',
  '`console.log($msg)` => `logger.info($msg)`',
);

// Add an element to an array only if not already present
await applyGritQL(
  tree,
  'src/plugins.ts',
  '`plugins: [$items]` => `plugins: [$items, myPlugin()]` where { $items <: not contains `myPlugin` }',
);

// Check if a pattern exists before making changes
if (!(await matchGritQL(tree, filePath, '`import { Auth } from "./auth"`'))) {
  // Add the import
}

GritQL patterns also work on non-TypeScript files. Prefix your pattern with language <name> to target other languages:

// Python: replace print statements with logging calls
await applyGritQL(
  tree,
  'src/handler.py',
  'language python\n`print($msg)` => `logger.info($msg)`',
);

GritQL patterns use backtick-delimited code snippets with $metavariables as wildcards. Use => for rewrites and where clauses for conditions.

GritQL Playground

You can try out GritQL patterns in the GritQL Playground, or install the GritQL CLI locally to test patterns against your files:

npm install -g @getgrit/cli
grit apply '`console.log($msg)` => `logger.info($msg)`' --dry-run

AI Coding Agents

If you use an AI coding agent to help write generators, add the Context7 MCP server to give it up-to-date documentation. Prompt it to look up gritql and docs.grit.io for GritQL pattern syntax reference, and provide access to the GritQL CLI so it can test patterns directly.

Adding Dependencies

import { addDependenciesToPackageJson } from '@nx/devkit';

// Add dependencies to package.json
addDependenciesToPackageJson(
  tree,
  {
    'new-dependency': '^1.0.0',
  },
  {
    'new-dev-dependency': '^2.0.0',
  },
);

Package Dependencies

If you add dependencies to a package.json, you can then install them for the user as part of the generator callback:

import { installPackagesTask } from '@nx/devkit';

// Generators return a callback which can run any post-generation tasks, such as installing dependencies
return () => {
  installPackagesTask(tree);
};

Formatting Generated Files

import { formatFilesInSubtree } from '@aws/nx-plugin/sdk/utils/format';

// Format all files that were modified
await formatFilesInSubtree(tree, 'optional/path/to/format');

Note

formatFilesInSubtree formats TypeScript, JavaScript, JSON and CSS files with Biome, and Python files with Ruff. When the workspace already has a biome.json on disk, it uses your workspace’s installed version of Biome and its configuration. Otherwise it falls back to a bundled Biome, applying any biome.json present in the virtual tree.

Reading and Updating JSON Files

import { readJson, updateJson } from '@nx/devkit';

// Read a JSON file
const packageJson = readJson(tree, 'package.json');

// Update a JSON file
updateJson(tree, 'tsconfig.json', (json) => {
  json.compilerOptions = {
    ...json.compilerOptions,
    strict: true,
  };
  return json;
});

Extending a Generator from the Nx Plugin for AWS

You can import generators from the Nx Plugin for AWS, and extend or compose them as you wish, for example you might wish to create a generator which builds on top of a TypeScript project:

import { tsProjectGenerator } from '@aws/nx-plugin/sdk/ts';

export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
  const callback = await tsProjectGenerator(tree, { ... });

  // Extend the TypeScript project generator here

  // Return the callback to ensure dependencies are installed.
  // You can wrap the callback if you wish to perform additional operations in the generator callback.
  return callback;
};

OpenAPI Generators

You can use and extend the generators we use for TypeScript clients and hooks in a similar way to the above:

import { openApiTsClientGenerator } from '@aws/nx-plugin/sdk/open-api';

export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
  await openApiTsClientGenerator(tree, { ... });

  // Add additional files here
};

We also expose a method which allows you to build a data structure that can be used to iterate over operations in an OpenAPI specification and therefore instrument your own code generation, for example:

import { buildOpenApiCodeGenerationData } from '@aws/nx-plugin/sdk/open-api';

export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
  const data = await buildOpenApiCodeGenerationData(tree, 'path/to/spec.json');

  generateFiles(
    tree,
    joinPathFragments(import.meta.dirname, 'files'), // Template directory
    'path/to/output', // Output directory
    data,
  );
};

Which then allows you to write templates such as:

files/my-operations.ts.template

export const myOperationNames = [
<%_ allOperations.forEach((op) => { _%>
  '<%- op.name %>',
<%_ }); _%>
];

Refer to the codebase on GitHub for more complex example templates.

Running Your Generator

You can run your generator in two ways:

Run this generator@my-project/nx-plugin:my-generator

CLI

pnpm

$ pnpm nx g @my-project/nx-plugin:my-generator

yarn

$ yarn nx g @my-project/nx-plugin:my-generator

npm

$ npx nx g @my-project/nx-plugin:my-generator

bun

$ bunx nx g @my-project/nx-plugin:my-generator

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @my-project/nx-plugin - my-generator
5. Fill in the required parameters
6. Click Generate

Generator Not Showing

If you don’t see your generator in the VSCode plugin UI, you can refresh your Nx Workspace with:

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

Testing Your Generator

Unit tests for generators are straightforward to implement. Here’s a typical pattern:

import { createTreeUsingTsSolutionSetup } from '@aws/nx-plugin/sdk/utils/test';
import { yourGenerator } from './generator.js';

describe('your generator', () => {
  let tree;

  beforeEach(() => {
    // Create a workspace tree matching the shape our preset generates
    tree = createTreeUsingTsSolutionSetup();

    // Add any files that should already exist in the tree
    tree.write(
      'project.json',
      JSON.stringify({
        name: 'test-project',
        sourceRoot: 'src',
      }),
    );

    tree.write('src/existing-file.ts', 'export const existing = true;');
  });

  it('should generate expected files', async () => {
    // Run the generator
    await yourGenerator(tree, {
      name: 'test',
      // Add other required options
    });

    // Check that files were created
    expect(tree.exists('src/test/file.ts')).toBeTruthy();

    // Check file content
    const content = tree.read('src/test/file.ts', 'utf-8');
    expect(content).toContain('export const test');

    // You can also use snapshots
    expect(tree.read('src/test/file.ts', 'utf-8')).toMatchSnapshot();
  });

  it('should update existing files', async () => {
    // Run the generator
    await yourGenerator(tree, {
      name: 'test',
      // Add other required options
    });

    // Check that existing files were updated
    const content = tree.read('src/existing-file.ts', 'utf-8');
    expect(content).toContain('import { test } from');
  });

  it('should handle errors', async () => {
    // Expect the generator to throw an error in certain conditions
    await expect(
      yourGenerator(tree, {
        name: 'invalid',
        // Add options that should cause an error
      }),
    ).rejects.toThrow('Expected error message');
  });
});

Key points for testing generators:

• Use createTreeUsingTsSolutionSetup() from @aws/nx-plugin/sdk/utils/test to create a virtual file system. It seeds the workspace markers our preset writes (tsconfig.base.json, pnpm-workspace.yaml, biome.json, a type: module root package.json), which any generator composing an @aws/nx-plugin generator needs
• Set up any prerequisite files before running the generator
• Test both the creation of new files and updates to existing files
• Use snapshots for complex file content
• Test error conditions to ensure your generator fails gracefully

Contributing Generators to @aws/nx-plugin

You can also use ts#nx-generator to scaffold a generator within @aws/nx-plugin.

When this generator is run in our repository, it’ll generate the following files for you:

• Directorypackages/nx-plugin/src/<name>/

  • schema.json Schema for input to your generator
  • schema.d.ts TypeScript types for your schema
  • generator.ts Generator implementation
  • generator.spec.ts Tests for your generator
• Directorydocs/src/content/docs/guides/

  • <name>.mdx Documentation page for your generator
• packages/nx-plugin/generators.json Updated to include your generator
• packages/nx-plugin/sdk/<prefix>.ts Updated to expose your generator from the SDK (for ts# and py# generators)

You can then start to implement your generator.

Contributing Generators

For a more in-depth guide regarding contributing to the Nx Plugin for AWS, please refer to the tutorial here.