nx-plugin-for-aws

name	nx-plugin-for-aws
description	Scaffold and build cloud-native applications on AWS using @aws/nx-plugin generators. Use when the user wants to create workspaces, generate projects, or scaffold infrastructure with the Nx Plugin for AWS.

Nx Plugin for AWS

Overview

The Nx Plugin for AWS (@aws/nx-plugin) is a collection of generators that help you rapidly scaffold and build cloud-native applications on AWS. It provides end-to-end code generation from application code to CDK/Terraform infrastructure, all following AWS best practices.

This power gives AI assistants guided access to the MCP server so they can help you create workspaces, discover generators, and scaffold projects interactively.

Key capabilities:

• Create new Nx workspaces configured for AWS development
• Scaffold TypeScript and Python projects, APIs, websites, and infrastructure
• Generate Lambda functions, MCP servers, Strands Agents, and more
• Connect projects together (e.g. frontend to backend)
• Manage licenses across your workspace

Onboarding

Prerequisites

Required

• Git
• Node >= 22 (We recommend using something like NVM to manage your node versions)
  • verify by running node --version
• UV >= 0.5.29
  1. install Python 3.14 by running: uv python install 3.14.0
  2. verify with uv python list --only-installed

Recommended

• PNPM >= 11 (you can also use Yarn >= 4, Bun >= 1, or NPM >= 10 if you prefer)
  • verify by running pnpm --version, yarn --version, bun --version or npm --version
• AWS Credentials configured to your target AWS account are required to deploy your application (as well as for some local development workflows).
• Docker or Finch >= 1.6.0 is required for some generators. For Docker, multi-platform builds must be set up; Finch supports multi-platform builds out of the box.
• Terraform >= 1.12 is required if you choose to use this for infrastructure as code instead of CDK
  • verify by running terraform --version
• If you are using VSCode, we recommend installing the Nx Console VSCode Plugin.

Getting Started

1. Choose a package manager (pnpm is recommended)
2. Choose an IaC provider (CDK is recommended)
3. Create a new workspace using the create_workspace_command tool
4. Start scaffolding with generators using list_generators and generator_guide

Quick Start Example

To create a new workspace and scaffold a React website with a tRPC API:

# Create workspace (pass `.` as the name to create in the current empty directory)
pnpm create @aws/nx-workspace my-app --no-interactive

# Generate a tRPC API
pnpm nx g @aws/nx-plugin:ts#trpc-api --no-interactive --name=my-api

# Generate a React website
pnpm nx g @aws/nx-plugin:ts#react-website --no-interactive --name=my-website

# Connect the website to the API
pnpm nx g @aws/nx-plugin:connection --no-interactive --sourceProject=my-website --targetProject=my-api

# Generate CDK infrastructure
pnpm nx g @aws/nx-plugin:ts#infra --no-interactive --name=infra

Always prompt the user for what name they want to use when executing generators if a --name is a required argument. DO NOT ASSUME THE NAME.

Common Workflows

Workflow 1: Create a New Workspace

Use the create_workspace_command tool with your preferred package manager. This generates the full command to create an Nx workspace pre-configured with the AWS plugin.

pnpm create @aws/nx-workspace my-app --no-interactive

If you are already inside an empty directory intended for this project, pass . as the workspace name to create the workspace in the current directory:

pnpm create @aws/nx-workspace . --no-interactive

Be sure to ask the user what their preferred project name is, unless already within an empty directory intended for the project.

Workflow 2: Discover Available Generators

Use the list_generators tool to see all available generators and their parameters. This returns the full list with descriptions and example commands.

Workflow 3: Get Detailed Generator Guidance

Use the generator_guide tool with a specific generator name to get in-depth documentation including:

• All parameters (required and optional)
• Generated file structure
• Post-generation steps
• Best practices and tips

Workflow 4: Scaffold a Full-Stack Application

A typical full-stack app involves:

1. Create workspace
2. Generate a backend API (ts#trpc-api, ts#smithy-api, or py#fast-api)
3. Generate a React frontend (ts#react-website)
4. Connect frontend to backend (connection)
5. Generate CDK infrastructure (ts#infra)
6. Optionally add auth (ts#react-website#auth)

Workflow 5: Add Components to Existing Projects

Add capabilities to existing projects:

• ts#lambda-function / py#lambda-function — Add Lambda functions
• ts#mcp-server / py#mcp-server — Add MCP servers
• ts#agent / py#agent — Add AI agents
• ts#nx-generator — Add custom Nx generators

Available Generators

Generator	Description
init	Configure an existing Nx workspace to use the @aws/nx-plugin
agentcore-gateway	Generate an AgentCore Gateway project
agentcore-harness	Generate an AgentCore Harness project (experimental)
connection	Integrates a source project with a target project
license	Add LICENSE files and configure source code licence headers
py#api	Create a Python API
py#lambda-function	Adds a lambda function to a python project
py#mcp-server	Generate a Python Model Context Protocol (MCP) server for providing context to Large Language Models
py#project	Generates a Python project
py#agent	Add an AI Agent to a Python project
smithy#project	Generate a Smithy model project, either defining a service or a library of reusable shapes
terraform#project	Generates a Terraform project
ts#docs	Generates a documentation site
ts#infra	Generates a cdk application
ts#lambda-function	Generate a TypeScript lambda function
ts#dcr-proxy	Generate an OAuth Dynamic Client Registration (DCR) proxy construct for Cognito-authenticated MCP servers
ts#mcp-server	Generate a TypeScript Model Context Protocol (MCP) server for providing context to Large Language Models
ts#nx-generator	Generator for adding an Nx Generator to an existing TypeScript project
ts#nx-migration	Generator for adding an Nx Migration to an Nx Plugin, applied by nx migrate when users upgrade
ts#nx-plugin

Best Practices

• Always use --no-interactive flag when running generators programmatically
• Use fully qualified project names (e.g. @my-scope/my-project) when referencing projects
• Run nx sync after adding dependencies between TypeScript projects
• Install dependencies at the workspace root, not in individual projects
• Use nx reset to reset the Nx daemon when unexpected issues arise
• When running several generators in sequence, pass --prefer-install-dependencies=false on each to avoid a slow install after every generator, then install once at the end (or let the final generator install by omitting the flag)
• After running generators, use nx show projects to verify what was created
• Fix lint issues with nx run-many --target lint --configuration=fix --all
• Generate all projects into the packages/ directory
• Prefer pnpm as the package manager and CDK as the IaC provider

One-Shot Scaffolding

When the user wants a full workspace created in one go, you can chain generators to minimize tool calls:

• Workspace creation pass --no-interactive to avoid interactive prompts

  pnpm create @aws/nx-workspace my-app --iacProvider=CDK --no-interactive
  

• Chain generators with && in a single Bash call after workspace creation. Pass --prefer-install-dependencies=false on each generator except the last so dependencies install once at the end, for example:

  cd my-app && \
    pnpm nx g @aws/nx-plugin:ts#trpc-api --no-interactive --name=my-app-api --auth=IAM --prefer-install-dependencies=false && \
    pnpm nx g @aws/nx-plugin:ts#react-website --no-interactive --name=my-app-website --uxProvider=Shadcn --prefer-install-dependencies=false && \
    pnpm nx g @aws/nx-plugin:ts#react-website#auth --no-interactive --project=@my-app/my-app-website --cognitoDomain=my-app-auth --prefer-install-dependencies=false && \
    pnpm nx g @aws/nx-plugin:connection --no-interactive --sourceProject=@my-app/my-app-website --targetProject=@my-app/my-app-api --prefer-install-dependencies=false && \
    pnpm nx g @aws/nx-plugin:ts#infra --no-interactive --name=infra && \
    pnpm nx sync && \
    pnpm lint && \
    pnpm build
  

• --prefer-install-dependencies=false asks a generator to defer its dependency install so the batch installs once at the end (the final generator above omits the flag and installs everything).

• Use a timeout of 300000ms (5 minutes) for workspace creation (downloads dependencies).

• nx sync is required before building — generators modify TypeScript project references.

Troubleshooting

MCP Server Connection Issues

Problem: MCP server won't start or connect Solution:

1. Verify Node.js and npm are installed: node --version && npm --version
2. Try running manually: npx -y @aws/nx-plugin-mcp
3. If you get ENOENT npx, use the full path: replace npx with the output of which npx

Generator Fails

Problem: Generator command fails with errors Solution:

1. Ensure you're in an Nx workspace root directory
2. Check that @aws/nx-plugin is installed: look for it in package.json
3. Run nx reset to clear the Nx daemon cache
4. Try running with --verbose flag for more details

TypeScript Import Errors

Problem: Import errors after adding project dependencies Solution:

1. Run nx sync to update TypeScript project references
2. Check tsconfig.base.json for correct path aliases
3. Remember TypeScript aliases use : prefix (e.g. :my-scope/my-lib)

Python Dependency Issues

Problem: Python imports not resolving Solution:

1. Use nx run <project>:add <dependency> to add dependencies
2. Ensure UV is installed and uv.lock is up to date
3. Check pyproject.toml for correct dependency declarations

Configuration

No additional configuration required — the MCP server works out of the box via npx.

MCP Server: nx-plugin-for-aws Package: @aws/nx-plugin Documentation: https://awslabs.github.io/nx-plugin-for-aws