@aws/nx-plugin-mcp 1.0.0-rc.46 → 1.0.0-rc.48

package/docs/snippets/lambda-function/deploying-your-function.mdx

@@ -10,7 +10,7 @@ This generator creates CDK or Terraform infrastructure as code based on your sel
 This generator creates a CDK construct for deploying your function in the `common/constructs` folder. You can use this in a CDK application:
 
 ```typescript {1, 6}
-import { MyProjectMyFunction } from ':my-scope/common-constructs';
+import { MyProjectMyFunction } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -38,7 +38,7 @@ The example below demonstrates the CDK code for invoking your lambda function on
 ```typescript
 import { Rule, Schedule } from 'aws-cdk-lib/aws-events';
 import { LambdaFunction } from 'aws-cdk-lib/aws-events-targets';
-import { MyProjectMyFunction } from ':my-scope/common-constructs';
+import { MyProjectMyFunction } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {

package/docs/snippets/mcp/bedrock-deployment.mdx

@@ -15,7 +15,7 @@ A CDK construct is generated for your MCP Server, named based on the `name` you
 You can use this CDK construct in a CDK application:
 
 ```ts {6}
-import { MyProjectMcpServer } from ':my-scope/common-constructs';
+import { MyProjectMcpServer } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -64,7 +64,7 @@ By default, your MCP server will be secured using IAM authentication, simply dep
 <Infrastructure>
 <Fragment slot="cdk">
 ```ts {5}
-import { MyProjectMcpServer } from ':my-scope/common-constructs';
+import { MyProjectMcpServer } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -76,7 +76,7 @@ export class ExampleStack extends Stack {
 You can grant access to invoke your MCP server on Bedrock AgentCore Runtime using the `grantInvokeAccess` method. For example you may wish for an agent generated with the <Link path="/guides/py-agent">`py#agent`</Link> generator to call your MCP server:
 
 ```ts {8}
-import { MyProjectAgent, MyProjectMcpServer } from ':my-scope/common-constructs';
+import { MyProjectAgent, MyProjectMcpServer } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -126,7 +126,7 @@ When you select `Cognito` authentication, the generator configures the MCP serve
 The generated construct accepts an `identity` prop which configures Cognito authentication:
 
 ```ts {8}
-import { MyProjectMcpServer, UserIdentity } from ':my-scope/common-constructs';
+import { MyProjectMcpServer, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {

package/docs/snippets/pdk-migration/example/01-migrate-api.mdx

@@ -23,9 +23,9 @@ If you used OpenAPI or TypeSpec as your modelling language, or have handlers imp
 
 #### Generate a TypeScript Smithy API
 
-Run the <Link path="/guides/ts-smithy-api">`ts#smithy-api` generator</Link> to set up your api project in `packages/api`:
+Run the <Link path="/guides/ts-smithy-api">`ts#api` generator</Link> with `framework` set to `smithy` to set up your api project in `packages/api`:
 
-<RunGenerator generator="ts#smithy-api" noInteractive requiredParameters={{ name: 'api', namespace: 'com.aws', auth: 'IAM' }} />
+<RunGenerator generator="ts#api" noInteractive requiredParameters={{ name: 'api', framework: 'smithy', namespace: 'com.aws', auth: 'iam' }} />
 
 You will notice this generates a `model` project, as well as a `backend` project. The `model` project contains your Smithy model, and `backend` contains your server implementation.
 
@@ -128,12 +128,14 @@ You can consider the `api/backend` project as somewhat equivalent to Type Safe A
 
 One of the main differences between Type Safe API and the `ts#smithy-api` generator is that handlers are implemented using the [Smithy Server Generator for TypeScript](https://smithy.io/2.0/languages/typescript/ts-ssdk/index.html), rather than Type Safe API's own generated handler wrappers (found in the `api/generated/typescript/runtime` project).
 
-The shopping list application's lambda handlers rely on the `@aws-sdk/client-dynamodb` package, so let's install that first:
+The shopping list application's lambda handlers rely on the `@aws-sdk/client-dynamodb` package, so let's install that into the `@shopping-list/api` project:
 
-<InstallCommand pkg="@aws-sdk/client-dynamodb" />
+<InstallCommand pkg="@aws-sdk/client-dynamodb" project="@shopping-list/api" />
 
 Then, let's copy the `handlers/src/dynamo-client.ts` file from the PDK project to `backend/src/operations` so it's available for our handlers.
 
+The `ts#smithy-api` generator scaffolds an example `Echo` operation. Since we removed this from our model, delete the corresponding handler in `backend/src/operations/echo.ts`. We'll register our migrated operations in `service.ts` further below.
+
 To migrate the handlers, you can follow these general steps:
 
 <Steps>
@@ -583,7 +585,7 @@ Additionally, update `packages/api/backend/project.json` and update `metadata.ap
     "generator": "ts#smithy-api",
 -    "apiName": "api",
 +    "apiName": "my-api",
-    "auth": "IAM",
+    "auth": "iam",
     "modelProject": "@shopping-list/api-model",
     "ports": [3001]
   },

package/docs/snippets/pdk-migration/example/02-migrate-website.mdx

@@ -11,21 +11,21 @@ import InstallCommand from '@components/install-command.astro';
 
 The `CloudscapeReactTsWebsiteProject` used in the shopping list application configured a React website with CloudScape and Cognito authentication built in.
 
-This project type leveraged [`create-react-app`](https://github.com/facebook/create-react-app), which is now deprecated. For migrating the website in this guide, we will use the <Link path="/guides/react-website">`ts#react-website` generator</Link>, which uses more modern and supported technologies, namely [Vite](https://vite.dev/).
+This project type leveraged [`create-react-app`](https://github.com/facebook/create-react-app), which is now deprecated. For migrating the website in this guide, we will use the <Link path="/guides/react-website">`ts#website` generator</Link>, which uses more modern and supported technologies, namely [Vite](https://vite.dev/).
 
 As part of the migration, we will also move from PDK's configured React Router to [TanStack Router](https://tanstack.com/router), which adds additional type-safety to website routing.
 
 #### Generate a React Website
 
-Run the <Link path="/guides/react-website">`ts#react-website` generator</Link> to set up your website project in `packages/website`:
+Run the <Link path="/guides/react-website">`ts#website` generator</Link> with `framework` set to `react` to set up your website project in `packages/website`. Since the shopping list application is built with CloudScape components, we also set `ux` to `cloudscape` (the default is `shadcn`):
 
-<RunGenerator generator="ts#react-website" noInteractive requiredParameters={{ name: 'website' }} />
+<RunGenerator generator="ts#website" noInteractive requiredParameters={{ name: 'website', framework: 'react', ux: 'cloudscape' }} />
 
 #### Add Cognito Authentication
 
-The React website generator above doesn't bundle cognito authentication by default like `CloudscapeReactTsWebsiteProject`, instead it's added explicitly via the <Link path="/guides/react-website-auth">`ts#react-website#auth` generator</Link>.
+The React website generator above doesn't bundle cognito authentication by default like `CloudscapeReactTsWebsiteProject`, instead it's added explicitly via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link>.
 
-<RunGenerator generator="ts#react-website#auth" noInteractive requiredParameters={{ project: 'website', cognitoDomain: 'shopping-list' }} />
+<RunGenerator generator="ts#website#auth" noInteractive requiredParameters={{ project: 'website', cognitoDomain: 'shopping-list' }} />
 
 This adds React components which manage the appropriate redirects to ensure users log in using the Cognito hosted UI. This also adds a CDK construct to deploy the Cognito resources in `packages/common/constructs`, called `UserIdentity`.
 
@@ -57,9 +57,26 @@ This generates the necessary client providers and build targets for your website
 
 #### Add AWS Northstar Dependency
 
-The `CloudscapeReactTsWebsiteProject` automatically included a dependency on `@aws-northstar/ui` which is used in our shopping list application, so we add it here:
+The `CloudscapeReactTsWebsiteProject` automatically included a dependency on `@aws-northstar/ui` which is used in our shopping list application, so we add it to the `@shopping-list/website` project:
 
-<InstallCommand pkg="@aws-northstar/ui" />
+<InstallCommand pkg="@aws-northstar/ui" project="@shopping-list/website" />
+
+`@aws-northstar/ui` bundles a code editor component which depends on `ace-builds`, using a webpack-specific import that Vite cannot resolve. Since our shopping list application doesn't use this component, we exclude it from the bundle by adding it to the `external` configuration within the existing `build` options in `packages/website/vite.config.mts`:
+
+```diff lang="ts"
+// packages/website/vite.config.mts
+  build: {
+    outDir: '../../dist/packages/website/bundle',
+    emptyOutDir: true,
+    reportCompressedSize: true,
+    commonjsOptions: {
+      transformMixedEsModules: true,
+    },
++    rollupOptions: {
++      external: ['ace-builds/webpack-resolver'],
++    },
+  },
+```
 
 #### Move the Components and Pages
 
@@ -79,12 +96,14 @@ Note that you'll now have some build errors visible in your IDE, we'll need to m
 
 #### Migrate from React Router to TanStack Router
 
-Since we're using [file-based routing](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing), we can use the website local development server to manage automatically generating route configuration. Let's start the local website server:
+Since we're using [file-based routing](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing), we can use the website local development server to manage automatically generating route configuration.
+
+Let's start the local website server:
 
-<NxCommands commands={["serve-local website"]} />
+<NxCommands commands={["dev website"]} />
 
 :::tip
-We're using the `serve-local` target here, which also starts local servers for any APIs which have been connected with `connection`, and hot-reloads if your website, model, or backend changes! This allows us to test our API and website locally before we've even written any CDK code.
+We're using the `dev` target here, which also starts local servers for any APIs which have been connected with `connection`, and hot-reloads if your website, model, or backend changes! This allows us to test our API and website locally before we've even written any CDK code.
 :::
 
 You'll see some errors, but the local website server should start on port `4200`, as well as the local Smithy API server on port `3001`.

package/docs/snippets/pdk-migration/example/03-migrate-infra.mdx

@@ -46,7 +46,7 @@ Since the Nx Plugin for AWS uses [Checkov](https://www.checkov.io/) for security
 
 ```diff lang="ts"
 // constructs/database.ts
-+import { suppressRules } from ':shopping-list/common-constructs';
++import { suppressRules } from '@shopping-list/common-constructs';
 ...
 +suppressRules(
 +  this.shoppingListTable,
@@ -69,7 +69,7 @@ The `UserIdentity` construct can generally be swapped out without changes by adj
 
 ```diff lang="ts"
 -import { UserIdentity } from "@aws/pdk/identity";
-+import { UserIdentity } from ':shopping-list/common-constructs';
++import { UserIdentity } from '@shopping-list/common-constructs';
 ...
 const userIdentity = new UserIdentity(this, `${id}UserIdentity`);
 ```
@@ -93,7 +93,7 @@ Follow the below steps:
     ```diff lang="ts"
     // stacks/application-stack.ts
     -import { MyApi } from "../constructs/apis/myapi";
-    +import { Api } from ':shopping-list/common-constructs';
+    +import { Api } from '@shopping-list/common-constructs';
     ...
     -const myapi = new MyApi(this, "MyApi", {
     -  databaseConstruct,
@@ -139,7 +139,7 @@ Finally, we add the `Website` construct from `packages/common/constructs/src/app
 
 ```diff lang="ts"
 -import { Website } from "../constructs/websites/website";
-+import { Website } from ':shopping-list/common-constructs';
++import { Website } from '@shopping-list/common-constructs';
 ...
 -new Website(this, "Website", {
 -  userIdentity,

package/docs/snippets/pdk-migration/faq/type-safe-api.mdx

@@ -26,7 +26,7 @@ For Python, the [python-fastapi](https://openapi-generator.tech/docs/generators/
 
 ##### Client
 
-For TypeScript clients, you can use the <Link path="/guides/react-website">`ts#react-website` generator</Link> and <Link path="/guides/connection">`connection` generator</Link> with an example `ts#smithy-api` to see how clients are generated and integrated with a website. This configures build targets which generate clients by invoking our `open-api#ts-client` or `open-api#ts-hooks` generators. You can use these generators yourself by pointing them at your OpenAPI Specification.
+For TypeScript clients, you can use the <Link path="/guides/react-website">`ts#website` generator</Link> and <Link path="/guides/connection">`connection` generator</Link> with an example `ts#api` (with `framework` set to `smithy`) to see how clients are generated and integrated with a website. This configures build targets which generate clients by invoking our `open-api#ts-client` or `open-api#ts-hooks` generators. You can use these generators yourself by pointing them at your OpenAPI Specification.
 
 For other languages, you can also see if any of the generators from [OpenAPI Generator](https://openapi-generator.tech/docs/generators#client-generators) fit your needs.
 

package/docs/snippets/prerequisites.mdx

@@ -10,7 +10,8 @@ import Snippet from '@components/snippet.astro';
 
 ### Recommended
 
-- [Docker](https://www.docker.com/) is required for some generators. [Multi-platform builds](https://docs.docker.com/build/building/multi-platform/) must be set up.
+- [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](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).

package/docs/snippets/rdb/cluster-instances.mdx

@@ -9,7 +9,7 @@ Configure the writer and reader instances for your Aurora cluster.
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', {
   ...

package/docs/snippets/rdb/deletion-protection.mdx

@@ -13,7 +13,7 @@ You can disable deletion protection for environments where database deletion is
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', {
   ...

package/docs/snippets/rdb/deploying.mdx

@@ -12,7 +12,7 @@ The relational database generator creates CDK or Terraform infrastructure based
 The CDK construct is created in `common/constructs`. Example usage:
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {

package/docs/snippets/rdb/encryption-key-rotation.mdx

@@ -9,7 +9,7 @@ The KMS key used to encrypt the Aurora cluster and its credentials secret has au
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', {
   ...

package/docs/snippets/rdb/engine-version.mdx

@@ -15,7 +15,7 @@ The local database image is configured in the `localDev.image` field of the gene
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', {
   ...
@@ -41,7 +41,7 @@ module "my_database" {
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', {
   ...

package/docs/snippets/rdb/performance-insights.mdx

@@ -11,7 +11,7 @@ Disable log export per database if not required:
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', {
   ...

package/docs/snippets/rdb/rds-proxy.mdx

@@ -22,7 +22,7 @@ You can disable the RDS proxy as follows:
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', {
   ...

package/docs/snippets/rdb/removal-policy.mdx

@@ -12,7 +12,7 @@ When using `RemovalPolicy.DESTROY`, deletion protection must also be disabled be
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
 import { RemovalPolicy } from 'aws-cdk-lib';
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', {
   ...
@@ -24,7 +24,7 @@ For an ephemeral environment where the database should be deleted with the stack
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
 import { RemovalPolicy } from 'aws-cdk-lib';
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', {
   ...

package/docs/snippets/rdb/serverless-capacity.mdx

@@ -9,7 +9,7 @@ Control Aurora Serverless v2 scaling limits to match your workload.
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', {
   ...

package/docs/snippets/required-prerequisites.mdx

@@ -8,5 +8,4 @@ title: Required Prerequisites
   - verify by running `pnpm --version`, `yarn --version`, `bun --version` or `npm --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.0`
-  2. verify with `uv python list --only-installed`
-- [AWS Credentials](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) configured to your target AWS account (where your application will be deployed)
+  2. verify with `uv python list --only-installed`

package/generators.json

@@ -340,7 +340,7 @@
     "ts#sync": {
       "factory": "./src/ts/sync/generator",
       "schema": "./src/ts/sync/schema.json",
-      "description": "TypeScript path alias sync generator",
+      "description": "TypeScript path alias and local workspace dependency sync generator",
       "metric": "g29",
       "hidden": true
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "version": "1.0.0-rc.46",
+  "version": "1.0.0-rc.48",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",

package/src/preset/schema.json

@@ -37,6 +37,11 @@
       "enum": ["esm", "cjs"],
       "default": "esm"
     },
+    "catalog": {
+      "type": "boolean",
+      "description": "Whether generators record dependency versions in the package manager's catalog (pnpm/yarn/bun), keeping a single source of truth for versions. When false, dependencies are written directly to each project's package.json and keeping versions aligned is your responsibility.",
+      "default": true
+    },
     "preferInstallDependencies": {
       "type": "boolean",
       "description": "Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.",