--- 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](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) - [Node >= 22](https://nodejs.org/en/download) (We recommend using something like [NVM](https://github.com/nvm-sh/nvm) to manage your node versions) - verify by running `node --version` - [UV >= 0.5.29](https://docs.astral.sh/uv/getting-started/installation/) 1. install Python 3.14 by running: `uv python install 3.14` 2. verify with `uv python list --only-installed` #### Recommended - [PNPM >= 11](https://pnpm.io/installation#using-npm) (you can also use [Yarn >= 4](https://yarnpkg.com/getting-started/install), [Bun >= 1](https://bun.sh/docs/installation), or [NPM >= 11](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager) if you prefer) - verify by running `pnpm --version`, `yarn --version`, `bun --version` or `npm --version` - [AWS Credentials](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) configured to your target AWS account are required to deploy your application (as well as for some local development workflows). - [Docker](https://www.docker.com/) or [Finch >= 1.6.0](https://runfinch.com/) is required for some generators. For Docker, [multi-platform builds](https://docs.docker.com/build/building/multi-platform/) must be set up; Finch supports [multi-platform builds](https://runfinch.com/docs/getting-started/building-images/#building-a-multi-architecture-container-image) out of the box. - [Terraform >= 1.12](https://developer.hashicorp.com/terraform/install) 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](https://code.visualstudio.com/), we recommend installing the [Nx Console VSCode Plugin](https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console). ### 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: ```bash # 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. ```bash 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: ```bash 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` | Generate an Nx Plugin of your own! Build custom generators automatically made available for AI vibe-coding via MCP | | `ts#project` | Generates a TypeScript project | | `ts#website` | Generates a website application | | `ts#website#auth` | Adds auth to an existing website | | `ts#agent` | Add an AI Agent to a TypeScript project | | `ts#api` | Create a TypeScript API | | `ts#rdb` | Create a relational database project | | `ts#dynamodb` | Create a TypeScript DynamoDB project | | `py#dynamodb` | Create a Python DynamoDB project | | `py#rdb` | Create a Python relational database project | ## 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 ```bash 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: ```bash 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 :add ` 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](https://awslabs.github.io/nx-plugin-for-aws)