@aws/nx-plugin-mcp 1.0.0-rc.3 → 1.0.0-rc.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. package/bin/aws-nx-mcp.js +4312 -3360
  2. package/docs/guides/agentcore-gateway.mdx +376 -0
  3. package/docs/guides/connection/agentcore-gateway-gateway.mdx +154 -0
  4. package/docs/guides/connection/agentcore-gateway-mcp.mdx +134 -0
  5. package/docs/guides/connection/py-agent-a2a.mdx +47 -15
  6. package/docs/guides/connection/py-agent-dynamodb.mdx +116 -0
  7. package/docs/guides/connection/py-agent-gateway.mdx +176 -0
  8. package/docs/guides/connection/py-agent-mcp.mdx +42 -13
  9. package/docs/guides/connection/py-fast-api-dynamodb.mdx +56 -0
  10. package/docs/guides/connection/py-mcp-server-dynamodb.mdx +116 -0
  11. package/docs/guides/connection/react-agui.mdx +4 -4
  12. package/docs/guides/connection/react-fastapi.mdx +2 -2
  13. package/docs/guides/connection/react-py-agent.mdx +3 -3
  14. package/docs/guides/connection/react-smithy.mdx +3 -3
  15. package/docs/guides/connection/react-trpc.mdx +1 -1
  16. package/docs/guides/connection/react-ts-agent.mdx +5 -5
  17. package/docs/guides/connection/smithy-dynamodb.mdx +68 -0
  18. package/docs/guides/connection/smithy-rdb.mdx +4 -4
  19. package/docs/guides/connection/trpc-dynamodb.mdx +62 -0
  20. package/docs/guides/connection/trpc-rdb.mdx +4 -4
  21. package/docs/guides/connection/ts-agent-a2a.mdx +12 -9
  22. package/docs/guides/connection/ts-agent-dynamodb.mdx +128 -0
  23. package/docs/guides/connection/ts-agent-gateway.mdx +141 -0
  24. package/docs/guides/connection/ts-agent-mcp.mdx +11 -8
  25. package/docs/guides/connection/ts-agent-rdb.mdx +3 -3
  26. package/docs/guides/connection/ts-mcp-server-dynamodb.mdx +125 -0
  27. package/docs/guides/connection/ts-mcp-server-rdb.mdx +3 -3
  28. package/docs/guides/connection.mdx +101 -0
  29. package/docs/guides/docker-bundling.mdx +13 -7
  30. package/docs/guides/fastapi.mdx +244 -4
  31. package/docs/guides/license.mdx +264 -109
  32. package/docs/guides/local-development.mdx +87 -0
  33. package/docs/guides/nx-generator.mdx +7 -2
  34. package/docs/guides/py-agent.mdx +204 -44
  35. package/docs/guides/py-dynamodb.mdx +476 -0
  36. package/docs/guides/py-mcp-server.mdx +57 -2
  37. package/docs/guides/react-website-auth.mdx +58 -1
  38. package/docs/guides/react-website.mdx +87 -19
  39. package/docs/guides/terraform-project.mdx +1 -1
  40. package/docs/guides/trpc.mdx +45 -9
  41. package/docs/guides/ts-agent.mdx +120 -6
  42. package/docs/guides/ts-dynamodb.mdx +187 -0
  43. package/docs/guides/ts-mcp-server.mdx +62 -2
  44. package/docs/guides/ts-rdb.mdx +98 -20
  45. package/docs/guides/ts-smithy-api.mdx +183 -4
  46. package/docs/guides/typescript-infrastructure.mdx +9 -1
  47. package/docs/guides/typescript-project.mdx +5 -10
  48. package/docs/guides/workspace.mdx +8 -2
  49. package/docs/snippets/agent/bedrock-deployment.mdx +4 -0
  50. package/docs/snippets/api/access-logging.mdx +33 -0
  51. package/docs/snippets/api/type-safe-api-integrations.mdx +31 -0
  52. package/docs/snippets/api/waf-configuration.mdx +1 -1
  53. package/docs/snippets/connection/dynamodb-local-development.mdx +7 -0
  54. package/docs/snippets/connection/lambda-dynamodb-access.mdx +80 -0
  55. package/docs/snippets/connection/py-dynamodb-local-development.mdx +7 -0
  56. package/docs/snippets/dynamodb/deploying-table.mdx +171 -0
  57. package/docs/snippets/dynamodb/gsi-config.mdx +38 -0
  58. package/docs/snippets/dynamodb/infrastructure.mdx +33 -0
  59. package/docs/snippets/dynamodb/local-dev-start.mdx +13 -0
  60. package/docs/snippets/dynamodb/local-dev-windows.mdx +15 -0
  61. package/docs/snippets/mcp/bedrock-deployment.mdx +4 -0
  62. package/docs/snippets/mcp/config.mdx +2 -1
  63. package/docs/snippets/required-prerequisites.mdx +1 -1
  64. package/generators.json +100 -1
  65. package/package.json +1 -1
  66. package/src/agentcore-gateway/gateway-connection/schema.json +31 -0
  67. package/src/agentcore-gateway/mcp-connection/schema.json +31 -0
  68. package/src/agentcore-gateway/schema.json +70 -0
  69. package/src/connection/schema.json +5 -0
  70. package/src/infra/app/schema.json +5 -0
  71. package/src/license/schema.json +11 -0
  72. package/src/preset/schema.json +10 -5
  73. package/src/py/agent/a2a-connection/schema.json +5 -0
  74. package/src/py/agent/gateway-connection/schema.json +31 -0
  75. package/src/py/agent/mcp-connection/schema.json +5 -0
  76. package/src/py/agent/react-connection/schema.json +5 -0
  77. package/src/py/agent/schema.json +6 -1
  78. package/src/py/api/schema.json +5 -0
  79. package/src/py/dynamodb/agent-connection/schema.json +27 -0
  80. package/src/py/dynamodb/fast-api-connection/schema.json +23 -0
  81. package/src/py/dynamodb/mcp-server-connection/schema.json +27 -0
  82. package/src/py/dynamodb/schema.json +75 -0
  83. package/src/py/fast-api/react/schema.json +5 -0
  84. package/src/py/fast-api/schema.json +5 -0
  85. package/src/py/lambda-function/schema.json +5 -0
  86. package/src/py/mcp-server/schema.json +5 -0
  87. package/src/py/project/schema.json +5 -0
  88. package/src/smithy/project/schema.json +5 -0
  89. package/src/smithy/react-connection/schema.json +5 -0
  90. package/src/smithy/ts/api/schema.json +5 -0
  91. package/src/terraform/project/schema.json +5 -0
  92. package/src/trpc/backend/schema.json +5 -0
  93. package/src/trpc/react/schema.json +5 -0
  94. package/src/ts/agent/a2a-connection/schema.json +5 -0
  95. package/src/ts/agent/gateway-connection/schema.json +31 -0
  96. package/src/ts/agent/mcp-connection/schema.json +5 -0
  97. package/src/ts/agent/react-connection/schema.json +5 -0
  98. package/src/ts/agent/schema.json +5 -0
  99. package/src/ts/api/schema.json +5 -0
  100. package/src/ts/astro-docs/schema.json +3 -3
  101. package/src/ts/docs/schema.json +3 -3
  102. package/src/ts/dynamodb/agent-connection/schema.json +27 -0
  103. package/src/ts/dynamodb/mcp-server-connection/schema.json +27 -0
  104. package/src/ts/dynamodb/schema.json +75 -0
  105. package/src/ts/dynamodb/smithy-connection/schema.json +23 -0
  106. package/src/ts/dynamodb/trpc-connection/schema.json +23 -0
  107. package/src/ts/lambda-function/schema.json +5 -0
  108. package/src/ts/lib/schema.json +5 -0
  109. package/src/ts/mcp-server/schema.json +5 -0
  110. package/src/ts/nx-generator/schema.json +5 -0
  111. package/src/ts/nx-plugin/schema.json +5 -0
  112. package/src/ts/rdb/agent-connection/schema.json +5 -0
  113. package/src/ts/rdb/mcp-server-connection/schema.json +5 -0
  114. package/src/ts/rdb/schema.json +5 -0
  115. package/src/ts/rdb/smithy-connection/schema.json +5 -0
  116. package/src/ts/rdb/trpc-connection/schema.json +5 -0
  117. package/src/ts/react-website/app/schema.json +11 -6
  118. package/src/ts/react-website/cognito-auth/schema.json +5 -0
  119. package/src/ts/react-website/runtime-config/schema.json +5 -0
  120. package/src/ts/website/app/schema.json +11 -6
  121. package/src/ts/website/auth/schema.json +5 -0
@@ -1,12 +1,14 @@
1
1
  ---
2
2
  title: React Website
3
3
  description: Reference documentation for a React Website
4
- generator: ts#react-website
4
+ generator: ts#website
5
5
  when:
6
6
  framework:
7
7
  - react
8
8
  ---
9
- import { FileTree, Steps } from '@astrojs/starlight/components';
9
+ import { FileTree, Steps, CardGrid } from '@astrojs/starlight/components';
10
+ import Astro from '@astrojs/react';
11
+ import ConnectionCard from '@components/connection-card.astro';
10
12
  import Link from '@components/link.astro';
11
13
  import RunGenerator from '@components/run-generator.astro';
12
14
  import GeneratorParameters from '@components/generator-parameters.astro';
@@ -16,12 +18,12 @@ import Infrastructure from '@components/infrastructure.astro';
16
18
  import Snippet from '@components/snippet.astro';
17
19
  import OptionFilter from '@components/option-filter.astro';
18
20
 
19
- This generator creates a new [React](https://react.dev/) website with [Cloudscape](http://cloudscape.design/) configured by default, along with the AWS CDK or Terraform infrastructure to deploy your website to the cloud as a static website hosted in [S3](https://aws.amazon.com/s3/), served by [CloudFront](https://aws.amazon.com/cloudfront/) and protected by [WAF](https://aws.amazon.com/waf/).
21
+ This generator creates a new [React](https://react.dev/) website with [shadcn/ui](https://ui.shadcn.com/) configured by default, along with the AWS CDK or Terraform infrastructure to deploy your website to the cloud as a static website hosted in [S3](https://aws.amazon.com/s3/), served by [CloudFront](https://aws.amazon.com/cloudfront/) and protected by [WAF](https://aws.amazon.com/waf/).
20
22
 
21
23
  The generated application uses [Vite](https://vite.dev/) as the build tool and bundler. It uses [TanStack Router](https://tanstack.com/router/v1) for type-safe routing.
22
24
 
23
25
  :::note[UX Provider]
24
- The default `uxProvider` is [Cloudscape](http://cloudscape.design/). You can also select [shadcn/ui](https://ui.shadcn.com/) or `None` (bring your own component library).
26
+ The default `uxProvider` is [shadcn/ui](https://ui.shadcn.com/). You can also select [Cloudscape](http://cloudscape.design/) or `None` (bring your own component library).
25
27
  :::
26
28
 
27
29
  ## Usage
@@ -30,7 +32,7 @@ The default `uxProvider` is [Cloudscape](http://cloudscape.design/). You can als
30
32
 
31
33
  You can generate a new React Website in two ways:
32
34
 
33
- <RunGenerator generator="ts#website" />
35
+ <RunGenerator generator="ts#website" requiredParameters={{ framework: 'react' }} />
34
36
 
35
37
  ### Options
36
38
 
@@ -126,6 +128,14 @@ waf -> cloudfront
126
128
  cloudfront -> s3
127
129
  ```
128
130
 
131
+ #### Security Headers
132
+
133
+ The CloudFront distribution applies a response headers policy that sets `Strict-Transport-Security`, `X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy` and a `Content-Security-Policy` on all responses.
134
+
135
+ A default `Content-Security-Policy` is enforced. It restricts scripts and framing to mitigate XSS and clickjacking, while permitting HTTPS and WSS connections so the website can call AWS service endpoints (such as API Gateway, Cognito and Bedrock AgentCore) whose URLs are only known at deploy time. To adjust the policy (for example to tighten `connect-src` to your specific origins), edit the `content_security_policy` value in your generated `static-website.ts` (CDK) or `static-website.tf` (Terraform).
136
+
137
+ `runtime-config.json` is served with `Cache-Control: no-cache` so that browsers always fetch the latest configuration after a redeploy, rather than using a stale cached copy.
138
+
129
139
  ## Implementing your React Website
130
140
 
131
141
  The [React documentation](https://react.dev/learn) is a good place to start to learn the basics of building with React.
@@ -185,7 +195,7 @@ Configuration from your infrastructure is provided to your website via <Link hre
185
195
 
186
196
  <Infrastructure>
187
197
  <Fragment slot="cdk">
188
- The `RuntimeConfig` CDK construct can be used to add and retrieve configuration in your CDK infrastructure. The CDK constructs generated by `@aws/nx-plugin` generators (such as <Link path="guides/trpc">`ts#trpc-api`</Link> and <Link path="guides/fastapi">`py#fast-api`</Link>) will automatically add appropriate values to the `RuntimeConfig`.
198
+ The `RuntimeConfig` CDK construct can be used to add and retrieve configuration in your CDK infrastructure. The CDK constructs generated by `@aws/nx-plugin` generators (such as <Link path="guides/trpc">`ts#api`</Link> and <Link path="guides/fastapi">`py#api`</Link>) will automatically add appropriate values to the `RuntimeConfig`.
189
199
 
190
200
  Your website CDK construct will deploy the `connection` namespace of the runtime configuration as a `runtime-config.json` file to the root of your S3 bucket.
191
201
 
@@ -214,7 +224,7 @@ With CDK, the website construct can be declared at any point in your stack. Runt
214
224
  :::
215
225
  </Fragment>
216
226
  <Fragment slot="terraform">
217
- With Terraform, runtime configuration is managed through the runtime-config modules. The Terraform modules generated by `@aws/nx-plugin` generators (such as <Link path="guides/trpc">`ts#trpc-api`</Link> and <Link path="guides/fastapi">`py#fast-api`</Link>) will automatically add appropriate values to the runtime configuration.
227
+ With Terraform, runtime configuration is managed through the runtime-config modules. The Terraform modules generated by `@aws/nx-plugin` generators (such as <Link path="guides/trpc">`ts#api`</Link> and <Link path="guides/fastapi">`py#api`</Link>) will automatically add appropriate values to the runtime configuration.
218
228
 
219
229
  Your website Terraform module will deploy the `connection` namespace of the runtime configuration as a `runtime-config.json` file to the root of your S3 bucket.
220
230
 
@@ -291,7 +301,11 @@ For Terraform projects, the `load:runtime-config` target copies the `runtime-con
291
301
 
292
302
  ## Local Development Server
293
303
 
294
- You can run a local development server using either the `serve` or `serve-local` target.
304
+ The canonical command for local development is `dev`, which starts your website (and any local servers for APIs you've connected it to) with one command:
305
+
306
+ <NxCommands commands={['dev <my-website>']} />
307
+
308
+ The `serve` target is also available for when you need to control how much of your application runs locally versus pointing at deployed AWS infrastructure. For a broader overview of local development across connected projects, including how `dev` behaves for projects with multiple components, see the <Link path="guides/local-development">Local Development</Link> guide.
295
309
 
296
310
  ### Serve Target
297
311
 
@@ -303,46 +317,50 @@ You can run this target with the following command:
303
317
 
304
318
  This target is useful for working on website changes while pointing to "real" deployed APIs and other infrastructure.
305
319
 
306
- ### Serve Local Target
320
+ ### Dev Target
307
321
 
308
- The `serve-local` target starts a local development server for your website (with [Vite `MODE`](https://vite.dev/guide/env-and-mode) set to `serve-local`), as well as starting any local servers for APIs you have connected your website to via the <Link path="/guides/connection">Connection generator</Link>.
322
+ The `dev` target starts a local development server for your website (with [Vite `MODE`](https://vite.dev/guide/env-and-mode) set to `local-dev`), as well as starting any local servers for APIs you have connected your website to via the <Link path="/guides/connection">Connection generator</Link>.
309
323
 
310
324
  When your local website server is run via this target, `runtime-config.json` is automatically overridden to point to your locally running API urls.
311
325
 
312
326
  You can run this target with the following command:
313
327
 
314
- <NxCommands commands={['serve-local <my-website>']} />
328
+ <NxCommands commands={['dev <my-website>']} />
315
329
 
316
330
  This target is useful when you are working across your website and API and wish to quickly iterate without deploying your infrastructure.
317
331
 
318
- :::note[`dev` script]
319
- If no `dev` script exists in your root `package.json` when this generator runs, a `dev` script is added that invokes `serve-local` for the generated website, meaning you can also start the local development server with:
332
+ :::note[Workspace `dev` script]
333
+ Your workspace's root `package.json` includes a `dev` script that runs the `dev` target for every project that has one:
320
334
 
321
335
  <PackageManagerShortCommand commands={["dev"]} />
322
336
 
323
- This makes the first React website you generate the default `dev` target for the workspace. Subsequent websites do not overwrite the existing `dev` script — you can invoke their `serve-local` targets directly, or update the script manually.
337
+ This starts the local development server for your website (and any other projects with a `dev` target) in one command. To run just this website, use its own `dev` target (e.g. `nx dev <my-website>`).
324
338
  :::
325
339
 
326
340
  :::warning[Mock Authentication]
327
341
  When run in this mode and no `runtime-config.json` is present, if you have configured Cognito Authentication (via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link>), login will be skipped and requests to your local servers will not include authentication headers.
328
342
 
329
- To enable login and authentication for `serve-local`, deploy your infrastructure and load runtime config.
343
+ To enable login and authentication for `dev`, deploy your infrastructure and load runtime config.
330
344
  :::
331
345
 
332
- :::tip[Serve-Local Behavior]
333
- When running with `serve-local`, you can specify any environment variables required by your APIs to point to other deployed AWS resources, for example:
346
+ :::tip[Dev Behavior]
347
+ When running with `dev`, you can specify any environment variables required by your APIs to point to other deployed AWS resources, for example:
334
348
 
335
- <NxCommands env={{DYNAMODB_TABLE_NAME: 'xxxxx'}} commands={['serve-local <my-website>']} />
349
+ <NxCommands env={{DYNAMODB_TABLE_NAME: 'xxxxx'}} commands={['dev <my-website>']} />
336
350
 
337
351
  Note that your local API servers will run with the AWS credentials you have configured locally.
338
352
  :::
339
353
 
340
354
  ## Building
341
355
 
342
- You can build your website using the `build` target. This use Vite to create a production bundle in the root `dist/packages/<my-website>/bundle` directory, as well as type-checking, compiling and linting your website.
356
+ You can build your website using the `build` target. This runs the `bundle`, `compile`, `test` and `lint` targets, type-checking, bundling, testing and linting your website.
343
357
 
344
358
  <NxCommands commands={['build <my-website>']} />
345
359
 
360
+ The `bundle` target uses Vite to create a production bundle in the root `dist/packages/<my-website>/bundle` directory. This is the deployable artifact consumed by your website infrastructure. You can run it on its own:
361
+
362
+ <NxCommands commands={['bundle <my-website>']} />
363
+
346
364
  ## Testing
347
365
 
348
366
  Testing your website is much like writing tests in a standard TypeScript project, so please refer to the <Link path="guides/typescript-project#testing">TypeScript project guide</Link> for more details.
@@ -422,3 +440,53 @@ provider "aws" {
422
440
  </Fragment>
423
441
  </Infrastructure>
424
442
 
443
+ ## Connections
444
+
445
+ Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:
446
+
447
+ <CardGrid>
448
+ <ConnectionCard
449
+ title="React to tRPC"
450
+ description="Call a tRPC API from a React website"
451
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-trpc`}
452
+ source="react"
453
+ target="trpc"
454
+ />
455
+ <ConnectionCard
456
+ title="React to FastAPI"
457
+ description="Call a Python FastAPI from a React website"
458
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-fastapi`}
459
+ source="react"
460
+ target="fastapi"
461
+ />
462
+ <ConnectionCard
463
+ title="React to Smithy API"
464
+ description="Call a Smithy API from a React website"
465
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-smithy`}
466
+ source="react"
467
+ target="smithy"
468
+ />
469
+ <ConnectionCard
470
+ title="React to Python Agent"
471
+ description="Call a Python Agent from a React website"
472
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-py-agent`}
473
+ source="react"
474
+ target="strands"
475
+ targetBadge="python"
476
+ />
477
+ <ConnectionCard
478
+ title="React to TypeScript Agent"
479
+ description="Call a TypeScript Agent from a React website"
480
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-ts-agent`}
481
+ source="react"
482
+ target="strands"
483
+ targetBadge="typescript"
484
+ />
485
+ <ConnectionCard
486
+ title="React to AG-UI Agent"
487
+ description="Call an Agent exposing the AG-UI protocol from a React website via CopilotKit"
488
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-agui`}
489
+ source="react"
490
+ target="copilotkit"
491
+ />
492
+ </CardGrid>
@@ -108,7 +108,7 @@ You can start writing your Terraform infrastructure inside `src/main.tf`, for ex
108
108
 
109
109
  ### Cross project dependencies
110
110
 
111
- If you wanted to execute a module from a seperate project (lib), you could do so as follows:
111
+ If you wanted to execute a module from a separate project (lib), you could do so as follows:
112
112
 
113
113
  ```
114
114
  module "lib_module" {
@@ -1,12 +1,14 @@
1
1
  ---
2
2
  title: tRPC
3
3
  description: Reference documentation for tRPC
4
- generator: ts#trpc-api
4
+ generator: ts#api
5
5
  when:
6
6
  framework: [trpc]
7
7
  infra: [rest-lambda, http-lambda]
8
8
  ---
9
- import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
9
+ import { FileTree, Tabs, TabItem, CardGrid } from '@astrojs/starlight/components';
10
+ import Astro from '@astrojs/react';
11
+ import ConnectionCard from '@components/connection-card.astro';
10
12
  import Link from '@components/link.astro';
11
13
  import RunGenerator from '@components/run-generator.astro';
12
14
  import GeneratorParameters from '@components/generator-parameters.astro';
@@ -25,11 +27,11 @@ The tRPC API generator creates a new tRPC API with AWS CDK or Terraform infrastr
25
27
 
26
28
  You can generate a new tRPC API in two ways:
27
29
 
28
- <RunGenerator generator="ts#trpc-api" />
30
+ <RunGenerator generator="ts#api" requiredParameters={{ framework: 'trpc' }} />
29
31
 
30
32
  ### Options
31
33
 
32
- <GeneratorParameters generator="ts#trpc-api" />
34
+ <GeneratorParameters generator="ts#api" />
33
35
 
34
36
  <Snippet name="api/api-choice-note" />
35
37
 
@@ -138,7 +140,7 @@ The example `echo` procedure is generated for you in `src/procedures/echo.ts`:
138
140
  export const echo = publicProcedure
139
141
  .input(EchoInputSchema)
140
142
  .output(EchoOutputSchema)
141
- .query((opts) => ({ result: opts.input.message }));
143
+ .query((opts) => ({ message: opts.input.message }));
142
144
  ```
143
145
 
144
146
  To break down the above:
@@ -478,7 +480,7 @@ export interface IIdentityContext {
478
480
 
479
481
  Note that we define an additional _optional_ property on the context. tRPC manages ensuring that this is defined in procedures which have correctly configured this middleware.
480
482
 
481
- Next, the middleware itself. The generator wires the authorizer to accept ID tokens, so `cognito:username` is the canonical username claim; we fall back to `username` for access tokens in case you reconfigure the authorizer:
483
+ Next, the middleware itself:
482
484
 
483
485
  ```ts
484
486
  import { initTRPC, TRPCError } from '@trpc/server';
@@ -503,7 +505,7 @@ export const createIdentityPlugin = () => {
503
505
  | undefined;
504
506
 
505
507
  const sub = claims?.sub;
506
- const username = claims?.['cognito:username'] ?? claims?.username;
508
+ const username = claims?.username;
507
509
 
508
510
  if (!sub || !username) {
509
511
  throw new TRPCError({
@@ -541,8 +543,8 @@ export const me = publicProcedure
541
543
  }));
542
544
  ```
543
545
 
544
- :::tip[Verifying the token]
545
- You don't need `aws-jwt-verify` or any other JWT-verification library here — the API Gateway Cognito User Pools authorizer has already verified the signature, issuer, audience, 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.
546
+ :::tip[No token verification required]
547
+ You don't need `aws-jwt-verify` or any other 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.
546
548
  :::
547
549
  </OptionFilter>
548
550
 
@@ -726,6 +728,12 @@ When using `Custom` auth, your API is protected by a Lambda Authorizer that **de
726
728
  <Snippet name="api/waf-configuration" parentHeading="WAF" />
727
729
  </OptionFilter>
728
730
 
731
+ <OptionFilter when={{ infra: 'rest-lambda' }} description="Access logging — REST APIs log requests to CloudWatch by default">
732
+ ### Access logging
733
+
734
+ <Snippet name="api/access-logging" parentHeading="Access logging" />
735
+ </OptionFilter>
736
+
729
737
  ### Integrations
730
738
 
731
739
  <Snippet name="api/type-safe-api-integrations" parentHeading="Integrations" />
@@ -817,3 +825,31 @@ If you are calling your API from a React website, consider using the <Link path=
817
825
  ## More Information
818
826
 
819
827
  For more information about tRPC, please refer to the [tRPC documentation](https://trpc.io/docs).
828
+
829
+ ## Connections
830
+
831
+ Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:
832
+
833
+ <CardGrid>
834
+ <ConnectionCard
835
+ title="React to tRPC"
836
+ description="Call a tRPC API from a React website"
837
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-trpc`}
838
+ source="react"
839
+ target="trpc"
840
+ />
841
+ <ConnectionCard
842
+ title="tRPC API to Relational Database"
843
+ description="Connect a tRPC API to an Aurora relational database"
844
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/trpc-rdb`}
845
+ source="trpc"
846
+ target="aurora"
847
+ />
848
+ <ConnectionCard
849
+ title="tRPC API to TypeScript DynamoDB"
850
+ description="Connect a tRPC API to a DynamoDB table"
851
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/trpc-dynamodb`}
852
+ source="trpc"
853
+ target="dynamodb"
854
+ />
855
+ </CardGrid>
@@ -4,7 +4,9 @@ description: Generate a TypeScript Agent for building AI agents with tools and d
4
4
  generator: ts#agent
5
5
  ---
6
6
 
7
- import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
7
+ import { FileTree, Tabs, TabItem, CardGrid } from '@astrojs/starlight/components';
8
+ import Astro from '@astrojs/react';
9
+ import ConnectionCard from '@components/connection-card.astro';
8
10
  import RunGenerator from '@components/run-generator.astro';
9
11
  import NxCommands from '@components/nx-commands.astro';
10
12
  import Link from '@components/link.astro';
@@ -261,19 +263,61 @@ Most users will not need to modify `index.ts` — edit `agent.ts` to change tool
261
263
 
262
264
  ### Local Development
263
265
 
264
- The generator configures a target named `<your-agent-name>-serve`, which starts your Agent locally for development and testing.
266
+ To run your Agent (and everything connected to it) locally, use the project's `dev` target:
265
267
 
266
- <NxCommands commands={['agent-serve your-project']} />
268
+ <NxCommands commands={['dev your-project']} />
267
269
 
268
- This command uses `tsx --watch` to automatically restart the server when files change. The agent will be available at `http://localhost:8081` (or the assigned port if you have multiple agents).
270
+ If you have added multiple components to your project (agents, MCP servers, etc.), this starts them all. To run just this agent, target its `<your-agent-name>-dev` target:
271
+
272
+ <NxCommands commands={['agent-dev your-project']} />
273
+
274
+ This uses `tsx --watch` to automatically restart the server when files change. The agent will be available at `http://localhost:8081` (or the assigned port if you have multiple agents).
269
275
 
270
276
  ### Chat with Your Agent
271
277
 
272
- The generator configures a `<your-agent-name>-chat` Nx target that depends on `<your-agent-name>-serve-local`. Running it starts the agent locally and drops you into an interactive terminal chat:
278
+ The generator configures a `<your-agent-name>-chat` Nx target that drops you into an interactive terminal chat with your agent.
279
+
280
+ The chat target runs standalone. By default it connects to your locally running agent, so start the agent's `<your-agent-name>-dev` target first (in a separate terminal):
281
+
282
+ <NxCommands commands={['agent-dev your-project']} />
283
+
284
+ Then, in another terminal, start the chat:
273
285
 
274
286
  <NxCommands commands={['run your-project:agent-chat']} />
275
287
 
276
- For **HTTP** (tRPC over WebSocket) agents, the generator also emits a tiny `scripts/<your-agent-name>/chat.ts` that wraps the generated `<Agent>Client.local({ url })` so you can customize it as you evolve the agent's input shape.
288
+ The generator emits a `scripts/<your-agent-name>/chat.ts` for every protocol. You can customize it as you evolve the agent's input shape. It connects to the local agent by default, or to your deployed agent when `RUNTIME_CONFIG_APP_ID` is set (see [Chat with your deployed agent](#chat-with-your-deployed-agent) below).
289
+
290
+ <OptionFilter when={{ infra: 'agentcore' }} description="Deployed agent chat details">
291
+ #### Chat with your deployed agent
292
+
293
+ To chat with your agent deployed to Bedrock AgentCore, set the `RUNTIME_CONFIG_APP_ID` environment variable to the AppConfig application id of the deployment (output as `RuntimeConfigApplicationId` by the deployed stack). The chat script resolves your agent's runtime ARN from runtime configuration and connects to the deployed endpoint:
294
+
295
+ <Tabs syncKey="auth">
296
+ <TabItem label="IAM" _filter={{ auth: 'iam' }}>
297
+ For IAM-authenticated agents, requests are signed with [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) using your default AWS credentials. Ensure the environment has AWS credentials with permission to invoke the runtime:
298
+
299
+ <NxCommands commands={['run your-project:agent-chat']} env={{ RUNTIME_CONFIG_APP_ID: '<app-id>' }} />
300
+ </TabItem>
301
+
302
+ <TabItem label="Cognito" _filter={{ auth: 'cognito' }}>
303
+ For Cognito-authenticated agents, provide a Cognito access token via the `AGENT_ACCESS_TOKEN` environment variable, which is sent as a bearer token:
304
+
305
+ <NxCommands commands={['run your-project:agent-chat']} env={{ RUNTIME_CONFIG_APP_ID: '<app-id>', AGENT_ACCESS_TOKEN: '<access-token>' }} />
306
+
307
+ You can obtain an access token using the AWS CLI's `cognito-idp admin-initiate-auth` command, for example:
308
+
309
+ ```bash
310
+ aws cognito-idp admin-initiate-auth \
311
+ --user-pool-id <user-pool-id> \
312
+ --client-id <user-pool-client-id> \
313
+ --auth-flow ADMIN_NO_SRP_AUTH \
314
+ --auth-parameters USERNAME=<username>,PASSWORD=<password> \
315
+ --query 'AuthenticationResult.AccessToken' \
316
+ --output text
317
+ ```
318
+ </TabItem>
319
+ </Tabs>
320
+ </OptionFilter>
277
321
 
278
322
  <OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment details">
279
323
  ## Deploying Your Agent to Bedrock AgentCore Runtime
@@ -434,3 +478,73 @@ To invoke your AG-UI agent from a React website, use the <Link path="/guides/con
434
478
 
435
479
  Refer to the <Link path="/guides/connection/react-agui">`connection` generator guide</Link> for details about how the connection is set up.
436
480
  </OptionFilter>
481
+
482
+ ## Connections
483
+
484
+ Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:
485
+
486
+ <CardGrid>
487
+ <ConnectionCard
488
+ title="React to TypeScript Agent"
489
+ description="Call a TypeScript Agent from a React website"
490
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-ts-agent`}
491
+ source="react"
492
+ target="strands"
493
+ targetBadge="typescript"
494
+ />
495
+ <ConnectionCard
496
+ title="React to AG-UI Agent"
497
+ description="Call an Agent exposing the AG-UI protocol from a React website via CopilotKit"
498
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-agui`}
499
+ source="react"
500
+ target="copilotkit"
501
+ />
502
+ <ConnectionCard
503
+ title="TypeScript Agent to MCP"
504
+ description="Connect a TypeScript Agent to an MCP server"
505
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-mcp`}
506
+ source="strands"
507
+ sourceBadge="typescript"
508
+ target="mcp"
509
+ />
510
+ <ConnectionCard
511
+ title="TypeScript Agent to A2A Agent"
512
+ description="Connect a TypeScript Agent to a remote A2A agent"
513
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-a2a`}
514
+ source="strands"
515
+ sourceBadge="typescript"
516
+ target="a2a"
517
+ />
518
+ <ConnectionCard
519
+ title="Python Agent to A2A Agent"
520
+ description="Connect a Python Agent to a remote A2A agent"
521
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-a2a`}
522
+ source="strands"
523
+ sourceBadge="python"
524
+ target="a2a"
525
+ />
526
+ <ConnectionCard
527
+ title="TypeScript Agent to Relational Database"
528
+ description="Connect a TypeScript Agent to an Aurora relational database"
529
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-rdb`}
530
+ source="strands"
531
+ sourceBadge="typescript"
532
+ target="aurora"
533
+ />
534
+ <ConnectionCard
535
+ title="TypeScript Agent to TypeScript DynamoDB"
536
+ description="Connect a TypeScript Agent to a DynamoDB table"
537
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-dynamodb`}
538
+ source="strands"
539
+ sourceBadge="typescript"
540
+ target="dynamodb"
541
+ />
542
+ <ConnectionCard
543
+ title="TypeScript Agent to AgentCore Gateway"
544
+ description="Connect a TypeScript Agent to an AgentCore Gateway"
545
+ href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-gateway`}
546
+ source="strands"
547
+ sourceBadge="typescript"
548
+ target="agentcore"
549
+ />
550
+ </CardGrid>