@aws/nx-plugin-mcp 1.0.0-rc.7 → 1.0.0-rc.71

package/docs/snippets/connection/rdb-api-infrastructure.mdx

@@ -2,6 +2,7 @@
 title: RDB API Infrastructure
 ---
 import Infrastructure from '@components/infrastructure.astro';
+import Link from '@components/link.astro';
 
 To allow your API to connect to the database at runtime, the API Lambda functions must be deployed into the same VPC as the database and granted network and IAM access.
 
@@ -11,7 +12,7 @@ To allow your API to connect to the database at runtime, the API Lambda function
 In your application stack, deploy the API into the same VPC as the database, then call `allowDefaultPortFrom` and `grantConnect` to open the network path and grant IAM `rds-db:connect` permission to each Lambda handler:
 
 ```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', { vpc, ... });
 
@@ -39,34 +40,65 @@ This example grants every handler in your API access, but if only some handlers
 </Fragment>
 <Fragment slot="terraform">
 
-Pass the database module outputs into your API module so it can reach the database and read its runtime configuration:
+Deploy the API into the same VPC as the database, grant it `rds-db:connect` via `additional_iam_policy_statements`, and open the network path with a pair of security group rules. The `aws_vpc.main` and `aws_subnet` resources are defined in the database deployment guide:
 
 ```hcl title="packages/infra/src/main.tf"
 module "my_database" {
   source              = "../../common/terraform/src/app/dbs/my-database"
-  vpc_id              = module.vpc.vpc_id
-  database_subnet_ids = module.vpc.private_isolated_subnet_ids
-  lambda_subnet_ids   = module.vpc.private_subnet_ids
+  vpc_id              = aws_vpc.main.id
+  database_subnet_ids = aws_subnet.database[*].id
+  lambda_subnet_ids   = aws_subnet.private[*].id
 }
 
 module "api" {
-  source             = "..."
-  vpc_id             = module.vpc.vpc_id
-  private_subnet_ids = module.vpc.private_subnet_ids
-
-  appconfig_application_id     = module.my_database.appconfig_application_id
-  database_cluster_resource_id = module.my_database.cluster_resource_id
-  database_runtime_user        = module.my_database.database_runtime_user
-  database_security_group_id   = module.my_database.security_group_id
-  database_port                = module.my_database.cluster_port
-
-  environment_variables = {
-    RUNTIME_CONFIG_APP_ID = module.my_database.appconfig_application_id
-  }
+  source     = "../../common/terraform/src/app/apis/my-api"
+  enable_vpc = true
+  vpc_id     = aws_vpc.main.id
+  subnet_ids = aws_subnet.private[*].id
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+
+  additional_iam_policy_statements = [
+    {
+      Effect = "Allow"
+      Action = ["rds-db:connect"]
+      Resource = [
+        "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${module.my_database.connect_resource_id}/${module.my_database.database_runtime_user}"
+      ]
+    }
+  ]
+}
+
+resource "aws_vpc_security_group_ingress_rule" "api_to_database" {
+  description                  = "Allow the API Lambda functions to connect to the database"
+  security_group_id            = module.my_database.security_group_id
+  referenced_security_group_id = module.api.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
+}
+
+resource "aws_vpc_security_group_egress_rule" "api_to_database" {
+  description                  = "Allow outbound traffic from the API Lambda functions to the database"
+  security_group_id            = module.api.security_group_id
+  referenced_security_group_id = module.my_database.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
 }
 ```
 
-Deploy the API Lambda functions into **private subnets with egress**, not private isolated subnets. Ensure the API Lambda role has `rds-db:connect` permission and that its security group can reach the database security group on the database port.
+Deploy the API Lambda functions into **private subnets with egress**, not private isolated subnets. `appconfig_application_id`/`appconfig_application_arn` come from the shared <Link path="guides/runtime-config">runtime configuration</Link> AppConfig application declared once in your root module, not from the database module — passing them sets `RUNTIME_CONFIG_APP_ID` on the Lambda functions and grants them read access to the application. Include the `database` namespace when instantiating it so the database module's runtime configuration entry is deployed:
+
+```hcl title="packages/infra/src/main.tf"
+module "runtime_config_appconfig" {
+  source = "../../common/terraform/src/core/runtime-config/appconfig"
+
+  application_name = "my-app-runtime-config"
+  namespaces       = ["connection", "agentcore", "database"]
+}
+```
 
 </Fragment>
 </Infrastructure>

package/docs/snippets/dynamodb/deploying-table.mdx

@@ -0,0 +1,166 @@
+---
+title: Deploying your DynamoDB Table
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+The DynamoDB generator creates CDK or Terraform infrastructure based on your selected `iac`.
+
+<Infrastructure>
+<Fragment slot="cdk">
+The CDK construct is created in `common/constructs`. Example usage:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyTable } from '@my-scope/common-constructs';
+
+export class ApplicationStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const table = new MyTable(this, 'Table');
+  }
+}
+```
+
+This provisions a DynamoDB table with:
+- `pk` (partition key) and `sk` (sort key), both `String` type
+- Global Secondary Indexes as defined in `config.json`
+- On-demand (`PAY_PER_REQUEST`) billing
+- Customer-managed KMS encryption with automatic key rotation
+- Point-in-time recovery enabled
+- Deletion protection enabled
+- Table name registered in Runtime Config under the `dynamodb` namespace in AWS AppConfig
+</Fragment>
+<Fragment slot="terraform">
+The Terraform module is created in `common/terraform`. Example usage:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source = "../../common/terraform/src/app/dynamodb/my-table"
+}
+```
+
+This provisions a DynamoDB table with:
+- `pk` (partition key) and `sk` (sort key), both `String` type
+- Global Secondary Indexes as defined in `config.json`
+- On-demand (`PAY_PER_REQUEST`) billing
+- Customer-managed KMS encryption with automatic key rotation
+- Point-in-time recovery enabled
+- Deletion protection enabled
+- Table name registered in Runtime Config
+</Fragment>
+</Infrastructure>
+
+### Deletion Protection
+
+Deletion protection is enabled by default to prevent accidental table deletion.
+
+#### Disable Deletion Protection
+
+Disable it for environments where table deletion is expected, such as short-lived development or preview stacks.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table', {
+  deletionProtection: false,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source                      = "../../common/terraform/src/app/dynamodb/my-table"
+  deletion_protection_enabled = false
+}
+```
+</Fragment>
+</Infrastructure>
+
+### Billing Mode
+
+The table defaults to on-demand (`PAY_PER_REQUEST`) billing. Switch to provisioned capacity for predictable, high-throughput workloads.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { BillingMode } from 'aws-cdk-lib/aws-dynamodb';
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table', {
+  billingMode: BillingMode.PROVISIONED,
+  readCapacity: 5,
+  writeCapacity: 5,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source       = "../../common/terraform/src/app/dynamodb/my-table"
+  billing_mode = "PROVISIONED"
+}
+```
+</Fragment>
+</Infrastructure>
+
+### Point-in-time Recovery
+
+[Point-in-time recovery](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Point-in-time-recovery.html) is enabled by default, allowing you to restore the table to any point in the last 35 days.
+
+#### Disable Point-in-time Recovery
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table', {
+  pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: false },
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source                         = "../../common/terraform/src/app/dynamodb/my-table"
+  point_in_time_recovery_enabled = false
+}
+```
+</Fragment>
+</Infrastructure>
+
+### Encryption Key Rotation
+
+The KMS key used to encrypt the table has automatic key rotation enabled by default. Disable it if your security policy manages rotation externally.
+
+#### Disable Encryption Key Rotation
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table', {
+  enableKeyRotation: false,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source              = "../../common/terraform/src/app/dynamodb/my-table"
+  enable_key_rotation = false
+}
+```
+</Fragment>
+</Infrastructure>

package/docs/snippets/dynamodb/gsi-config.mdx

@@ -0,0 +1,38 @@
+---
+title: GSI Configuration
+---
+
+```json title="config.json"
+{
+  ...
+  "tableConfig": {
+    "globalSecondaryIndexes": [
+      {
+        "indexName": "gsi1pk-gsi1sk-index",
+        "partitionKey": "gsi1pk",
+        "sortKey": "gsi1sk"
+      },
+      {
+        "indexName": "gsi2pk-gsi2sk-index",
+        "partitionKey": "gsi2pk",
+        "sortKey": "gsi2sk"
+      }
+    ]
+  }
+}
+```
+
+The `sortKey` field is optional for hash-key-only GSIs.
+
+This config file is the single source of truth read by all consumers:
+- **Local development** — `dev` reads `config.json` and creates or updates the local table to match the GSI list
+- **CDK** — the construct reads `config.json` at synth time, so GSI changes are reflected on the next `cdk deploy`
+- **Terraform** — the module reads `config.json` at plan/apply time
+
+### One GSI per Deployment
+
+:::caution
+DynamoDB [does not allow more than one GSI to be created or deleted in a single table update](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.OnlineOps.html).
+
+Each deployment can add or remove **at most one GSI**. If you need to add or remove multiple GSIs, do so one at a time — update `config.json` and relevant entity classes, deploy the stack, then repeat for the next change.
+:::

package/docs/snippets/dynamodb/infrastructure.mdx

@@ -0,0 +1,33 @@
+---
+title: DynamoDB Infrastructure
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+
+<Snippet name="shared-constructs" />
+
+<Infrastructure>
+  <Fragment slot="cdk">
+    <FileTree>
+      - packages/common/constructs/src
+        - app
+          - dynamodb
+            - \<name>.ts Infrastructure specific to your table
+        - core
+          - dynamodb.ts Generic DynamoDB table construct
+    </FileTree>
+  </Fragment>
+  <Fragment slot="terraform">
+    <FileTree>
+      - packages/common/terraform/src
+        - app
+          - dynamodb
+            - \<name>
+              - \<name>.tf Module specific to your table
+        - core
+          - dynamodb
+            - dynamodb.tf Generic DynamoDB module
+    </FileTree>
+  </Fragment>
+</Infrastructure>

package/docs/snippets/dynamodb/local-dev-start.mdx

@@ -0,0 +1,13 @@
+---
+title: Starting Local DynamoDB
+---
+import NxCommands from '@components/nx-commands.astro';
+
+The generator configures a `dev` target that starts a [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html) instance and creates the table. Use the project's `dev` target:
+
+<NxCommands commands={['dev <project-name>']} />
+
+This automatically:
+1. Pulls the DynamoDB Local image (`pull-image` target)
+2. Starts a container
+3. Creates a local table with the indexes defined in `config.json`

package/docs/snippets/dynamodb/local-dev-windows.mdx

@@ -0,0 +1,15 @@
+---
+title: Local Development Windows Caution
+---
+
+Stopping `dev` (e.g. with `Ctrl+C`) automatically removes the DynamoDB Local container, but preserves the named volume so your data persists across restarts.
+
+:::caution[Windows]
+Due to limitations with signal handling on Windows, the container is not automatically removed when `dev` is stopped. You will need to remove it manually:
+
+```bash
+<engine> rm -f <scope>-dynamodb
+```
+
+Replace `<engine>` with your container engine (`docker` or `finch`) and `<scope>` with your Nx workspace scope (e.g. `proj`).
+:::

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

@@ -3,14 +3,14 @@ title: Deploying your Function
 ---
 import Infrastructure from '@components/infrastructure.astro';
 
-This generator creates CDK or Terraform infrastructure as code based on your selected `iacProvider`. You can use this to deploy your function.
+This generator creates CDK or Terraform infrastructure as code based on your selected `iac`. You can use this to deploy your function.
 
 <Infrastructure>
 <Fragment slot="cdk">
 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/architecture.mdx

@@ -23,7 +23,7 @@ ecr: ECR {
 
 agentcore: MCP Server\n(AgentCore Runtime) {
   shape: image
-  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore.svg
+  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore-runtime.svg
 }
 
 cw: CloudWatch\n(Logs, Metrics) {

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) {
@@ -144,7 +144,7 @@ The `UserIdentity` construct can be generated using the <Link path="/guides/reac
 <Fragment slot="terraform">
 The generated module accepts `user_pool_id` and `user_pool_client_ids` variables for Cognito authentication:
 
-```terraform {8-9}
+```terraform {11-12}
 module "user_identity" {
   source = "../../common/terraform/src/core/user-identity"
 }
@@ -164,4 +164,8 @@ module "my_project_mcp_server" {
 
 :::note[Custom OIDC Providers]
 If you require custom JWT authentication with a non-Cognito OIDC provider, you can modify the generated CDK construct or Terraform module for your MCP server directly. Note that the connection generator will only support `IAM` or `Cognito` authentication.
+:::
+
+:::caution[Security Best Practices]
+When implementing your MCP server's business logic, review the [Bedrock AgentCore Runtime security best practices](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-security-best-practices.html).
 :::

package/docs/snippets/mcp/config.mdx

@@ -1,13 +1,14 @@
 ---
 title: MCP Server Configuration
 ---
+
 ```json {3-6}
 {
   "mcpServers": {
     "nx-plugin-for-aws": {
       "command": "npx",
-      "args": ["-y", "@aws/nx-plugin-mcp@next"]
+      "args": ["-y", "@aws/nx-plugin-mcp"]
     }
   }
 }
-```
+```

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,