@aws/nx-plugin-mcp 1.0.0-rc.9 → 1.0.0-rc.90

package/docs/get_started/building-with-ai.mdx

@@ -0,0 +1,116 @@
+---
+title: Building with AI
+description: Building with AI and the Nx Plugin for AWS MCP Server
+---
+
+import Link from "@components/link.astro";
+import Snippet from "@components/snippet.astro";
+import { Steps, Tabs, TabItem } from "@astrojs/starlight/components";
+
+Install the [Claude Plugin](https://code.claude.com/docs/en/plugins), [Kiro Power](https://kiro.dev/docs/powers/), or [MCP Server](https://modelcontextprotocol.io/introduction) to enable AI assistants to work effectively with the plugin. By using these, you can accelerate your development workflow with AI while benefitting from your projects being scaffolded in a consistent fashion, spending less time on setting up the main components and benefitting from the security, observability, type-safety and local development built into the plugin.
+
+## Configure your AI Assistant
+
+:::tip[Project-level configuration is automatic]
+Workspaces created with the Nx Plugin for AWS preset already include project-level MCP configuration for common coding agents (Claude Code, Cursor, Kiro, Gemini CLI, GitHub Copilot and OpenAI Codex). Any agent working inside the workspace can use the MCP server without further setup. The steps below configure the MCP server globally for use across all of your projects.
+:::
+
+<Tabs syncKey="ai-assistant">
+  <TabItem label="Kiro">
+    The Nx Plugin for AWS ships as a [Kiro Power](https://kiro.dev/docs/powers/) that bundles the MCP server with steering documentation and workflow guides.
+
+    <Steps>
+
+    1. Open the Powers panel in Kiro and click **Add power from GitHub**
+    2. Enter the following URL:
+
+       ```
+       https://github.com/awslabs/nx-plugin-for-aws/tree/main/powers/nx-plugin-for-aws
+       ```
+
+    3. Click **Install**
+
+    </Steps>
+
+    Kiro automatically configures the MCP server — no additional setup required.
+
+  </TabItem>
+  <TabItem label="Kiro CLI">
+    Run the following command:
+
+    ```bash
+    kiro-cli mcp add \
+      --name nx-plugin-for-aws \
+      --scope global \
+      --command npx \
+      --args "-y,@aws/nx-plugin-mcp"
+    ```
+
+    See the [Kiro CLI MCP docs](https://kiro.dev/docs/cli/mcp/) for more details.
+
+  </TabItem>
+  <TabItem label="Claude Code">
+    The Nx Plugin for AWS is distributed as a [Claude Code plugin](https://code.claude.com/docs/en/plugins) that bundles a [Skill](https://code.claude.com/docs/en/skills) with the MCP server.
+
+    Run the following commands inside Claude Code, one at a time:
+
+    ```
+    /plugin marketplace add awslabs/nx-plugin-for-aws
+    ```
+
+    ```
+    /plugin install nx-plugin-for-aws@nx-plugin-for-aws
+    ```
+
+    Then run `/reload-plugins` to activate the plugin.
+
+  </TabItem>
+  <TabItem label="Cursor">
+    Add the following to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project):
+
+    <Snippet name="mcp/config" />
+
+    See the [Cursor MCP docs](https://cursor.com/docs/mcp) for more details.
+
+  </TabItem>
+  <TabItem label="Codex">
+    Add the following to `~/.codex/config.toml`:
+
+    ```toml
+    [mcp_servers.nx-plugin-for-aws]
+    command = "npx"
+    args = ["-y", "@aws/nx-plugin-mcp"]
+    ```
+
+    See the [Codex config docs](https://developers.openai.com/codex/config-reference) for more details.
+
+  </TabItem>
+  <TabItem label="Other">
+    Most MCP-compatible assistants use a JSON configuration file. Add the following entry:
+
+    <Snippet name="mcp/config" />
+
+    If you have issues such as `ENOENT npx`, replace the command with the full path to `npx` (find it with `which npx`).
+
+    For assistant-specific documentation:
+
+    <Snippet name="mcp/assistant-docs" />
+
+  </TabItem>
+</Tabs>
+
+## Start Vibe Coding
+
+Ask your AI Assistant to build something using the `nx-plugin-for-aws`! It will typically create a workspace, scaffold with the applicable generators, then fill in the business logic.
+
+Try a prompt like:
+
+> _"Build a multi-agent application using the Nx Plugin for AWS. I want a React frontend that talks to a backend orchestrator agent which delegates to specialised research and writing agents."_
+
+Or for a smaller starting point:
+
+> _"Use the Nx Plugin for AWS to scaffold a React website backed by a tRPC API, with Cognito auth and CDK infrastructure."_
+
+## Build your own MCP Server
+
+Check out the <Link path="/guides/ts-mcp-server">`ts#mcp-server` generator guide</Link> for details about building your own MCP Server.

package/docs/get_started/concepts.mdx

@@ -0,0 +1,67 @@
+---
+title: Concepts
+description: Key concepts.
+---
+import Link from '@components/link.astro';
+import FrameworkLogos from '@components/framework-logos.astro';
+
+The `@aws/nx-plugin` is an [Nx](https://nx.dev/) plugin that provides a toolkit for building and deploying full-stack applications on AWS. It gives you a collection of [Generators](#generators) which scaffold best-practice application code _and_ the infrastructure to deploy it — type-safe, locally runnable, and deployable from the start, getting you closer to production.
+
+Rather than starting from a blank page, you (or your AI agent) pick the components you need — APIs, websites, authentication, AI agents, infrastructure — provide a few configuration options, and the plugin generates best-practice starter code. It even wires projects together for you (including updating existing files via AST transforms) to produce type-safe clients between your frontend and backend.
+
+## Built on Nx and its generators
+
+[Nx](https://nx.dev) is a smart build framework for managing monorepos. It is language agnostic, letting TypeScript, Python, infrastructure and more live and build together in a single workspace. Its build system uses caching and dependency graph analysis to only rebuild what changed and run tasks in parallel, keeping testing, linting and building fast as your workspace grows.
+
+Every piece of functionality in the `@aws/nx-plugin` is delivered as an Nx [Generator](https://nx.dev/features/generate-code) — automated scaffolding that produces consistent code structures from predefined templates. Generators can be invoked via the [Nx CLI](https://nx.dev/features/generate-code#invoke-generators), the [Nx Console IDE plugin](https://nx.dev/getting-started/editor-setup), or by your AI assistant through the <Link path="/get_started/building-with-ai">Nx Plugin for AWS MCP Server</Link>.
+
+Because every component is a generator, you only add what you need, when you need it. Start with an API, add a website later, connect them when you're ready — each step is a single command.
+
+## Build with proven frameworks
+
+The `@aws/nx-plugin` deliberately avoids building custom abstractions on top of the tools you already know. Instead of inventing bespoke frameworks, runtimes or wrappers, it scaffolds idiomatic code using established, widely-adopted open-source projects. This means your existing skills carry over directly, you can rely on the official documentation for each framework, and you're never locked into a layer that only this plugin understands.
+
+The generated code stands on the shoulders of best-in-class frameworks, including:
+
+<FrameworkLogos />
+
+The plugin's value is in how these pieces are configured and connected together for AWS — not in replacing them.
+
+## Open for modification
+
+All generated code is _your_ code. The `@aws/nx-plugin` is a build-time tool, not a runtime dependency — once a generator has run, the plugin is no longer in the picture. You can read every file it produced, commit it, and change it however you like.
+
+This means:
+
+- **No escape hatches.** There's no proprietary configuration surface to learn or wrestle with when you need to do something the generator didn't anticipate. You edit the generated code directly, the same way you would edit any code you wrote yourself.
+- **No new layers of abstraction.** Generators emit plain, idiomatic code for the underlying frameworks. There's no wrapper API or magic indirection sitting between you and React, tRPC, FastAPI, CDK or any of the other tools — what you see is what runs.
+- **The plugin isn't a dependency.** It generates code and steps out of the way. Your application doesn't import or rely on `@aws/nx-plugin` at runtime, so you're never blocked by it and never locked in.
+
+If you don't like something in the generated code, you are free to modify it. Generators give you a head start, not a cage.
+
+## In step with improvements
+
+Owning your code usually comes at a cost: the moment you start editing a scaffold, you're cut off from the fixes and improvements made upstream. Adopting them again means reading a changelog, regenerating, and reconciling a diff by hand. <Link path="/get_started/upgrading">Migrations</Link> are how the `@aws/nx-plugin` works to keep that from happening.
+
+Releases ship migrations alongside them, aiming to bring the code earlier generators produced into step with the improvements we've made since. When we fix a bug, harden a security default or refine a generated pattern, running `nx migrate` applies that change to your code, in place — instead of leaving you to spot it in a changelog and port it across yourself.
+
+In practice:
+
+- **Upgrading is automated, not a re-adoption exercise.** A workspace generated months ago can move forward with the plugin rather than drifting further from it.
+- **Customisations are pattern-matched, not overwritten.** Migrations check that a file still matches the shape the generator produced. Where it has diverged beyond what they can safely update, they leave your code alone and report the manual follow-up instead.
+- **Some changes arrive as agent prompts.** Where the right edit depends on what you've built, the migration is a prompt your AI coding agent applies rather than a codemod.
+- **Upgrades are opt-in.** Nothing in your workspace changes until you choose to run `nx migrate`.
+
+Migrations narrow the gap rather than close it: how far your code has moved decides how much they can do, and some steps will still need your hands.
+
+## Minimal dependencies
+
+The `@aws/nx-plugin` strives to keep the number of global dependencies to a minimum. What you need to get started boils down to which generators you invoke.
+
+As an example, any TypeScript-based generator will only require [Node](https://nodejs.org/en/download) to be installed. For Python-based projects, [UV](https://docs.astral.sh/uv/) is the only requirement.
+
+## Type safety
+
+The `@aws/nx-plugin` employs type-safety to simplify the developer experience via IDE completions, while also eliminating runtime errors which would otherwise only surface in a non type-safe implementation. As such, all components that are vended are type-safe by default.
+
+Type safety flows across project boundaries: when you connect a website to an API, the generated client shares types with the backend, so a change to an API contract surfaces as a compile-time error in your frontend rather than a bug in production. Refactor with confidence.

package/docs/get_started/existing-project.mdx

@@ -0,0 +1,180 @@
+---
+title: Add to an Existing Project
+description: How to adopt @aws/nx-plugin in an existing Nx workspace or non-Nx monorepo.
+---
+import { Steps, Aside, FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import Snippet from '@components/snippet.astro';
+import Drawer from '@components/drawer.astro';
+import NxCommands from '@components/nx-commands.astro';
+import NxInitCommand from '@components/nx-init-command.astro';
+import TsConfigBaseCompilerOptions from '@components/tsconfig-base-compiler-options.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+
+Not every project starts with `pnpm create @aws/nx-workspace`. If you already have an [Nx workspace](https://nx.dev) — or a monorepo you can add Nx to — you can adopt `@aws/nx-plugin` incrementally without recreating your project.
+
+<Aside type="tip">
+You can use your agentic coding tool of choice to add the plugin for you, using the <Link path="get_started/building-with-ai">MCP server</Link>. Try the prompt:
+
+> Add the Nx Plugin for AWS to this project.
+</Aside>
+
+## Prerequisites
+
+<Snippet name="prerequisites" />
+
+<Aside type="caution" title="Before you start">
+Save and commit all in-progress work first, so the changes made at each step can be reviewed — and reverted — at any point.
+</Aside>
+
+## Adding Nx to a non-Nx project
+
+If your project doesn't use Nx yet, add it first with [`nx init`](https://nx.dev/recipes/adopting-nx/adding-to-existing-project). This is a step Nx itself owns; the plugin builds on top of a working Nx workspace. It works on a plain package, an npm/pnpm/yarn/bun workspace, a Turborepo or a Lerna monorepo:
+
+<NxInitCommand />
+
+Follow the prompts to add Nx to your workspace. For more details refer to the [Nx Documentation](https://nx.dev/recipes/adopting-nx/adding-to-existing-project).
+
+<Aside type="note" title="pnpm workspaces">
+pnpm only runs install scripts for allow-listed packages, and `nx` needs its install script — without it, the install `nx init` performs can fail, leaving a `set this to true or false` placeholder in `pnpm-workspace.yaml`. Allow-list it before running `nx init`:
+
+```yaml title="pnpm-workspace.yaml"
+allowBuilds:
+  - nx
+```
+</Aside>
+
+### Non-Node projects (Python, Go, Java, Rust, …)
+
+Nx and the plugin are distributed as npm packages, so a project with no Node.js tooling needs a minimal root `package.json` before `nx init` can do anything useful:
+
+```json title="package.json"
+{
+  "name": "my-project",
+  "private": true,
+  "type": "module"
+}
+```
+
+Create that file, then run `nx init` and [add the plugin](#adding-the-plugin) as usual. Your existing language tooling is untouched — Nx projects generated by the plugin (including <Link path="guides/py-project">Python projects</Link>) live alongside your existing code, and you can wire your existing build into Nx incrementally.
+
+To bring your existing projects under Nx, you have a few options depending on the language:
+
+- **Languages with an official Nx plugin** — [Java (Gradle or Maven)](https://nx.dev/docs/technologies/java/introduction) and [.NET](https://nx.dev/docs/technologies/dotnet/introduction) have dedicated plugins that infer your projects' tasks automatically. Add the relevant one, e.g. `nx add @nx/gradle`, `nx add @nx/maven` or `nx add @nx/dotnet`.
+- **Languages with a community plugin** — for example [Go](https://nx.dev/plugin-registry) (`@nx-go/nx-go`) or [Rust](https://nx.dev/plugin-registry) (`@monodon/rust`). Browse the [Nx Plugin Registry](https://nx.dev/plugin-registry) for others.
+- **Any other language** — add a `project.json` to each project and define its targets to run your existing build commands, so `nx build <project>` (and `nx run-many`) drive them. See the <Link path="guides/workspace">workspace guide</Link> for how `project.json` and targets are set up.
+
+### Single-package projects
+
+The plugin is designed for monorepos — it generates each project into its own directory under `packages/`. If you're starting from a **single-package project** (one `package.json` at the root with your source directly beneath it, no workspaces), move your existing package into `packages/` before adopting the plugin so your project sits alongside the ones the plugin generates:
+
+<Steps>
+
+1. Create a `packages/<your-package>/` directory and move your source, `package.json` and `tsconfig.json` into it.
+2. Create a new root `package.json` that acts as the workspace manifest rather than a project itself:
+
+   ```json title="package.json"
+   {
+     "name": "<your-workspace>",
+     "private": true,
+     "type": "module"
+   }
+   ```
+
+3. Declare the workspace so your package manager discovers projects under `packages/`. For `pnpm`, add a `pnpm-workspace.yaml`:
+
+   ```yaml title="pnpm-workspace.yaml"
+   packages:
+     - packages/*
+   ```
+
+   For `npm`/`yarn`/`bun`, add a `workspaces` field to the root `package.json` instead:
+
+   ```json title="package.json"
+   {
+     "workspaces": ["packages/*"]
+   }
+   ```
+
+4. Run `nx init` (if you haven't), then [add the plugin](#adding-the-plugin).
+
+</Steps>
+
+<Aside type="note" title="Package manager">
+The plugin's projects are generated under a `packages/` directory. `pnpm` reads workspace globs from `pnpm-workspace.yaml`; other package managers read the `workspaces` field of the root `package.json` — `init` updates whichever your workspace uses.
+</Aside>
+
+## Adding the plugin
+
+Use [`nx add`](https://nx.dev/nx-api/nx/documents/add), which installs the plugin at a version compatible with your Nx installation and then runs its `init` generator to configure your workspace:
+
+<NxCommands commands={['add @aws/nx-plugin']} />
+
+Once it completes, your workspace is ready — choose the generators you need and start generating projects.
+
+### What this generator configures
+
+Adding the plugin makes the deterministic changes a workspace needs to run the plugin's generators. It preserves your workspace's module format: a workspace whose root `package.json` has `type: "module"` stays ESM, anything else stays CommonJS, and generated code follows suit. It does not overwrite existing files, and you may need to make some manual changes following this step depending on your existing configuration.
+
+It creates or updates the following files:
+
+<FileTree>
+- aws-nx-plugin.config.mts records your chosen IaC provider (CDK or Terraform) and container engine; generators read `iac.provider` from here
+- nx.json registers the sync generators (`@nx/js:typescript-sync` and `@aws/nx-plugin:ts#sync`) on the `compile` target so TypeScript project references stay in sync
+- tsconfig.json a root TypeScript config referencing your workspace's projects, which Nx's TypeScript sync keeps up to date
+- tsconfig.base.json the shared compiler options the plugin's TypeScript projects extend (see below for what it carries)
+- pnpm-workspace.yaml (pnpm only) allow-lists the build scripts the plugin's dependencies need (`@swc/core`, `esbuild`, `nx`, `sharp`)
+- package.json convenience scripts for common tasks, plus the `@aws/nx-plugin`, `@aws/nx-plugin-mcp`, `nx`, `@nx/js`, `@nx/workspace`, `typescript` and Biome dev dependencies
+- biome.json default Biome formatter and linter configuration
+- .mcp.json configures the MCP server for supported coding agents unless disabled (also .cursor/, .kiro/, .gemini/, .vscode/ and .codex/ equivalents). It runs the workspace's own `@aws/nx-plugin-mcp`, so the server always matches the version installed in your workspace
+</FileTree>
+
+The <Link path="get_started/building-with-ai">MCP server</Link> configuration can be disabled with `--mcp=false`.
+
+<Drawer title="tsconfig.base.json" trigger="Click here to see the compiler options a created tsconfig.base.json carries.">
+The plugin's TypeScript projects rely on these compiler options. If a `tsconfig.base.json` already exists it is left as-is, so if you keep your own these are the options to align with:
+
+<TsConfigBaseCompilerOptions />
+</Drawer>
+
+### Options
+
+<GeneratorParameters generator="init" />
+
+## Troubleshooting
+
+#### `nx build <project>` no longer works for an existing TypeScript library
+
+The first `ts#project` run configures the `@nx/js/typescript` plugin to infer the TypeScript build target as `compile` (the plugin reserves `build` for orchestrating `lint`, `compile` and `test`). Existing libraries relying on the inferred `build` target are inferred as `compile` too — run `nx run <project>:compile`, or use `nx run-many --target build,compile`. Libraries with an explicit `build` target in their `project.json` are unaffected.
+
+#### `The workspace is out of sync`
+
+TypeScript project references need syncing. `init` registers the sync generators; run:
+
+<NxCommands commands={['sync']} />
+
+#### `ERR_PNPM_IGNORED_BUILDS` during install
+
+pnpm skips install scripts for packages that aren't allow-listed. `init` allow-lists the ones the plugin's tooling needs (`@swc/core`, `esbuild`, `nx`, `sharp`) in `pnpm-workspace.yaml`, but the block can fire during `nx add @aws/nx-plugin` itself — before `init` has run. Run `pnpm approve-builds` and approve the listed packages (or add them under `allowBuilds:`), then re-run the install.
+
+#### `nx sync` hangs, or `plugin worker ... exited before the connection was established`
+
+If two different `nx` versions are present in the same node_modules tree (run `npm ls nx` to confirm), their plugin-worker IPC deadlocks. The `init` generator pins the root `nx` devDependency to the version the plugin's own `@nx/*` packages resolve, but a later install of another `@nx/*` package at a different patch version can reintroduce the mismatch. Align every `nx` and `@nx/*` entry in your root `package.json` to a single version and reinstall.
+
+#### `ts.readConfigFile is not a function`
+
+Your workspace has TypeScript 7 installed, which [Nx does not yet support](https://nx.dev/docs/technologies/typescript/guides/typescript-7) — Nx's plugins rely on TypeScript's in-process compiler API, which TypeScript 7 no longer provides. Pin `typescript` in your root `package.json` to the version the plugin uses (the `init` generator installs a compatible version) and reinstall.
+
+#### `Recursive task invocation detected`
+
+Your **root** `package.json` is registered as an Nx project (it has an `"nx"` key, which `nx init` adds for a single-package repo) *and* carries a `build` script of `nx run-many --target build`. Nx then infers a `build` target on the root that calls itself. Move your source into `packages/<your-package>/` so the root becomes a workspace manifest rather than a project — see [Single-package projects](#single-package-projects). (Nx's own standalone presets avoid this by setting `"nx": { "includedScripts": [] }` on the root package; you can do the same as a quicker alternative.)
+
+#### TypeScript errors in your **existing** projects after adding the plugin (`TS6059`, `TS7016`, `TS5011`, `NG4006`)
+
+The plugin's own generated projects carry the TypeScript settings they need in their per-project `tsconfig.lib.json`, so they build regardless of your `tsconfig.base.json`. These errors show up instead in a **pre-existing project of yours** that inherits a `tsconfig.base.json` `init` created (with `composite`/`emitDeclarationOnly`/`nodenext`) but isn't compatible with those settings — for example, the Angular compiler rejects `emitDeclarationOnly` (`NG4006`), or a project that sets `outDir` without a `rootDir` now needs one (`TS5011`). Add per-project `tsconfig` overrides re-declaring the conflicting options for those projects (e.g. `"rootDir": "src"`), or point the plugin's projects and your projects at separate base configs.
+
+`init` never rewrites an existing `tsconfig.base.json`, precisely so it can't silently break the projects that inherit from it — resolving these mismatches is a decision only you can make for your codebase.
+
+<Aside type="note" title="ESM and CommonJS">
+The module format is workspace-wide, read from the root `package.json` `type` field: `type: "module"` means ESM, anything else (including no `type` field) means CommonJS. `init` preserves whichever your workspace uses, and the plugin's TypeScript generators emit matching code. If you later want to switch, change the root `type` — but that's a migration of your existing code, not something `init` does for you.
+</Aside>

package/docs/get_started/graph-builder.mdx

@@ -0,0 +1,39 @@
+---
+title: Graph Builder
+description: Design your workspace visually, then copy the commands that scaffold it.
+# The builder needs the full content width, which the table of contents column
+# would otherwise take.
+tableOfContents: false
+---
+import Link from '@components/link.astro';
+import GraphBuilder from '@components/graph-builder.astro';
+
+Sketch the projects your workspace needs and the connections between them, and the builder generates the commands that scaffold exactly what you drew. Copy them, run them, and you have a working workspace.
+
+Drag components from the palette onto the canvas, drag from a component's right edge to another to connect them, and edit each component's properties on the right. The generated commands at the bottom update with every change — hit **Copy** to take the whole script.
+
+<GraphBuilder />
+
+## How it works
+
+Each component on the canvas maps to a generator, and each connection to the <Link path="guides/connection">connection generator</Link>. The commands are emitted in dependency order: the workspace first, then the projects, then the components they host, then the connections wiring them together.
+
+A website always gets <Link path="guides/react-website-auth">Cognito authentication</Link> added straight after it, since `ts#website` leaves that to a follow-up generator.
+
+An `infra` project is added at the end — <Link path="guides/typescript-infrastructure">`ts#infra`</Link> or <Link path="guides/terraform-project">`terraform#project`</Link>, matching your IaC choice. Every generated project vends constructs for it to instantiate, so this is what you deploy. Because it owns that name, no component on the canvas can be called `infra`.
+
+Use **Vertical** / **Horizontal** in the toolbar to swap which way the graph flows — the connection points move to the top and bottom edges of each component, and the layout is transposed to match.
+
+Drag the canvas background to pan around, and drag a component to reposition it. Shift-click to select several components and move them as a group. Click a connection to select it, then press <kbd>Delete</kbd> to remove it (or use the ✕ on the connection itself).
+
+The palette lists every project and component type that can take part in a connection, and you can only draw the connections the plugin supports — so a graph that validates is a graph that scaffolds.
+
+Three rules are worth knowing:
+
+- **Components share a host project.** An agent and an MCP server are added _to_ a project rather than being projects of their own. Give them the same host project name to put them in one project, or different names for one project each.
+- **Some connections constrain their endpoints.** Connecting an agent to another agent requires the target to use the `a2a` protocol, for instance. Where a property setting would break a connection you have drawn, the builder says so against the component and the connection.
+- **Drawing a connection can adjust the target.** Connecting a website to an agent switches that agent to the `ag-ui` protocol, and connecting an agent to another agent switches the target to `a2a` — the protocols those connections are built on. A property you have set yourself is never changed.
+
+:::tip[Prefer to build with AI?]
+The plugin ships an MCP server, so your coding agent can scaffold and connect projects for you. See <Link path="get_started/building-with-ai">Building with AI</Link>.
+:::