TypeScript Nx Plugin

Generate a complete TypeScript Nx Plugin with an integrated Model Context Protocol (MCP) server. This generator creates a foundation for building custom generators that can be seamlessly used by AI assistants for automated code generation and project scaffolding.

Usage

Generate an Nx Plugin

You can generate a TypeScript Nx Plugin in two ways:

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

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

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-plugin --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#nx-plugin --dry-run

npm

npx nx g @aws/nx-plugin:ts#nx-plugin --dry-run

bun

bunx nx g @aws/nx-plugin:ts#nx-plugin --dry-run

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

Options

Parameter	Type	Default	Description
name Required	string	-	TypeScript project name
directory	string	packages	Parent directory where the library is placed.
subDirectory	string	-	The sub directory the lib is placed in. By default this is the library name.
preferInstallDependencies	boolean	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 structure:

• Directoryyour-plugin/

  • Directorysrc/

    • index.ts Empty entry point for your plugin
    • Directorymcp-server/

      • index.ts Exports your server
      • server.ts Main MCP server configuration
      • stdio.ts Entry point for your MCP server with STDIO transport
      • http.ts Entry point for your MCP server with Streamable HTTP transport
      • Directorytools/

        • create-workspace-command.ts Tool for workspace creation guidance
        • general-guidance.ts Tool for general Nx and plugin guidance
        • list-generators.ts Tool to list available generators
        • generator-guide.ts Tool for detailed generator information
      • utils.ts Utility functions for the MCP server
  • generators.json Nx generator configuration (initially empty)
  • package.json Plugin package configuration
  • tsconfig.json TypeScript configuration (CommonJS for Nx compatibility)
  • project.json Nx project configuration with build and package targets

Working with Your Nx Plugin

Adding Generators

Once you have your plugin project, you can add generators using the ts#nx-generator generator:

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin

yarn

yarn nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin

npm

npx nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin

bun

bunx nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin

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

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin --dry-run

npm

npx nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin --dry-run

bun

bunx nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin --dry-run

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
   • project: your-plugin
6. Click Generate

This will add a new generator to your plugin.

Generator Documentation

Read the ts#nx-generator guide for details about how to implement generators.

Make sure to write a detailed README.md for your generator, since this is used by the MCP Server’s generator-guide tool.

Project Targets

The generated plugin includes several important targets:

Build Target

Compiles your TypeScript code and prepares the plugin for use:

pnpm

pnpm nx build your-plugin

yarn

yarn nx build your-plugin

npm

npx nx build your-plugin

bun

bunx nx build your-plugin

Package Target

Creates a distributable package ready for NPM publishing:

pnpm

pnpm nx package your-plugin

yarn

yarn nx package your-plugin

npm

npx nx package your-plugin

bun

bunx nx package your-plugin

The package target includes all necessary assets:

• Compiled JavaScript files
• TypeScript declaration files
• Generator and executor configuration files
• Documentation and license files

MCP Server Integration

The plugin configures an MCP server using the ts#mcp-server generator.

Tools

The plugin includes a complete MCP server that provides AI assistants the following tools:

• general-guidance: Get best practices for working with Nx and your plugin
• create-workspace-command: Learn how to create new workspaces that can use your plugin
• list-generators: List all available generators in your plugin
• generator-guide: Get detailed information about specific generators including schemas and usage

Configuring with AI Assistants

Configuration Files

Most AI assistants that support MCP use a similar configuration approach. You’ll need to create or update a configuration file with your MCP server details:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "/path/to/your-mcp-server/stdio.ts"]
    }
  }
}

Path Resolution

If you receive an error such as ENOENT npx when connecting to your server, you might need to specify the full path to npx, which you can obtain by running which npx in your terminal.

Hot Reload

While developing your MCP server, you may wish to configure the --watch flag so that the AI assistant always sees the latest versions of tools/resources:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "--watch", "/path/to/your-mcp-server/stdio.ts"]
    }
  }
}

Refreshing Tools

If you add new tools or resources you may need to refresh your MCP server in the AI assistant.

Assistant-Specific Configuration

Please refer to the following documentation for configuring MCP with specific AI Assistants:

• Kiro
• Kiro CLI
• Claude Code
• Cursor
• Codex
• Cline
• Roo Code

Workspace Configuration

Some AI Assistants, such as Kiro, allow you to specify workspace level MCP server configuration, which is particularly useful for defining the relevant MCP servers for a particular project.

Customizing the MCP Server

You can extend the MCP server by modifying server.ts to add additional tools or resources specific to your plugin’s domain.

For more details about writing MCP Servers, refer to the ts#mcp-server guide.

Publishing Your Plugin

Preparing for Publication

1. Update Package Information: Edit your plugin’s package.json with proper name, version, description, and repository information.

2. Build the Package:

   pnpm

   pnpm nx package your-plugin

   yarn

   yarn nx package your-plugin

   npm

   npx nx package your-plugin

   bun

   bunx nx package your-plugin

3. Test Locally: You can test your plugin locally by installing it in another workspace:

   npm install /path/to/your/workspace/dist/your-plugin/package

Publishing to NPM

Once your plugin is ready:

cd dist/your-plugin/package
npm publish

Using Published Plugins

After publishing, others can install and use your plugin:

pnpm

pnpm add -w your-plugin-name

yarn

yarn add your-plugin-name

npm

npm install --legacy-peer-deps your-plugin-name

bun

bun add your-plugin-name

Then use your generators:

CLI

pnpm

pnpm nx g your-plugin-name:your-generator-name

yarn

yarn nx g your-plugin-name:your-generator-name

npm

npx nx g your-plugin-name:your-generator-name

bun

bunx nx g your-plugin-name:your-generator-name

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

pnpm

pnpm nx g your-plugin-name:your-generator-name --dry-run

yarn

yarn nx g your-plugin-name:your-generator-name --dry-run

npm

npx nx g your-plugin-name:your-generator-name --dry-run

bun

bunx nx g your-plugin-name:your-generator-name --dry-run

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 your-plugin-name - your-generator-name
5. Fill in the required parameters
6. Click Generate

Configure AI Assistants with your Published Plugin

Your published plugin’s MCP server can be configured as follows:

{
  "mcpServers": {
    "aws-nx-mcp": {
      "command": "npx",
      "args": ["-y", "-p", "your-plugin-name", "your-plugin-name-mcp-server"]
    }
  }
}