@aws/nx-plugin-mcp 1.0.0-rc.10 → 1.0.0-rc.11

package/docs/guides/connection.mdx

@@ -153,3 +153,7 @@ The Connection generator supports the following connections:
 :::note[Runtime Configuration]
 The connection generator makes use of <Link path="guides/runtime-config">Runtime Configuration</Link> to pass deploy-time values (such as API URLs, Cognito settings, and agent runtime ARNs) between generated projects and components at runtime so they can discover and connect to one another.
 :::
+
+:::tip[Local Development]
+Connected projects can be run on your machine with the `serve` and `serve-local` targets. See the <Link path="guides/local-development">Local Development</Link> guide for details.
+:::

package/docs/guides/local-development.mdx

@@ -0,0 +1,76 @@
+---
+title: Local Development
+description: How local development works with the serve and serve-local 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 `serve-local`. 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.
+
+## `serve-local`
+
+The `serve-local` target runs the **targeted project** and **every project connected to it transitively**, all on your machine. The connection generator wires this up automatically — running `serve-local` on the website also starts local servers for the `api`, the `agent`, and the `mcp` server it reaches through the agent.
+
+<NxCommands commands={['serve-local 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 `serve-local`) 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 `serve-local` when you are working across several connected projects at once and want to iterate quickly without deploying your infrastructure.
+
+:::tip[`dev` shortcut]
+A root `dev` script is added as a shortcut for the first website you generate in your workspace, so you can spin up the website and all connected components 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/ts-dynamodb.mdx

@@ -11,7 +11,6 @@ import GeneratorParameters from '@components/generator-parameters.astro';
 import Infrastructure from '@components/infrastructure.astro';
 import NxCommands from '@components/nx-commands.astro';
 import Snippet from '@components/snippet.astro';
-import OptionFilter from '@components/option-filter.astro';
 
 This generator creates a new TypeScript project backed by [Amazon DynamoDB](https://aws.amazon.com/dynamodb/), using [ElectroDB](https://electrodb.dev/) for type-safe entity modelling. It generates the application code and infrastructure needed to provision and manage a DynamoDB table using AWS CDK or Terraform, with single-table design support and built-in local development via DynamoDB Local.
 
@@ -41,6 +40,7 @@ The generator creates the following project structure in the `<directory>/<name>
     - entities
       - example.ts Example ElectroDB entity definition
       - index.ts Entity exports
+  - dynamodb.config.json GSI definitions for the table
   - project.json Project configuration and build targets
 </FileTree>
 
@@ -84,7 +84,7 @@ The generator configures a `serve-local` target that starts a [DynamoDB Local](h
 This automatically:
 1. Pulls the DynamoDB Local image (`pull-image` target)
 2. Starts a container
-3. Creates a local table with pre-defined indexes
+3. Creates a local table with the indexes defined in `dynamodb.config.json`
 
 ### Data Modelling
 
@@ -165,11 +165,34 @@ Replace `<engine>` with your container engine (`docker` or `finch`) and `<scope>
 
 ## Adding/Removing Global Secondary Indexes
 
-Start by updating `GLOBAL_SECONDARY_INDEXES` in `src/gsi.ts` — this is the source of truth for your GSI definitions, and on the next `serve-local` run the script will automatically add or remove indexes on the local table to reflect the new list. When using CDK, these changes are also automatically reflected in your AWS table on the next deployment.
+GSIs are defined in `dynamodb.config.json` at the project root. Add an entry to `globalSecondaryIndexes` for each GSI, following the [single-table design](https://electrodb.dev/en/core-concepts/single-table-relationships/) naming convention for GSI keys:
 
-<OptionFilter when={{ iac: 'terraform' }}>
-  Unlike CDK, changes to `src/gsi.ts` are not automatically reflected in your Terraform module. You must also manually update your Terraform module to add or remove the corresponding GSI definitions before deploying.
-</OptionFilter>
+```json title="packages/my-table/dynamodb.config.json"
+{
+  "globalSecondaryIndexes": [
+    {
+      "indexName": "gsi1pk-gsi1sk-index",
+      "partitionKey": "gsi1pk",
+      "sortKey": "gsi1sk"
+    }
+  ]
+}
+```
+
+The `sortKey` field is optional for hash-key-only GSIs.
+
+This config file is read directly from the project root by all consumers:
+- **Local development** — `serve-local` reads `dynamodb.config.json` and creates or updates the local table to match the GSI list
+- **CDK** — the construct reads `dynamodb.config.json` at synth time, so GSI changes are reflected on the next `cdk deploy`
+- **Terraform** — the module reads `dynamodb.config.json` at plan/apply time
+
+### One GSI per Deployment
+
+:::caution
+DynamoDB [does not allow more than one GSI to be created or deleted in a single table update](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.OnlineOps.html).
+
+Each deployment can add or remove **at most one GSI**. If you need to add or remove multiple GSIs, do so one at a time — update `dynamodb.config.json`, deploy the stack, then repeat for the next change.
+:::
 
 ## Connecting to the Table
 
@@ -217,7 +240,7 @@ export class ApplicationStack extends Stack {
 
 This provisions a DynamoDB table with:
 - `pk` (partition key) and `sk` (sort key), both `String` type
-- 2 Global Secondary Indexes by default, as defined in `src/gsi.ts`
+- Global Secondary Indexes as defined in `dynamodb.config.json`
 - On-demand (`PAY_PER_REQUEST`) billing
 - Customer-managed KMS encryption with automatic key rotation
 - Point-in-time recovery enabled
@@ -235,7 +258,7 @@ module "my_table" {
 
 This provisions a DynamoDB table with:
 - `pk` (partition key) and `sk` (sort key), both `String` type
-- 2 Global Secondary Indexes by default, as defined in `src/gsi.ts`
+- Global Secondary Indexes as defined in `dynamodb.config.json`
 - On-demand (`PAY_PER_REQUEST`) billing
 - Customer-managed KMS encryption with automatic key rotation
 - Point-in-time recovery enabled

package/package.json

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