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

package/docs/guides/docker-bundling.mdx

@@ -342,7 +342,7 @@ infra.asset -> ecr: cdk deploy\nbuilds + pushes
 
 ```ts
 import { DockerImageAsset, Platform } from 'aws-cdk-lib/aws-ecr-assets';
-import { findWorkspaceRoot } from ':my-scope/common-constructs';
+import { findWorkspaceRoot } from '@my-scope/common-constructs';
 import * as path from 'path';
 import * as url from 'url';
 
@@ -356,7 +356,7 @@ const image = new DockerImageAsset(this, 'MyImage', {
 });
 ```
 
-The `findWorkspaceRoot` helper is generated by the <Link path="/guides/typescript-infrastructure">`ts#infra`</Link> generator and exported from `:my-scope/common-constructs`. If you are not using shared constructs, you can hardcode the path to the `dist` directory relative to where `cdk` is invoked from — typically the workspace root — and omit the `findWorkspaceRoot` call entirely.
+The `findWorkspaceRoot` helper is generated by the <Link path="/guides/typescript-infrastructure">`ts#infra`</Link> generator and exported from `@my-scope/common-constructs`. If you are not using shared constructs, you can hardcode the path to the `dist` directory relative to where `cdk` is invoked from — typically the workspace root — and omit the `findWorkspaceRoot` call entirely.
 
 :::note[Running bundle before synth]
 CDK does not run the `bundle`/`docker` targets automatically — you must run `nx build my-project` (or wire the deploy target to depend on `build`) before `cdk deploy`. The generators that use this pattern declare `docker` and `bundle` as dependencies of `build` so this happens transparently.

package/docs/guides/fastapi.mdx

@@ -445,7 +445,7 @@ The FastAPI generator creates CDK or Terraform infrastructure as code based on y
 The CDK construct for deploying your API in the `common/constructs` folder. You can use this in a CDK application:
 
 ```ts {6-8}
-import { MyApi } from ':my-scope/common-constructs';
+import { MyApi } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -473,7 +473,7 @@ This sets up:
 If you selected to use `Cognito` authentication, you will need to supply the `identity` property to the API construct:
 
 ```ts {9}
-import { MyApi, UserIdentity } from ':my-scope/common-constructs';
+import { MyApi, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {

package/docs/guides/react-website-auth.mdx

@@ -149,7 +149,7 @@ You will need to add the user identity infrastructure to your stack, declaring i
 ```ts title="packages/infra/src/stacks/application-stack.ts" {3,9}
 import { Stack } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite, UserIdentity } from ':my-scope/common-constructs';
+import { MyWebsite, UserIdentity } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -218,7 +218,7 @@ In order to grant authenticated users access to perform certain actions, such as
 ```ts title="packages/infra/src/stacks/application-stack.ts" {12}
 import { Stack } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite, UserIdentity, MyApi } from ':my-scope/common-constructs';
+import { MyWebsite, UserIdentity, MyApi } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string) {

package/docs/guides/react-website.mdx

@@ -59,6 +59,7 @@ The generator will create the following project structure in the `<directory>/<n
   - tsconfig.json Base TypeScript configuration for source and tests
   - tsconfig.app.json TypeScript configuration for source code
   - tsconfig.spec.json TypeScript configuration for tests
+  - package.json Project manifest defining the project's package name and dependencies
 </FileTree>
 
 :::note[Without TanStack Router]
@@ -245,7 +246,7 @@ Your website CDK construct will deploy the `connection` namespace of the runtime
 ```ts title="packages/infra/src/stacks/application-stack.ts"
 import { Stack } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite, MyApi } from ':my-scope/common-constructs';
+import { MyWebsite, MyApi } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -427,7 +428,7 @@ You can use the CDK construct generated for you in `packages/common/constructs`
 ```ts title="packages/infra/src/stacks/application-stack.ts" {3, 9}
 import { Stack } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite } from ':my-scope/common-constructs';
+import { MyWebsite } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string) {

package/docs/guides/runtime-config.mdx

@@ -70,7 +70,7 @@ Generated constructs automatically write relevant configuration to the `connecti
 The `RuntimeConfig` CDK construct is a stage-scoped singleton. Use `set()` to write a key into a namespace:
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { RuntimeConfig } from ':my-scope/common-constructs';
+import { RuntimeConfig } from '@my-scope/common-constructs';
 
 const rc = RuntimeConfig.ensure(this);
 

package/docs/guides/trpc.mdx

@@ -66,6 +66,7 @@ The generator will create the following project structure in the `<directory>/<a
     - client
       - index.ts Type-safe client for machine-to-machine API calls
   - tsconfig.json TypeScript configuration
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
 
 </FileTree>
@@ -558,7 +559,7 @@ The CDK construct for deploying your API lives in the `common/constructs` folder
 
 <OptionFilter when={{ auth: ['iam', 'custom'] }} description="CDK usage for IAM or Custom authentication">
 ```ts {6-8}
-import { MyApi } from ':my-scope/common-constructs';
+import { MyApi } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -577,7 +578,7 @@ When using `Custom` auth, the construct creates a Lambda Authorizer internally f
 
 <OptionFilter when={{ auth: 'cognito' }} description="CDK usage with Cognito authentication — pass the identity construct">
 ```ts {6,9}
-import { MyApi, UserIdentity } from ':my-scope/common-constructs';
+import { MyApi, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -813,7 +814,7 @@ This will automatically reload when you make changes to your API.
 You can create a tRPC client to invoke your API in a type-safe manner. If you are calling your tRPC API from another backend, you can use the client in `src/client/index.ts`, for example:
 
 ```ts
-import { createMyApiClient } from ':my-scope/my-api';
+import { createMyApiClient } from '@my-scope/my-api';
 
 const client = createMyApiClient({ url: 'https://my-api-url.example.com/' });
 

package/docs/guides/ts-dynamodb.mdx

@@ -36,6 +36,7 @@ The generator creates the following project structure in the `<directory>/<name>
       - example.ts Example ElectroDB entity definition
       - index.ts Entity exports
   - config.json Table configuration including GSI definitions and local development settings
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
 </FileTree>
 
@@ -136,7 +137,7 @@ GSIs are defined in `config.json` at the project root under the `tableConfig.glo
 In any TypeScript project, import entity factories from your DynamoDB package and use them directly:
 
 ```ts
-import { createExampleEntity } from ':my-scope/my-table';
+import { createExampleEntity } from '@my-scope/my-table';
 
 const entity = await createExampleEntity();
 const result = await entity.query.primary({ id: '123' }).go();

package/docs/guides/ts-rdb.mdx

@@ -47,6 +47,7 @@ The generator will create the following project structure in the `<directory>/<n
   - .gitignore Git ignore entries including generated Prisma client output
   - config.json Local development connection details and runtime config key
   - Dockerfile Container image definition for the migration handler
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
   - prisma.config.ts Configuration for Prisma CLI
 </FileTree>
@@ -173,7 +174,7 @@ Replace `<engine>` with your container engine (`docker` or `finch`), `<scope>` w
 In any TypeScript project, import `getPrisma` from your database package and call it to get a type-safe Prisma client:
 
 ```ts
-import { getPrisma } from ':my-scope/db';
+import { getPrisma } from '@my-scope/db';
 
 const prisma = await getPrisma();
 const users = await prisma.user.findMany({ orderBy: { id: 'asc' } });
@@ -340,7 +341,7 @@ export const listExampleTable = publicProcedure
 If you are using the [middleware pattern](#injecting-the-prisma-client-via-middleware), add the `$disconnect()` call to the middleware so all procedures built on it are covered automatically:
 
 ```ts title="packages/api/src/middleware/db.ts"
-import { getPrisma } from ':my-scope/db';
+import { getPrisma } from '@my-scope/db';
 import { initTRPC } from '@trpc/server';
 
 export interface IDbContext {

package/docs/guides/ts-smithy-api.mdx

@@ -46,6 +46,7 @@ The generator creates two related projects in the `<directory>/<api-name>` direc
 <FileTree>
 
 - **model/** Smithy model project
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
   - smithy-build.json Smithy build configuration
   - build.Dockerfile Docker configuration for building Smithy artifacts
@@ -588,7 +589,7 @@ The generator creates CDK or Terraform infrastructure based on your selected `ia
 The CDK construct for deploying your API is in the `common/constructs` folder:
 
 ```ts {6-8}
-import { MyApi } from ':my-scope/common-constructs';
+import { MyApi } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -615,7 +616,7 @@ This sets up:
 If you selected `Cognito` authentication, you will need to supply the `identity` property to the API construct:
 
 ```ts {9}
-import { MyApi, UserIdentity } from ':my-scope/common-constructs';
+import { MyApi, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {

package/docs/guides/typescript-infrastructure.mdx

@@ -38,6 +38,7 @@ The generator will create the following project structure in the `<directory>/<n
     - stacks CDK Stack definitions
       - application-stack.ts Main application stack
   - cdk.json CDK configuration
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
   - checkov.yml Checkov configuration file
 
@@ -102,7 +103,7 @@ The `env` property tells CDK which AWS account and region to deploy to. `CDK_DEF
 If you generated with `stageConfig`, the `main.ts` reads account and region from a centralized config file instead, falling back to environment variables when no config is set:
 
 ```ts title="src/main.ts (with stageConfig)"
-import { resolveStage } from ':my-scope/common-infra-config';
+import { resolveStage } from '@my-scope/common-infra-config';
 
 // Looks up the stage under this project (packages/infra), falling back to
 // shared stages. Returns undefined when no config exists for the stage.
@@ -271,7 +272,7 @@ If, for example, you created a tRPC API called `my-api`, you can simply import a
 ```ts title="src/stacks/application-stack.ts" {3, 9-12}
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyApi } from ':my-scope/common-constructs';
+import { MyApi } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
@@ -292,7 +293,7 @@ If you have used the <Link path="guides/react-website">React Website</Link> gene
 ```ts title="src/stacks/application-stack.ts" {3, 9-10}
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite } from ':my-scope/common-constructs';
+import { MyWebsite } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
@@ -339,7 +340,7 @@ There may be instances where you want to suppress certain rules on resources. Yo
 #### Supress a rule on a given construct
 
 ```typescript
-import { suppressRules } from ':my-scope/common-constructs';
+import { suppressRules } from '@my-scope/common-constructs';
 
 // suppresses the CKV_AWS_XXX for the given construct.
 suppressRules(construct, ['CKV_AWS_XXX'], 'Reason');
@@ -348,7 +349,7 @@ suppressRules(construct, ['CKV_AWS_XXX'], 'Reason');
 #### Supress a rule on a descendant construct
 
 ```typescript
-import { suppressRules } from ':my-scope/common-constructs';
+import { suppressRules } from '@my-scope/common-constructs';
 
 // Supresses the CKV_AWS_XXX for the construct or any of its descendants if it is an instance of Bucket
 suppressRules(construct, ['CKV_AWS_XXX'], 'Reason', (construct) => construct instanceof Bucket);

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.
 
@@ -108,10 +113,12 @@ Run tests across all projects:
 
 ### Dev
 
-If you have a <Link path="guides/react-website">website</Link>, start it and all connected components locally:
+Start all local development servers across your workspace:
 
 <PackageManagerShortCommand commands={["dev"]} />
 
+See the <Link path="guides/local-development">Local Development</Link> guide for more details.
+
 ### Sync
 
 Run any [sync generators](https://nx.dev/concepts/sync-generators), which for example synchronise TypeScript project references (refer to the <Link path="guides/typescript-project">ts#project</Link> generator guide for more details):

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,