@aws/nx-plugin-mcp 1.0.0-rc.45 → 1.0.0-rc.47

package/docs/guides/typescript-project.mdx

@@ -3,12 +3,13 @@ title: TypeScript Projects
 description: Reference documentation for TypeScript projects
 generator: ts#project
 ---
-import { FileTree } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem, Steps } from '@astrojs/starlight/components';
 import RunGenerator from '@components/run-generator.astro';
 import InstallCommand from '@components/install-command.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
 import NxCommands from '@components/nx-commands.astro';
 import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
 import Link from '@components/link.astro';
 
 The TypeScript project generator can be used to create a modern [TypeScript](https://www.typescriptlang.org/) library or application configured with best practices such as [ECMAScript Modules (ESM)](https://www.typescriptlang.org/docs/handbook/modules/reference.html), TypeScript [project references](https://www.typescriptlang.org/docs/handbook/project-references.html), [Vitest](https://vitest.dev/) for running tests and [Biome](https://biomejs.dev/) for linting and formatting.
@@ -33,6 +34,7 @@ The generator will create the following project structure in the `<directory>/<n
 
   - src TypeScript source code
     - index.ts
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
   - tsconfig.json Base TypeScript configuration for this project (extends workspace root tsconfig.base.json)
   - tsconfig.lib.json TypeScript configuration for your library (your runtime or packaged source)
@@ -41,8 +43,8 @@ The generator will create the following project structure in the `<directory>/<n
 
 </FileTree>
 
-:::tip[No package.json Needed]
-Notice that no `package.json` file is created for this project! You can find out why [below](#dependencies).
+:::tip[Project package.json]
+The project's `package.json` starts minimal. As you add runtime dependencies they are declared here (shared build/test tooling stays in the workspace root) — you can find out more [below](#dependencies).
 :::
 
 You will also notice some changes to the following files in your workspace root:
@@ -85,13 +87,9 @@ export * from './algorithms/index.js';
 [TypeScript aliases](https://www.typescriptlang.org/docs/handbook/modules/reference.html#paths) for your project are configured in your workspace `tsconfig.base.json`, which allows you to reference your TypeScript project from other TypeScript projects:
 
 ```ts title="packages/my-other-project/src/index.ts"
-import { sayHello } from ':my-scope/my-library';
+import { sayHello } from '@my-scope/my-library';
 ```
 
-:::note[Project Aliases]
-Aliases for your TypeScript projects begin with a `:` rather than the traditional `@`, since this avoids the possibility of name conflicts between local packages in your workspace and remote packages in [NPM](https://www.npmjs.com/).
-:::
-
 When you add an import statement for a new project in your workspace for the first time, you will likely see an error in your IDE similar to the below:
 
 <details>
@@ -106,28 +104,40 @@ File '/path/to/my/workspace/packages/my-library/src/index.ts' is not listed with
 
 </details>
 
-This is because a [project reference](https://www.typescriptlang.org/docs/handbook/project-references.html) has not yet been set up.
+This is because a [project reference](https://www.typescriptlang.org/docs/handbook/project-references.html) has not yet been set up, and the imported project has not yet been declared as a workspace dependency in your project's `package.json`.
 
-TypeScript projects are configured with the Nx TypeScript Sync generator out of the box, saving you from needing to manually configure the project reference. Simply run the following command and Nx will add the required configuration:
+Your workspace is configured with sync generators which manage both for you, so you don't need to configure them by hand. Simply run the following command and Nx will add the required configuration:
 
 <NxCommands commands={['sync']} />
 
-After this, the error in your IDE should be gone and you are ready to use your library.
+```bash wrap
+ NX   The workspace is out of sync
+
+[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on, contain stale project references, or have duplicate project references.
+[@aws/nx-plugin:ts#sync]: Local project dependencies are out of sync. The following workspace dependencies will be declared:
+packages/my-other-project/package.json:
+- @my-scope/my-library: workspace:*
+
+Syncing the workspace...
+The workspace was synced successfully!
+```
+
+Nx's TypeScript sync generator adds the project reference, and the plugin's `ts#sync` generator declares the imported project in your project's `package.json` (`workspace:*` where the package manager supports the workspace protocol, `*` on npm and yarn classic), so the package manager links the local project on install. After this, the error in your IDE should be gone and you are ready to use your library.
 
 :::tip[Build Shortcut]
-You can also just build your project and you'll be prompted with a message such as:
+You can also just build your project — the sync generators run first and you'll be prompted to apply any outstanding changes:
 
 ```bash wrap
-[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on or contain outdated project references.
+ NX   The workspace is out of sync
 
-This will result in an error in CI.
+...
 
-? Would you like to sync the identified changes to get your workspace up to date?
+? Would you like to sync the identified changes to get your workspace up to date? …
 Yes, sync the changes and run the tasks
 No, run the tasks without syncing the changes
 ```
 
-Select `Yes` to allow Nx to update your project references.
+Select `Yes` to allow Nx to sync your workspace.
 :::
 
 ### Keeping Path Aliases In Sync
@@ -136,13 +146,116 @@ If you add custom `compilerOptions.paths` entries in a project's `tsconfig.json`
 
 ### Dependencies
 
-You will notice that your TypeScript project does not have a `package.json` file, which might be unexpected if you are used to traditional TypeScript monorepos.
+Each TypeScript project declares its third-party runtime dependencies in its own `package.json`. Build and test tooling shared across projects is defined in the root `package.json`.
+
+To add a runtime dependency to a project, install it into that project:
+
+<InstallCommand pkg="some-npm-package" project="@my-scope/my-library" />
+
+You can also run your package manager's plain `add`/`install` command from within the project's directory.
+
+To add a shared dev tool, install it at the workspace root:
+
+<InstallCommand pkg="some-dev-tool" dev />
+
+:::note
+Biome's [`noUndeclaredDependencies`](https://biomejs.dev/linter/rules/no-undeclared-dependencies/) lint rule enforces that a project's source only imports packages declared in its own `package.json`. Config files, build scripts and tests are exempt, so shared tooling can stay at the root.
+:::
+
+#### Catalogs
+
+For package managers which support catalogs ([pnpm](https://pnpm.io/catalogs), [yarn](https://yarnpkg.com/features/catalogs) and [bun](https://bun.com/docs/install/catalogs)), generators record each version in the catalog and reference it with the `catalog:` protocol (eg `"zod": "catalog:"`), so the catalog is the single source of truth for versions regardless of which project declares the dependency. This helps you to follow a [single version policy](https://nx.dev/concepts/decisions/dependency-management#single-version-policy), avoiding type conflicts and multiple copies of packages in deployment bundles.
+
+When you add a new dependency yourself, keep it in the catalog too:
+
+<Tabs syncKey="package-manager">
+  <TabItem label="pnpm">
+    The workspace sets [`catalogMode: strict`](https://pnpm.io/settings#catalogmode), so `pnpm add` records the version in the catalog and references it automatically — no extra steps.
+
+    ```bash
+    pnpm add some-npm-package --filter my-library
+    ```
+  </TabItem>
+  <TabItem label="yarn">
+    yarn's `catalog:` protocol only *references* an existing catalog entry — it cannot create one — so record the version first.
+
+    <Steps>
+    1. Add the version under `catalog` in `.yarnrc.yml`:
+
+       ```yaml title=".yarnrc.yml"
+       catalog:
+         some-npm-package: ^1.0.0
+       ```
+
+    2. Reference it from the project:
+
+       ```bash
+       yarn workspace @my-scope/my-library add some-npm-package@catalog:
+       ```
+    </Steps>
+  </TabItem>
+  <TabItem label="bun">
+    bun's `catalog:` protocol only *references* an existing catalog entry — it cannot create one — so record the version first.
 
-To add a dependency for any TypeScript package in your monorepo, simply add the dependency to the `package.json` in the root of your workspace. You can do this via the command line for your package manager:
+    <Steps>
+    1. Add the version under `catalog` in the root `package.json`:
 
-<InstallCommand pkg="some-npm-package" />
+       ```json title="package.json"
+       {
+         "catalog": {
+           "some-npm-package": "^1.0.0"
+         }
+       }
+       ```
 
-The dependency is then available for any of the TypeScript projects in your workspace to use.
+    2. Reference it from the project:
+
+       ```bash
+       bun add some-npm-package@catalog: --cwd packages/my-library
+       ```
+    </Steps>
+  </TabItem>
+</Tabs>
+
+:::tip[Aligning versions on npm]
+npm has no catalog feature, so versions are declared directly in each `package.json`. To keep them consistent across projects, we recommend [syncpack](https://github.com/JamieMason/syncpack) (`npx syncpack lint`).
+:::
+
+##### Opting out of catalogs
+
+Catalogs are enabled by default. To turn them off, create your workspace with `--catalog false`:
+
+<CreateNxWorkspaceCommand workspace="my-project" extraArgs="--catalog false" />
+
+Or set it in `aws-nx-plugin.config.mts` at any time:
+
+```ts title="aws-nx-plugin.config.mts"
+export default {
+  packageManager: {
+    catalogs: false,
+  },
+} satisfies AwsNxPluginConfig;
+```
+
+With catalogs disabled, generators write dependency versions directly into each project's `package.json`, and keeping versions aligned across projects is your responsibility.
+
+#### Declaring all dependencies at the root
+
+If you prefer declaring every dependency in the root `package.json` only (no per-project dependency declarations), turn off the lint rule in the workspace `biome.json`:
+
+```json title="biome.json"
+{
+  "linter": {
+    "rules": {
+      "correctness": {
+        "noUndeclaredDependencies": "off"
+      }
+    }
+  }
+}
+```
+
+Projects resolve root-installed packages at build time, so everything still builds — you give up per-project manifests as an accurate record of each project's dependencies (which matters if you later publish a project or split the repo).
 
 #### Runtime Code
 
@@ -193,12 +306,6 @@ Note that in the above target, we chose `src/index.ts` as our entrypoint for the
 If you're building an AWS Lambda function, check out the <Link path="/guides/ts-lambda-function">`ts#lambda-function`</Link> generator as this configures bundling for you, as well as generating infrastructure and adding observability and type-safety.
 :::
 
-#### Publishing to NPM
-
-If you are publishing your TypeScript project to NPM, you must create a `package.json` file for it.
-
-This must declare the dependencies that your project references. Since at build time your project will resolve dependencies installed via the workspace root `package.json`, Biome's `noUndeclaredDependencies` rule will warn you if your project imports a package that isn't listed in its `package.json`.
-
 ### Building
 
 Your TypeScript project is configured with a `build` target (defined in `project.json`), which you can run via:

package/docs/guides/workspace.mdx

@@ -6,6 +6,7 @@ import { FileTree } from '@astrojs/starlight/components';
 import Link from '@components/link.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 NxCommands from '@components/nx-commands.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
 
@@ -82,7 +83,11 @@ The default monorepo setup uses a [single version policy](https://nx.dev/concept
 
 This means that all projects within your monorepo use the same version of dependencies by default, reducing issues related to packages in the same monorepo running into version mismatch issues.
 
-From a Node perspective this means a single lockfile at the root with a single `node_modules` containing all dependencies. If you need to add a new dependency, add it in the root `package.json`.
+From a Node perspective this means a single lockfile at the root, with dependencies installed once and linked into each project. Each Node project declares the runtime dependencies its source imports in its own `package.json`, while shared build/test tooling lives in the root `package.json` `devDependencies`. Add a project's runtime dependency by installing it into that project:
+
+<InstallCommand pkg="some-npm-package" project="@my-scope/my-project" />
+
+For package managers with catalog support ([pnpm](https://pnpm.io/catalogs), [yarn](https://yarnpkg.com/features/catalogs) and [bun](https://bun.com/docs/install/catalogs)), dependency versions are recorded in the catalog and referenced with the `catalog:` protocol, keeping a single source of truth for versions across every project's `package.json`. For npm workspaces, we recommend [syncpack](https://github.com/JamieMason/syncpack) to align versions declared across multiple `package.json` files.
 
 From a Python perspective, this means a single `.venv` in the root of the monorepo with all dependencies installed into it. Each Python project has its own `pyproject.toml`, but the versions of those dependencies are managed by the UV workspace and subsequently written out to the `uv.lock` file in the root.
 

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

@@ -15,7 +15,7 @@ A CDK construct is generated for your agent, named based on the `name` you chose
 You can use this CDK construct in a CDK application:
 
 ```ts
-import { MyProjectAgent } from ':my-scope/common-constructs';
+import { MyProjectAgent } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -69,7 +69,7 @@ By default, your Agent will be secured using IAM authentication, simply deploy i
 <Infrastructure>
 <Fragment slot="cdk">
 ```ts {5}
-import { MyProjectAgent } from ':my-scope/common-constructs';
+import { MyProjectAgent } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -81,7 +81,7 @@ export class ExampleStack extends Stack {
 You can grant access to invoke your agent on Bedrock AgentCore Runtime using the `grantInvokeAccess` method, for example:
 
 ```ts {8}
-import { MyProjectAgent } from ':my-scope/common-constructs';
+import { MyProjectAgent } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -131,7 +131,7 @@ When you select `Cognito` authentication, the generator configures the agent to
 The generated construct accepts an `identity` prop which configures Cognito authentication:
 
 ```ts {8}
-import { MyProjectAgent, UserIdentity } from ':my-scope/common-constructs';
+import { MyProjectAgent, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {

package/docs/snippets/agent/runtime-arn.mdx

@@ -12,7 +12,7 @@ You can obtain the runtime ARN from your infrastructure as follows:
 <Fragment slot="cdk">
 ```ts {9}
 import { CfnOutput } from 'aws-cdk-lib';
-import { MyProjectAgent } from ':my-scope/common-constructs';
+import { MyProjectAgent } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {

package/docs/snippets/api/cors-configuration-cdk-note.mdx

@@ -8,7 +8,7 @@ If your solution includes a website you can configure its CloudFront distributio
 You can call the API `restrictCorsTo` method with website constructs, CloudFront distributions, origin strings, or a mix of them.
 
 ```ts
-import { MyApi, MyWebsite } from ':my-scope/common-constructs';
+import { MyApi, MyWebsite } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {

package/docs/snippets/connection/lambda-dynamodb-access.mdx

@@ -11,7 +11,7 @@ To allow Lambda functions to access the DynamoDB table, grant the necessary perm
 Call `grantReadWriteData` on the table construct. This grants both the DynamoDB and KMS permissions required by the Lambda execution role:
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyTable } from ':my-scope/common-constructs';
+import { MyTable } from '@my-scope/common-constructs';
 
 const table = new MyTable(this, 'Table');
 

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

@@ -12,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, ... });
 

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

@@ -10,7 +10,7 @@ The DynamoDB generator creates CDK or Terraform infrastructure based on your sel
 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';
+import { MyTable } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
@@ -62,7 +62,7 @@ Disable it for environments where table deletion is expected, such as short-live
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyTable } from ':my-scope/common-constructs';
+import { MyTable } from '@my-scope/common-constructs';
 
 const table = new MyTable(this, 'Table', {
   deletionProtection: false,
@@ -89,7 +89,7 @@ The table defaults to on-demand (`PAY_PER_REQUEST`) billing. Switch to provision
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
 import { BillingMode } from 'aws-cdk-lib/aws-dynamodb';
-import { MyTable } from ':my-scope/common-constructs';
+import { MyTable } from '@my-scope/common-constructs';
 
 const table = new MyTable(this, 'Table', {
   billingMode: BillingMode.PROVISIONED,
@@ -119,7 +119,7 @@ module "my_table" {
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyTable } from ':my-scope/common-constructs';
+import { MyTable } from '@my-scope/common-constructs';
 
 const table = new MyTable(this, 'Table', {
   pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: false },
@@ -147,7 +147,7 @@ The KMS key used to encrypt the table has automatic key rotation enabled by defa
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyTable } from ':my-scope/common-constructs';
+import { MyTable } from '@my-scope/common-constructs';
 
 const table = new MyTable(this, 'Table', {
   enableKeyRotation: false,

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/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', {
   ...