Nx Plugin For AWS

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