@aws/nx-plugin-mcp 1.0.0-rc.37 → 1.0.0-rc.39

package/docs/get_started/concepts.mdx

@@ -0,0 +1,52 @@
+---
+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 production-ready application code _and_ the infrastructure to deploy it — type-safe, locally runnable, and ready to ship.
+
+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.
+
+## 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,176 @@
+---
+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 `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)
+</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
+
+#### `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/quick-start.mdx

@@ -0,0 +1,266 @@
+---
+title: Quick Start Guide
+description: A quick start on how to use @aws/nx-plugin.
+---
+import { Steps } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import Snippet from '@components/snippet.astro';
+import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+import InstallCommand from '@components/install-command.astro';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+This guide walks you through the basics of installing and using `@aws/nx-plugin` to rapidly build projects on AWS.
+
+:::tip[Full-Stack Tutorial]
+For a more in-depth tutorial for building a full-stack application, check out the <Link path="get_started/tutorials/dungeon-game/overview">Dungeon Adventure Tutorial</Link>.
+:::
+
+## Prerequisites
+
+The following global dependencies are needed before proceeding:
+
+<Snippet name="prerequisites" />
+
+## Step 1: Initialize a New Nx Workspace
+
+Run the following command to create an <Link path="guides/workspace">Nx workspace</Link> with the package manager of your choice:
+
+<CreateNxWorkspaceCommand workspace="my-project" />
+
+:::tip[Choosing an IaC Provider]
+You will be prompted for your preferred infrastructure as code (IaC) provider, either [CDK](https://docs.aws.amazon.com/cdk/) or [Terraform](https://developer.hashicorp.com/terraform). You can skip the prompt by running the command with `--iac`, ie:
+
+<Infrastructure>
+<Fragment slot="cdk">
+<CreateNxWorkspaceCommand workspace="my-project" iac="cdk" />
+</Fragment>
+<Fragment slot="terraform">
+<CreateNxWorkspaceCommand workspace="my-project" iac="terraform" />
+</Fragment>
+</Infrastructure>
+:::
+
+Once complete, navigate to the project directory:
+
+```sh
+cd my-project
+```
+
+## Step 2: Use Generators to Scaffold your Project
+
+We'll add a tRPC API, React Website, Cognito Authentication, and CDK or Terraform Infrastructure in this quick-start guide. Depending on the type of project you're building, you can choose any combination of generators to quickly bootstrap your project. Check out the __Guides__ in the navigation bar to the left to see the full list of options.
+
+### Add a tRPC API
+
+<RunGenerator generator="ts#api" requiredParameters={{ name: 'demo-api', framework: 'trpc', auth: 'iam' }} />
+
+This will create the API inside the `packages/demo-api` folder.
+
+### Add a React Website
+
+<RunGenerator generator="ts#website" requiredParameters={{ name: 'demo-website' }} />
+
+This scaffolds a new React website in `packages/demo-website`.
+
+### Add Cognito Authentication
+
+<RunGenerator generator="ts#website#auth" requiredParameters={{ project: '@my-project/demo-website', cognitoDomain: 'my-demo' }} />
+
+This sets up the necessary infrastructure and React code to add Cognito Authentication to your website.
+
+### Connect Frontend to Backend
+
+<RunGenerator generator="connection" requiredParameters={{ sourceProject: '@my-project/demo-website', targetProject: '@my-project/demo-api' }} />
+
+This configures the necessary providers to ensure your website can call your tRPC API.
+
+### Add Infrastructure
+
+Add the infrastructure project based on your chosen IAC provider.
+
+<Infrastructure>
+<Fragment slot="cdk">
+<RunGenerator generator="ts#infra" requiredParameters={{ name: 'infra' }} />
+
+This configures a CDK App which you can use to deploy your infrastructure on AWS.
+</Fragment>
+<Fragment slot="terraform">
+<RunGenerator generator="terraform#project" requiredParameters={{ name: 'infra' }} />
+
+This configures a Terraform project which you can use to deploy your infrastructure on AWS.
+</Fragment>
+</Infrastructure>
+
+## Step 3: Run your Website and API Locally
+
+Use the following command to start local dev servers for your website and its connected APIs:
+
+<PackageManagerShortCommand commands={["dev"]} />
+
+Your website will be available at `http://localhost:4200`.
+
+Changes to both your website and API will be reflected in real-time as both the local website and API servers will hot-reload.
+
+## Step 4: Define Cloud Resources and Deploy to AWS
+
+<Infrastructure>
+<Fragment slot="cdk">
+Open `packages/infra/src/stacks/application-stack.ts` and add the following code:
+
+```typescript
+import { Stack, StackProps } from 'aws-cdk-lib';
+import { DemoApi, DemoWebsite, UserIdentity } from ':my-project/common-constructs';
+import { Construct } from 'constructs';
+
+export class ApplicationStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const identity = new UserIdentity(this, 'identity');
+    const api = new DemoApi(this, 'api', {
+      integrations: DemoApi.defaultIntegrations(this).build(),
+    });
+    api.grantInvokeAccess(identity.identityPool.authenticatedRole);
+
+    new DemoWebsite(this, 'website');
+  }
+}
+```
+
+This is all the CDK we need to write to deploy our full stack application.
+</Fragment>
+<Fragment slot="terraform">
+Open `packages/infra/src/main.tf` and add the following code:
+
+```hcl
+# Include metrics tracking for @aws/nx-plugin usage
+module "metrics" {
+  source = "../../common/terraform/src/metrics"
+}
+
+# Deploy user identity
+module "user_identity" {
+  source = "../../common/terraform/src/core/user-identity"
+}
+
+# Shared asset bucket — stages Lambda deployment zips for every lambda / API module
+module "asset_bucket" {
+  source = "../../common/terraform/src/core/asset-bucket"
+}
+
+# Deploy API
+module "demo_api" {
+  source = "../../common/terraform/src/app/apis/demo-api"
+
+  asset_bucket_name = module.asset_bucket.bucket_name
+}
+
+# Grant authenticated users access to invoke the API
+resource "aws_iam_policy" "api_invoke_policy" {
+  name        = "DemoApiInvokePolicy"
+  description = "Policy to allow authenticated users to invoke the API"
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect = "Allow"
+        Action = "execute-api:Invoke"
+        Resource = "${module.demo_api.api_execution_arn}/*/*"
+      }
+    ]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "authenticated_api_access" {
+  role       = module.user_identity.authenticated_role_name
+  policy_arn = aws_iam_policy.api_invoke_policy.arn
+}
+
+# Deploy website
+provider "aws" {
+  alias  = "us_east_1"
+  region = "us-east-1"
+}
+
+module "demo_website" {
+  source = "../../common/terraform/src/app/static-websites/demo-website"
+
+  providers = {
+    aws.us_east_1 = aws.us_east_1
+  }
+
+  depends_on = [module.user_identity, module.demo_api]
+}
+```
+
+This is all the Terraform we need to write to deploy our full stack application.
+</Fragment>
+</Infrastructure>
+
+### Build and Deploy the Infrastructure
+
+Next, run the following command to build your project:
+
+<PackageManagerShortCommand commands={["build"]} />
+
+:::tip[Fixing Lint Errors]
+If you encounter any lint errors, you can run the following command to automatically fix them.
+
+<PackageManagerShortCommand commands={["lint"]} />
+:::
+
+Bootstrap your infrastructure:
+
+<Infrastructure>
+<Fragment slot="cdk">
+<NxCommands commands={['bootstrap infra']} />
+
+:::tip[Bootstrap Regions]
+CDK bootstrapping is required for both your target deployment AWS region, and `us-east-1` to allow deployment of the AWS WAF WebACL for the website.
+:::
+</Fragment>
+<Fragment slot="terraform">
+<NxCommands commands={['bootstrap infra']} />
+
+:::tip[One-Time Setup]
+Terraform bootstrapping creates an S3 bucket to store your Terraform state files. This only needs to be done once per AWS account/region combination.
+:::
+</Fragment>
+</Infrastructure>
+
+Deploy your project:
+
+<Infrastructure>
+<Fragment slot="cdk">
+<NxCommands commands={['deploy infra "my-project-sandbox/*"']} />
+</Fragment>
+<Fragment slot="terraform">
+<NxCommands commands={['apply infra']} />
+
+:::tip[Plan Before Apply]
+This command will first run `terraform plan` to show you what changes will be made, then apply those changes to deploy your infrastructure.
+:::
+</Fragment>
+</Infrastructure>
+
+## Step 5: Test the Website with Deployed Cloud Resources
+
+<Steps>
+1. Fetch the `runtime-config.json` file:
+
+    <NxCommands commands={['run demo-website:load:runtime-config']} />
+
+2. Start the local website server
+
+    <NxCommands commands={['serve demo-website']} />
+</Steps>
+
+Your website will be available at `http://localhost:4200`, and will point to the resources you deployed for the API and authentication.
+
+---
+
+Congratulations! 🎉 You have successfully built and deployed a full-stack application using `@aws/nx-plugin`!