@aws/nx-plugin-mcp 1.0.0-rc.8 → 1.0.0-rc.80

package/docs/guides/docker-bundling.mdx

@@ -3,15 +3,40 @@ title: Docker Bundling
 description: Build and deploy Docker images for TypeScript and Python projects in an Nx Plugin for AWS workspace.
 ---
 
-import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem, Code } from '@astrojs/starlight/components';
 import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
 import Link from '@components/link.astro';
 import Infrastructure from '@components/infrastructure.astro';
+import TrivyVersion from '@components/trivy-version.astro';
+import { CONTAINER_VERSIONS } from '../../../../../../packages/nx-plugin/src/utils/versions';
 
-Several generators (such as <Link path="/guides/ts-agent">`ts#agent`</Link> and <Link path="/guides/py-agent">`py#agent`</Link>) produce a Docker image that is pushed to Amazon ECR and consumed by AWS infrastructure. This guide describes the pattern they follow so that you can apply it to other use cases — for example, running a <Link path="/guides/fastapi">`py#fast-api`</Link> project on Amazon ECS, or deploying a containerised Express server.
+export const trivyTarget = `{
+  "targets": {
+    "trivy": {
+      "cache": true,
+      "inputs": ["default", "^production"],
+      "outputs": ["{workspaceRoot}/dist/{projectRoot}/trivy"],
+      "executor": "nx:run-commands",
+      "options": {
+        "commands": [
+          "rimraf dist/packages/my-project/trivy",
+          "make-dir dist/packages/my-project/trivy",
+          "ncp packages/my-project/.trivyignore dist/packages/my-project/trivy/.trivyignore",
+          "docker save -o dist/packages/my-project/trivy/image.tar my-scope-my-project:latest",
+          "docker run --rm -v \\"./dist/packages/my-project/trivy\\":/scan public.ecr.aws/aquasecurity/trivy:${CONTAINER_VERSIONS.trivy} image --input /scan/image.tar --ignorefile /scan/.trivyignore --scanners vuln --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 --no-progress -q"
+        ],
+        "parallel": false
+      },
+      "dependsOn": ["docker"]
+    }
+  }
+}`;
+
+Several generators (such as <Link path="/guides/ts-agent">`ts#agent`</Link> and <Link path="/guides/py-agent">`py#agent`</Link>) produce a Docker image that is pushed to Amazon ECR and consumed by AWS infrastructure. This guide describes the pattern they follow so that you can apply it to other use cases — for example, running a <Link path="/guides/fastapi">FastAPI</Link> project on Amazon ECS, or deploying a containerised Express server.
 
 :::tip[Docker or Finch]
-The container engine used to build images is chosen at workspace creation time via the `--containerEngine` flag (`docker`, `finch`, or `infer` — the default — which auto-detects what's installed). [Finch](https://runfinch.com/) is an open-source, drop-in alternative to Docker. The selection is recorded in `aws-nx-plugin.config.mts` and applied to every generator that emits container build commands. CDK image asset builds honour the choice via the `CDK_DOCKER` environment variable.
+The container engine used to build images is chosen at workspace creation time via the `--containers` flag (`docker`, `finch`, or `infer` — the default — which auto-detects what's installed). [Finch](https://runfinch.com/) is an open-source, drop-in alternative to Docker. The selection is recorded in `aws-nx-plugin.config.mts` and applied to every generator that emits container build commands. CDK image asset builds honour the choice via the `CDK_DOCKER` environment variable.
 :::
 
 ## The Pattern
@@ -84,7 +109,7 @@ export default defineConfig([
     output: {
       file: '../../dist/packages/my-project/bundle/index.js',
       format: 'cjs',
-      inlineDynamicImports: true,
+      codeSplitting: false,
     },
     platform: 'node',
   },
@@ -253,6 +278,44 @@ This clears the output directory, then copies both the bundle contents and the `
 
 <NxCommands commands={['docker my-project']} />
 
+## Scanning Images with Trivy
+
+It's good practice to scan your images for known vulnerabilities. The generators that follow this pattern add a `trivy` target which scans the built image with [Trivy](https://trivy.dev/), running from the [ECR-hosted Trivy image](https://gallery.ecr.aws/aquasecurity/trivy), and exits non-zero on `HIGH` or `CRITICAL` findings.
+
+Add a `trivy` target which `dependsOn` your `docker` target. It saves the built image to a tarball and scans it via a workspace-relative bind mount, so the same command works under both `docker` and `finch`:
+
+<Code lang="json" code={trivyTarget} />
+
+Each project's per-image scan targets are aggregated under a workspace-wide `trivy` target, which the vended `trivy` root script runs (`nx run-many --target trivy`).
+
+<PackageManagerShortCommand commands={['trivy']} />
+
+:::tip[Run Trivy in CI]
+The scan is intentionally not wired into `build` since this can introduce unnecessary friction when iterating during development, as Trivy's vulnerabilty database is continually updated with new CVEs.
+
+Instead we recommend running the above command as a dedicated step in your CI pipeline prior to deployment to production stages.
+:::
+
+:::tip[Caching skips unchanged images]
+Because the image is fully determined by your project source, declaring `inputs` (here `default` and `^production`, matching the `bundle` target) lets Nx cache the scan and skip re-scanning an image that hasn't changed. Pin the Trivy image version (e.g. <code>trivy:<TrivyVersion /></code>) so scans are reproducible.
+:::
+
+:::note[Suppressing findings]
+Trivy reads a `.trivyignore` file (a list of vulnerability IDs, one per line) from the root of your project. `--ignore-unfixed` skips vulnerabilities with no available fix, so the scan only fails on issues you can action by upgrading tooling in your `Dockerfile`. See the [Trivy filtering documentation](https://trivy.dev/latest/docs/configuration/filtering/#by-finding-ids) for details.
+:::
+
+:::tip[Apply the distribution's security updates]
+A base image tag lags behind its distribution's security suite, so its OS packages carry vulnerabilities that already have a published fix. Upgrade them as the first step of your build, ahead of any other instruction so later layers install against the upgraded packages. For a Debian-derived base image (as used by the Node and Python images above):
+
+```dockerfile
+RUN apt-get update && \
+    apt-get upgrade -y --no-install-recommends && \
+    rm -rf /var/lib/apt/lists/*
+```
+
+The generated `Dockerfile`s do this for you.
+:::
+
 ## Infrastructure
 
 Wiring the resulting build-context directory to infrastructure as code is the same for both TypeScript and Python — only the path to the build-context directory differs (`dist/packages/my-project/bundle` for TypeScript, `dist/packages/my-project/docker` for Python).
@@ -291,7 +354,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';
 
@@ -305,7 +368,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.
@@ -318,8 +381,8 @@ Terraform's AWS provider does not have a first-class "build and push a Docker im
 
 1. The project's `build` target runs `docker build`, producing a local image tagged `my-scope-my-project:latest`.
 2. An `aws_ecr_repository` to hold the image.
-3. A `null_resource` with a `local-exec` provisioner that authenticates to ECR, re-tags the locally-built image, and pushes it.
-4. The downstream resource (e.g. `aws_ecs_task_definition`) references `"${aws_ecr_repository.repo.repository_url}:latest"`.
+3. A `null_resource` with a `local-exec` provisioner that authenticates to ECR, re-tags the locally-built image with its content digest, and pushes it.
+4. The downstream resource (e.g. `aws_ecs_task_definition`) references the image by its immutable, digest-based tag.
 
 ```d2
 direction: down
@@ -361,7 +424,7 @@ infra.repo -> ecr
 ```hcl
 resource "aws_ecr_repository" "repo" {
   name                 = "my-project-repository"
-  image_tag_mutability = "MUTABLE"
+  image_tag_mutability = "IMMUTABLE"
   force_delete         = true
 }
 
@@ -370,24 +433,30 @@ data "external" "docker_digest" {
   program = ["sh", "-c", "echo '{\"digest\":\"'$(docker inspect my-scope-my-project:latest --format '{{.Id}}')'\"}'"]
 }
 
+locals {
+  # Content-based, immutable image tag derived from the local image digest
+  image_tag = replace(data.external.docker_digest.result.digest, "sha256:", "")
+}
+
 resource "null_resource" "docker_publish" {
   triggers = {
     docker_digest  = data.external.docker_digest.result.digest
     repository_url = aws_ecr_repository.repo.repository_url
+    image_tag      = local.image_tag
   }
 
   provisioner "local-exec" {
     command = <<-EOT
       aws ecr get-login-password --region ${data.aws_region.current.id} \
         | docker login --username AWS --password-stdin ${self.triggers.repository_url}
-      docker tag my-scope-my-project:latest ${self.triggers.repository_url}:latest
-      docker push ${self.triggers.repository_url}:latest
+      docker tag my-scope-my-project:latest ${self.triggers.repository_url}:${self.triggers.image_tag}
+      docker push ${self.triggers.repository_url}:${self.triggers.image_tag}
     EOT
   }
 }
 ```
 
-The `data.external.docker_digest` block ensures the `null_resource` re-runs whenever the local image hash changes, triggering a new push on every meaningful code change.
+The `data.external.docker_digest` block ensures the `null_resource` re-runs whenever the local image hash changes, triggering a new push on every meaningful code change. The image is pushed under an immutable, content-based tag derived from its digest, so the ECR repository can use `IMMUTABLE` tag mutability and reject any attempt to overwrite an existing tag.
 
 :::note[Running bundle before apply]
 `nx apply <project>` requires the image tag `my-scope-my-project:latest` to already exist locally. Run `nx build my-project` (or `nx docker my-project`) before `nx apply <project>`.

package/docs/guides/fastapi.mdx

@@ -1,12 +1,14 @@
 ---
 title: FastAPI
 description: Reference documentation for FastAPI
-generator: py#fast-api
+generator: py#api
 when:
   framework: [fastapi]
 ---
 
-import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem, CardGrid } from '@astrojs/starlight/components';
+import Astro from '@astrojs/react';
+import ConnectionCard from '@components/connection-card.astro';
 import Link from '@components/link.astro';
 import RunGenerator from '@components/run-generator.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
@@ -26,11 +28,11 @@ The FastAPI generator creates a new FastAPI with AWS CDK or Terraform infrastruc
 
 You can generate a new FastAPI in two ways:
 
-<RunGenerator generator="py#fast-api" />
+<RunGenerator generator="py#api" requiredParameters={{ framework: 'fastapi' }} />
 
 ### Options
 
-<GeneratorParameters generator="py#fast-api" />
+<GeneratorParameters generator="py#api" />
 
 <Snippet name="api/api-choice-note" />
 
@@ -119,9 +121,7 @@ def read_item(item_id: int):
 The logger automatically includes:
 
 - Correlation IDs for request tracing
-- Request path and method
-- Lambda context information
-- Cold start indicators
+- Request path, matched route and method
 
 #### Tracing
 
@@ -157,8 +157,7 @@ Default metrics include:
 
 - Request counts
 - Success/failure counts
-- Cold start metrics
-- Per-route metrics
+- Per-route metrics (via a `route` dimension of `<method> <path>`)
 
 ### Error Handling
 
@@ -185,6 +184,216 @@ Unhandled exceptions are caught by the middleware and:
 It's recommended to specify response models for your API operations for better code generation if using the `connection` generator. <Link path="guides/connection/react-fastapi#errors">See here for more details</Link>.
 :::
 
+### Accessing the Calling User
+
+When your API is protected by authentication, your route handlers often need to know who is calling. The generated FastAPI runs inside AWS Lambda via the [Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter), which forwards the API Gateway request context as JSON on the `x-amzn-request-context` header. You can read it from the FastAPI `Request` to extract the caller's identity.
+
+As an example, let's add a `/me` endpoint that returns details about the calling user. We'll implement the extraction as a [FastAPI dependency](https://fastapi.tiangolo.com/tutorial/dependencies/) so it can be reused across routes. The shape of the request context — and therefore how you extract the identity — depends on both your selected `auth` method and whether you deployed a REST or HTTP API.
+
+<OptionFilter when={{ auth: 'iam' }} description="Identity extraction for IAM-authenticated APIs">
+For `IAM` authentication, we look up the caller in Cognito using the sub extracted from the API Gateway request context. Create `identity.py` alongside `main.py`:
+
+<Tabs syncKey="http-rest">
+<TabItem label="REST API" _filter={{ infra: 'rest-lambda' }}>
+```python
+import json
+import os
+from typing import Annotated
+
+from boto3 import client
+from fastapi import Depends, HTTPException, Request
+from pydantic import BaseModel
+
+cognito = client("cognito-idp")
+
+
+class Identity(BaseModel):
+    sub: str
+    username: str
+
+
+def get_identity(request: Request) -> Identity:
+    # The Lambda Web Adapter forwards the API Gateway request context as JSON
+    request_context_header = request.headers.get("x-amzn-request-context")
+    if not request_context_header:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    request_context = json.loads(request_context_header)
+    provider = request_context.get("identity", {}).get("cognitoAuthenticationProvider")
+
+    sub = provider.split(":")[-1] if provider else None
+    if not sub:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    users = cognito.list_users(
+        # Assumes user pool id is configured in lambda environment
+        UserPoolId=os.environ["USER_POOL_ID"],
+        Limit=1,
+        Filter=f'sub="{sub}"',
+    ).get("Users", [])
+
+    if len(users) != 1:
+        raise HTTPException(status_code=403, detail=f"No user found with subjectId {sub}")
+
+    return Identity(sub=sub, username=users[0]["Username"])
+
+
+CurrentUser = Annotated[Identity, Depends(get_identity)]
+```
+</TabItem>
+<TabItem label="HTTP API" _filter={{ infra: 'http-lambda' }}>
+```python
+import json
+import os
+from typing import Annotated
+
+from boto3 import client
+from fastapi import Depends, HTTPException, Request
+from pydantic import BaseModel
+
+cognito = client("cognito-idp")
+
+
+class Identity(BaseModel):
+    sub: str
+    username: str
+
+
+def get_identity(request: Request) -> Identity:
+    # The Lambda Web Adapter forwards the API Gateway request context as JSON
+    request_context_header = request.headers.get("x-amzn-request-context")
+    if not request_context_header:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    request_context = json.loads(request_context_header)
+    amr = (
+        request_context.get("authorizer", {})
+        .get("iam", {})
+        .get("cognitoIdentity", {})
+        .get("amr", [])
+    )
+    sign_in = next((s for s in amr if ":CognitoSignIn:" in s), None)
+    sub = sign_in.split(":")[-1] if sign_in else None
+
+    if not sub:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    users = cognito.list_users(
+        # Assumes user pool id is configured in lambda environment
+        UserPoolId=os.environ["USER_POOL_ID"],
+        Limit=1,
+        Filter=f'sub="{sub}"',
+    ).get("Users", [])
+
+    if len(users) != 1:
+        raise HTTPException(status_code=403, detail=f"No user found with subjectId {sub}")
+
+    return Identity(sub=sub, username=users[0]["Username"])
+
+
+CurrentUser = Annotated[Identity, Depends(get_identity)]
+```
+</TabItem>
+</Tabs>
+</OptionFilter>
+
+<OptionFilter when={{ auth: 'cognito' }} description="Identity extraction for Cognito-authenticated APIs">
+With `auth: 'cognito'`, the API Gateway Cognito User Pools authorizer verifies the JWT that the caller supplies in the `Authorization` header and places the verified claims on the request context.
+
+Create `identity.py` alongside `main.py`:
+
+<Tabs syncKey="http-rest">
+<TabItem label="REST API" _filter={{ infra: 'rest-lambda' }}>
+```python
+import json
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Request
+from pydantic import BaseModel
+
+
+class Identity(BaseModel):
+    sub: str
+    username: str
+
+
+def get_identity(request: Request) -> Identity:
+    # The Lambda Web Adapter forwards the API Gateway request context as JSON
+    request_context_header = request.headers.get("x-amzn-request-context")
+    if not request_context_header:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    request_context = json.loads(request_context_header)
+    claims = request_context.get("authorizer", {}).get("claims", {})
+
+    sub = claims.get("sub")
+    username = claims.get("username")
+
+    if not sub or not username:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    return Identity(sub=sub, username=username)
+
+
+CurrentUser = Annotated[Identity, Depends(get_identity)]
+```
+</TabItem>
+<TabItem label="HTTP API" _filter={{ infra: 'http-lambda' }}>
+HTTP APIs use a JWT authorizer which places the verified claims under `authorizer.jwt.claims`:
+
+```python
+import json
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Request
+from pydantic import BaseModel
+
+
+class Identity(BaseModel):
+    sub: str
+    username: str
+
+
+def get_identity(request: Request) -> Identity:
+    # The Lambda Web Adapter forwards the API Gateway request context as JSON
+    request_context_header = request.headers.get("x-amzn-request-context")
+    if not request_context_header:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    request_context = json.loads(request_context_header)
+    claims = request_context.get("authorizer", {}).get("jwt", {}).get("claims", {})
+
+    sub = claims.get("sub")
+    username = claims.get("username")
+
+    if not sub or not username:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    return Identity(sub=sub, username=username)
+
+
+CurrentUser = Annotated[Identity, Depends(get_identity)]
+```
+</TabItem>
+</Tabs>
+
+:::tip[No token verification required]
+You don't need any JWT-verification library here — the API Gateway Cognito User Pools authorizer has already verified the signature, issuer, scopes, and expiry by the time your Lambda runs. If any of those checks fail, API Gateway returns `401 Unauthorized` and your handler is never invoked.
+:::
+</OptionFilter>
+
+You can then inject the `CurrentUser` dependency into any route that needs the caller's identity:
+
+```python
+from .identity import CurrentUser, Identity
+from .init import app, tracer
+
+@app.get("/me")
+@tracer.capture_method
+def me(identity: CurrentUser) -> Identity:
+    return identity
+```
+
 <OptionFilter when={{ infra: 'rest-lambda' }} description="Streaming — REST API only">
 ### Streaming
 
@@ -226,14 +435,14 @@ To consume a stream of responses, you can make use of the <Link path="guides/con
 
 ## Deploying your FastAPI
 
-The FastAPI generator creates CDK or Terraform infrastructure as code based on your selected `iacProvider`. You can use this to deploy your FastAPI.
+The FastAPI generator creates CDK or Terraform infrastructure as code based on your selected `iac`. You can use this to deploy your FastAPI.
 
 <Infrastructure>
 <Fragment slot="cdk">
 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) {
@@ -261,7 +470,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) {
@@ -330,7 +539,7 @@ This sets up:
 :::note[Cognito Authentication]
 If you selected to use `Cognito` authentication, you will need to supply the Cognito configuration:
 
-```hcl {3, 5-6}
+```hcl {6-7}
 module "my_api" {
   source = "../../common/terraform/src/app/apis/my-api"
 
@@ -406,6 +615,12 @@ When using `Custom` auth, your API is protected by a Lambda Authorizer that **de
 <Snippet name="api/waf-configuration" parentHeading="WAF" />
 </OptionFilter>
 
+<OptionFilter when={{ infra: 'rest-lambda' }} description="Access logging — REST APIs log requests to CloudWatch by default">
+### Access logging
+
+<Snippet name="api/access-logging" parentHeading="Access logging" />
+</OptionFilter>
+
 ### Integrations
 
 <Snippet name="api/type-safe-api-integrations" parentHeading="Integrations" />
@@ -430,14 +645,14 @@ If you are actively working on both your CDK infrastructure and FastAPI together
 <NxCommands
   commands={[
     'watch --projects=<FastAPIProject> -- \\ ',
-    'run <InfraProject>:"generate:<ApiName>-metadata"',
+    'run @<scope>/common-constructs:"generate:<ApiName>-metadata"',
   ]}
 />
 :::
 </Fragment>
 <Fragment slot="terraform">
 :::note[Terraform Limitations]
-We do not support type-safe integrations for Terraform, and therefore no code generation targets are configured if you selected Terraform for your `iacProvider`.
+We do not support type-safe integrations for Terraform, and therefore no code generation targets are configured if you selected Terraform for your `iac`.
 :::
 </Fragment>
 </Infrastructure>
@@ -509,3 +724,25 @@ This starts a local FastAPI development server with:
 ## Invoking your FastAPI
 
 To invoke your API from a React website, you can use the <Link path="guides/connection/react-fastapi">`connection` generator</Link>.
+
+## Connections
+
+Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:
+
+<CardGrid>
+  <ConnectionCard
+    title="React to FastAPI"
+    description="Call a Python FastAPI from a React website"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-fastapi`}
+    source="react"
+    target="fastapi"
+  />
+  <ConnectionCard
+    title="FastAPI to Python DynamoDB"
+    description="Connect a FastAPI to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-fast-api-dynamodb`}
+    source="fastapi"
+    target="dynamodb"
+    targetBadge="python"
+  />
+</CardGrid>

package/docs/guides/local-development.mdx

@@ -0,0 +1,87 @@
+---
+title: Local Development
+description: How local development works with the serve and dev targets
+---
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+
+Connected projects expose two targets for running them on your machine: `serve` and `dev`. The difference is one of **scope** — how much of your application runs locally versus pointing at deployed AWS infrastructure.
+
+Consider a workspace with the following connections: a website that calls a tRPC `api`, and also calls an `agent` which in turn calls an `mcp` server.
+
+## `serve`
+
+The `serve` target runs **only the targeted project** locally. Every other project it connects to is expected to be **deployed**, and is reached at its real AWS URL.
+
+<NxCommands commands={['serve website']} />
+
+Because the targeted project talks to deployed resources, it needs to know where they are. For a website this is provided by its `runtime-config.json` (see <Link path="guides/react-website#local-runtime-config">Local Runtime Config</Link>), which you load from a deployed application. For server-side projects (APIs and agents) that read <Link path="guides/runtime-config">Runtime Configuration</Link>, set the `RUNTIME_CONFIG_APP_ID` environment variable to point at your deployed AppConfig application.
+
+```d2
+direction: right
+
+local: Local {
+  style.stroke-dash: 3
+  website: website
+}
+deployed: Deployed {
+  style.stroke-dash: 3
+  api: api
+  agent: agent
+  mcp: mcp
+}
+
+local.website -> deployed.api
+local.website -> deployed.agent
+deployed.agent -> deployed.mcp
+```
+
+Use `serve` when you want to iterate on a single project against the "real", deployed versions of everything it depends on.
+
+## `dev`
+
+The `dev` target runs the **targeted project** and **every project connected to it transitively**, all on your machine. The connection generator wires this up automatically — running `dev` on the website also starts local servers for the `api`, the `agent`, and the `mcp` server it reaches through the agent.
+
+<NxCommands commands={['dev website']} />
+
+When run this way, the website's `runtime-config.json` is automatically overridden (via [Vite's `MODE`](https://vite.dev/guide/env-and-mode), set to `local-dev`) so that it points at your locally running servers instead of deployed URLs.
+
+```d2
+direction: right
+
+local: Local {
+  style.stroke-dash: 3
+  website: website
+  api: api
+  agent: agent
+  mcp: mcp
+
+  website -> api
+  website -> agent
+  agent -> mcp
+}
+```
+
+Every project runs locally, so there are no deployed dependencies.
+
+Use `dev` when you are working across several connected projects at once and want to iterate quickly without deploying your infrastructure.
+
+### Projects with multiple components
+
+Some project types can hold multiple components in a single project (for example a TypeScript or Python project containing several agents and MCP servers). For these:
+
+- The project-level `dev` target starts **all** of the project's components together. Each component is added to `dev` as it is generated:
+
+<NxCommands commands={['dev my-project']} />
+- Each component also exposes a `<component-name>-dev` target, so you can run a single component on its own:
+
+<NxCommands commands={['my-component-dev my-project']} />
+
+:::tip[Workspace `dev` script]
+Your workspace's root `package.json` includes a `dev` script that runs `nx run-many --target dev`, starting the `dev` target for every project that has one. Spin up your whole workspace's local development servers with:
+
+<PackageManagerShortCommand commands={["dev"]} />
+:::
+
+For more detail on each project type's local development server, see the relevant guide — for example the <Link path="guides/react-website#local-development-server">React Website</Link> guide.

package/docs/guides/nx-generator.mdx

@@ -286,7 +286,7 @@ import { generateFiles, joinPathFragments } from '@nx/devkit';
 // Generate files from templates
 generateFiles(
   tree,
-  joinPathFragments(__dirname, 'files'), // Template directory
+  joinPathFragments(import.meta.dirname, 'files'), // Template directory
   'path/to/output', // Output directory
   {
     // Variables to replace in templates
@@ -459,7 +459,7 @@ export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
 
   generateFiles(
     tree,
-    joinPathFragments(__dirname, 'files'), // Template directory
+    joinPathFragments(import.meta.dirname, 'files'), // Template directory
     'path/to/output', // Output directory
     data,
   );
@@ -497,7 +497,7 @@ Unit tests for generators are straightforward to implement. Here's a typical pat
 
 ```typescript
 import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
-import { yourGenerator } from './generator';
+import { yourGenerator } from './generator.js';
 
 describe('your generator', () => {
   let tree;
@@ -583,6 +583,7 @@ When this generator is run in our repository, it'll generate the following files
   - docs/src/content/docs/guides/
     - \<name>.mdx Documentation page for your generator
   - packages/nx-plugin/generators.json Updated to include your generator
+  - packages/nx-plugin/sdk/\<prefix>.ts Updated to expose your generator from the SDK (for `ts#` and `py#` generators)
 </FileTree>
 
 You can then start to implement your generator.