@aws/nx-plugin-mcp 0.120.0 → 0.121.0

package/docs/guides/connection/react-trpc.mdx

@@ -0,0 +1,447 @@
+---
+title: React to tRPC
+description: Connect a React website to a tRPC API
+when:
+  sourceType: react
+  targetType: ts#trpc-api
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+
+Nx Plugin for AWS provides a generator to quickly integrate your <Link path="guides/trpc">tRPC API</Link> with a React website. It sets up all necessary configuration for connecting to your tRPC backends, including AWS IAM and Cognito authentication support and proper error handling. The integration provides full end-to-end type safety between your frontend and tRPC backend(s).
+
+## Prerequisites
+
+Before using this generator, ensure your React application has:
+
+1. A `main.tsx` file that renders your application
+2. An `<App/>` JSX element where the tRPC provider will be automatically injected
+3. A working tRPC API (generated using the tRPC API generator)
+4. Cognito Auth added via the <Link path="/guides/react-website-auth">`ts#react-website-auth` generator</Link> if connecting an API which uses Cognito or IAM auth
+
+<details>
+<summary>Example of required `main.tsx` structure</summary>
+
+```tsx
+import { StrictMode } from 'react';
+import * as ReactDOM from 'react-dom/client';
+import App from './app/app';
+
+const root = ReactDOM.createRoot(
+  document.getElementById('root') as HTMLElement,
+);
+root.render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
+```
+
+</details>
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator creates the following structure in your React application:
+
+<FileTree>
+
+- src
+  - components
+    - \<ApiName>ClientProvider.tsx Sets up the tRPC clients and bindings to your backend schema(s). ApiName will resolve to the name of the API
+    - QueryClientProvider.tsx TanStack React Query client provider
+  - hooks
+    - useSigV4.tsx Hook for signing HTTP requests with SigV4 (IAM only)
+    - use\<ApiName>.tsx A hook returning the tRPC options proxy for TanStack Query integration
+    - use\<ApiName>Client.tsx A hook returning the vanilla tRPC client for direct API calls
+
+</FileTree>
+
+Additionally, it installs the required dependencies:
+
+  - `@trpc/client`
+  - `@trpc/tanstack-react-query`
+  - `@tanstack/react-query`
+  - `aws4fetch` (if using IAM auth)
+  - `event-source-polyfill` (if using REST API, for subscription support)
+
+## Using the Generated Code
+
+### Using the tRPC Options Proxy Hook
+
+The generator provides a `use<ApiName>` hook that returns a [tRPC options proxy](https://trpc.io/docs/client/tanstack-react-query) for use with TanStack Query hooks like `useQuery` and `useMutation`:
+
+```tsx {5,8,11}
+import { useQuery, useMutation } from '@tanstack/react-query';
+import { useMyApi } from './hooks/useMyApi';
+
+function MyComponent() {
+  const trpc = useMyApi();
+
+  // Example query
+  const { data, isLoading, error } = useQuery(trpc.users.list.queryOptions());
+
+  // Example mutation
+  const mutation = useMutation(trpc.users.create.mutationOptions());
+
+  const handleCreate = () => {
+    mutation.mutate({
+      name: 'John Doe',
+      email: 'john@example.com',
+    });
+  };
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <ul>
+      {data.map((user) => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Using the Vanilla tRPC Client
+
+The `use<ApiName>Client` hook provides access to the [vanilla tRPC client](https://trpc.io/docs/client/vanilla), which is useful for imperative API calls and subscriptions:
+
+```tsx {2,5,8,11}
+import { useState } from 'react';
+import { useMyApiClient } from './hooks/useMyApi';
+
+function MyComponent() {
+  const client = useMyApiClient();
+
+  const handleClick = async () => {
+    const result = await client.echo.query({ message: 'Hello!' });
+    console.log(result);
+
+    const mutationResult = await client.users.create.mutate({ name: 'Jane' });
+    console.log(mutationResult);
+  };
+
+  return <button onClick={handleClick}>Call API</button>;
+}
+```
+
+### Error Handling
+
+The integration includes built-in error handling that properly processes tRPC errors:
+
+```tsx {4, 6}
+function MyComponent() {
+  const trpc = useMyApi();
+
+  const { data, error } = useQuery(trpc.users.list.queryOptions());
+
+  if (error) {
+    return (
+      <div>
+        <h2>Error occurred:</h2>
+        <p>{error.message}</p>
+        {error.data?.code && <p>Code: {error.data.code}</p>}
+      </div>
+    );
+  }
+
+  return (
+    <ul>
+      {data.map((user) => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Subscriptions (Streaming)
+
+:::caution[Subscriptions Compute Type]
+Subscriptions are only supported when the tRPC API uses `ServerlessApiGatewayRestApi` (REST API) as the compute type. API Gateway HTTP APIs do not support response streaming.
+:::
+
+When connecting to a REST API tRPC backend, the generated client is automatically configured with a `splitLink` that routes subscription operations through `httpSubscriptionLink` (using SSE) and regular queries/mutations through `httpLink`. This means subscriptions work out of the box with no additional configuration.
+
+For information on how to define subscription procedures in your backend, see the <Link path="guides/trpc">`ts#trpc-api` generator guide</Link>.
+
+#### Using the useSubscription Hook
+
+You can consume subscriptions using the `useSubscription` hook with `subscriptionOptions` from the options proxy:
+
+```tsx {1-2,7-22}
+import { useSubscription } from '@trpc/tanstack-react-query';
+import { useMyApi } from './hooks/useMyApi';
+
+function StreamingComponent() {
+  const trpc = useMyApi();
+
+  const subscription = useSubscription(
+    trpc.myStream.subscriptionOptions(
+      { query: 'hello' },
+      {
+        enabled: true,
+        onStarted: () => {
+          console.log('Subscription started');
+        },
+        onData: (data) => {
+          console.log('Received:', data.text);
+        },
+        onError: (error) => {
+          console.error('Subscription error:', error);
+        },
+      },
+    ),
+  );
+
+  return (
+    <div>
+      <p>Status: {subscription.status}</p>
+      {subscription.data && <p>Latest: {subscription.data.text}</p>}
+      {subscription.error && <p>Error: {subscription.error.message}</p>}
+      <button onClick={() => subscription.reset()}>Reset</button>
+    </div>
+  );
+}
+```
+
+The `subscription` object provides:
+
+- `subscription.data` — the most recently received data
+- `subscription.error` — the most recently received error
+- `subscription.status` — one of `'idle'`, `'connecting'`, `'pending'`, or `'error'`
+- `subscription.reset()` — resets the subscription (useful for recovering from errors)
+
+#### Using the Vanilla Client
+
+Alternatively, you can use the vanilla tRPC client via the `use<ApiName>Client` hook for more control over the subscription lifecycle:
+
+```tsx {2,5,9-22,25}
+import { useState, useEffect } from 'react';
+import { useMyApiClient } from './hooks/useMyApi';
+
+function StreamingComponent() {
+  const client = useMyApiClient();
+  const [messages, setMessages] = useState<string[]>([]);
+
+  useEffect(() => {
+    const subscription = client.myStream.subscribe(
+      { query: 'hello' },
+      {
+        onData: (data) => {
+          setMessages((prev) => [...prev, data.text]);
+        },
+        onComplete: () => {
+          console.log('Stream complete');
+        },
+        onError: (error) => {
+          console.error('Stream error:', error);
+        },
+      },
+    );
+
+    // Clean up the subscription on unmount
+    return () => subscription.unsubscribe();
+  }, [client]);
+
+  return (
+    <ul>
+      {messages.map((msg, i) => (
+        <li key={i}>{msg}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Best Practices
+
+### Handle Loading States
+
+Always handle loading and error states for a better user experience:
+
+```tsx {6}
+function UserList() {
+  const trpc = useMyApi();
+
+  const users = useQuery(trpc.users.list.queryOptions());
+
+  if (users.isLoading) {
+    return <LoadingSpinner />;
+  }
+
+  if (users.error) {
+    return <ErrorMessage error={users.error} />;
+  }
+
+  return (
+    <ul>
+      {users.data.map((user) => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Optimistic Updates
+
+Use optimistic updates for a better user experience:
+
+```tsx {15-17,20-22,28-31}
+import { useQueryClient, useQuery, useMutation } from '@tanstack/react-query';
+
+function UserList() {
+  const trpc = useMyApi();
+  const users = useQuery(trpc.users.list.queryOptions());
+  const queryClient = useQueryClient();
+
+  const deleteMutation = useMutation(
+    trpc.users.delete.mutationOptions({
+      onMutate: async (userId) => {
+        // Cancel outgoing fetches
+        await queryClient.cancelQueries(trpc.users.list.queryFilter());
+
+        // Get snapshot of current data
+        const previousUsers = queryClient.getQueryData(
+          trpc.users.list.queryKey(),
+        );
+
+        // Optimistically remove the user
+        queryClient.setQueryData(trpc.users.list.queryKey(), (old) =>
+          old?.filter((user) => user.id !== userId),
+        );
+
+        return { previousUsers };
+      },
+      onError: (err, userId, context) => {
+        // Restore previous data on error
+        queryClient.setQueryData(
+          trpc.users.list.queryKey(),
+          context?.previousUsers,
+        );
+      },
+    }),
+  );
+
+  return (
+    <ul>
+      {users.map((user) => (
+        <li key={user.id}>
+          {user.name}
+          <button onClick={() => deleteMutation.mutate(user.id)}>Delete</button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Prefetching Data
+
+Prefetch data for better performance:
+
+```tsx {8}
+function UserList() {
+  const trpc = useMyApi();
+  const users = useQuery(trpc.users.list.queryOptions());
+  const queryClient = useQueryClient();
+
+  // Prefetch user details on hover
+  const prefetchUser = async (userId: string) => {
+    await queryClient.prefetchQuery(trpc.users.getById.queryOptions(userId));
+  };
+
+  return (
+    <ul>
+      {users.map((user) => (
+        <li key={user.id} onMouseEnter={() => prefetchUser(user.id)}>
+          <Link to={`/users/${user.id}`}>{user.name}</Link>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Infinite Queries
+
+Handle pagination with infinite queries:
+
+```tsx {5-12}
+function UserList() {
+  const trpc = useMyApi();
+
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
+    useInfiniteQuery(
+      trpc.users.list.infiniteQueryOptions(
+        { limit: 10 },
+        {
+          getNextPageParam: (lastPage) => lastPage.nextCursor,
+        },
+      ),
+    );
+
+  return (
+    <div>
+      {data?.pages.map((page) =>
+        page.users.map((user) => <UserCard key={user.id} user={user} />),
+      )}
+
+      {hasNextPage && (
+        <button onClick={() => fetchNextPage()} disabled={isFetchingNextPage}>
+          {isFetchingNextPage ? 'Loading...' : 'Load More'}
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+It is important to note that infinite queries can only be used for procedures with an input property named `cursor`.
+
+## Type Safety
+
+The integration provides complete end-to-end type safety. Your IDE will provide full autocompletion and type checking for all your API calls:
+
+```tsx
+function UserForm() {
+  const trpc = useMyApi();
+
+  // ✅ Input is fully typed
+  const createUser = trpc.users.create.useMutation();
+
+  const handleSubmit = (data: CreateUserInput) => {
+    // ✅ Type error if input doesn't match schema
+    createUser.mutate(data);
+  };
+
+  return <form onSubmit={handleSubmit}>{/* ... */}</form>;
+}
+```
+
+The types are automatically inferred from your backend's router and schema definitions, ensuring that any changes to your API are immediately reflected in your frontend code without the need to build.
+
+## Custom Auth
+
+If your tRPC API uses `Custom` authentication (Lambda Authorizer), the generated client provider includes placeholder `headers` where you must add the authorization headers your authorizer expects. Look for the `// TODO: Add headers required by your custom authorizer` comments in the generated `<ApiName>ClientProvider.tsx` and replace them with your token or API key logic.
+
+## More Information
+
+For more information, please refer to:
+
+- [tRPC TanStack React Query Integration](https://trpc.io/docs/client/tanstack-react-query)
+- [tRPC Vanilla Client](https://trpc.io/docs/client/vanilla)
+- [TanStack Query documentation](https://tanstack.com/query/v5)

package/docs/guides/connection/react-ts-agent.mdx

@@ -0,0 +1,198 @@
+---
+title: React to TypeScript Agent
+description: Connect a React website to a TypeScript Agent
+when:
+  sourceType: react
+  targetType: ts#agent
+  protocol: HTTP
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Snippet from '@components/snippet.astro';
+
+Nx Plugin for AWS provides a generator to quickly integrate your <Link path="guides/ts-agent">TypeScript Agent</Link> with a React website. It sets up all necessary configuration for connecting to your agent via tRPC over WebSocket, including AWS IAM and Cognito authentication support. The integration provides full end-to-end type safety between your frontend and the agent's tRPC router.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A React website (generated using the <Link path="guides/react-website">`ts#react-website` generator</Link>)
+2. A TypeScript Agent (generated using the <Link path="guides/ts-agent">`ts#agent` generator</Link>)
+3. Cognito Auth added via the <Link path="/guides/react-website-auth">`ts#react-website-auth` generator</Link>
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+You will be prompted to select your React website as the source project and the project containing your Agent as the target project. If your target project contains multiple components (such as multiple agents or other component types), you will be prompted to specify a `targetComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator creates the following structure in your React application:
+
+<FileTree>
+
+- src
+  - components
+    - \<AgentName>AgentClientProvider.tsx Sets up the tRPC WebSocket client and bindings to your agent's tRPC router
+    - QueryClientProvider.tsx TanStack React Query client provider
+  - hooks
+    - useSigV4.tsx Hook for signing requests with SigV4 (IAM only)
+    - use\<AgentName>Agent.tsx Hooks returning the tRPC options proxy and vanilla tRPC client
+
+</FileTree>
+
+Additionally, it installs the required dependencies:
+
+  - `@trpc/client`
+  - `@trpc/tanstack-react-query`
+  - `@tanstack/react-query`
+  - `aws4fetch` (if using IAM auth)
+
+## How It Works
+
+### WebSocket Connection
+
+The generated client connects to your Agent via tRPC over WebSocket. The agent exposes a tRPC router (including the `invoke` subscription for streaming agent responses) over a WebSocket endpoint.
+
+- **Deployed**: The agent runtime ARN is loaded from <Link path="guides/runtime-config">Runtime Configuration</Link>. Running this connection generator also patches the agent's generated CDK/Terraform construct to publish its ARN to the website's `runtime-config.json` (under the `connection` namespace), so only agents you explicitly connect are exposed to the frontend. The ARN is converted to a WebSocket URL following the Bedrock AgentCore Runtime WebSocket protocol: `wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/ws`
+- **Local development**: When running with `serve-local`, the runtime config override sets the value to a local `ws://` URL (e.g., `ws://localhost:8081/ws`), and the client connects directly
+
+### Authentication
+
+The generated code handles authentication depending on your agent's configuration:
+
+- **IAM** (default): Uses AWS SigV4 presigned URLs to authenticate the WebSocket connection. Credentials are obtained from the Cognito Identity Pool configured with your website's auth. In `serve-local` mode, signing is automatically skipped when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
+- **Cognito**: Embeds the JWT access token in the `Sec-WebSocket-Protocol` header as a base64url-encoded bearer token, following the [AgentCore WebSocket auth protocol](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-websocket.html)
+
+
+## Infrastructure
+
+<Snippet name="connection/react-agent-infrastructure" parentHeading="Infrastructure" />
+
+## Using the Generated Code
+
+### Using TanStack Query
+
+The most common use case is streaming the agent's response using the `invoke` subscription with the `use<AgentName>Agent` hook, which returns a [tRPC options proxy](https://trpc.io/docs/client/tanstack-react-query) for use with TanStack Query:
+
+```tsx {1-2,7-22}
+import { useSubscription } from '@trpc/tanstack-react-query';
+import { useMyAgentAgent } from './hooks/useMyAgentAgent';
+
+function ChatComponent() {
+  const trpc = useMyAgentAgent();
+
+  const subscription = useSubscription(
+    trpc.invoke.subscriptionOptions(
+      { message: 'What can you help me with?' },
+      {
+        enabled: true,
+        onStarted: () => {
+          console.log('Agent started responding');
+        },
+        onData: (token) => {
+          console.log('Received token:', token);
+        },
+        onError: (error) => {
+          console.error('Agent error:', error);
+        },
+      },
+    ),
+  );
+
+  return (
+    <div>
+      <p>Status: {subscription.status}</p>
+      {subscription.data && <p>Latest token: {subscription.data}</p>}
+      {subscription.error && <p>Error: {subscription.error.message}</p>}
+    </div>
+  );
+}
+```
+
+:::note[tRPC Options Proxy]
+For more details on the tRPC options proxy and TanStack Query integration, see the [tRPC TanStack React Query documentation](https://trpc.io/docs/client/tanstack-react-query).
+:::
+
+### Using the Vanilla tRPC Client
+
+The `use<AgentName>AgentClient` hook provides access to the [vanilla tRPC client](https://trpc.io/docs/client/vanilla) for more control over the subscription lifecycle:
+
+```tsx {2,5,9-22,25}
+import { useState } from 'react';
+import { useMyAgentAgentClient } from './hooks/useMyAgentAgent';
+
+function ChatComponent() {
+  const client = useMyAgentAgentClient();
+  const [messages, setMessages] = useState<string[]>([]);
+
+  const sendMessage = (message: string) => {
+    const subscription = client.invoke.subscribe(
+      { message },
+      {
+        onData: (token) => {
+          setMessages((prev) => [...prev, token]);
+        },
+        onComplete: () => {
+          console.log('Agent finished');
+        },
+        onError: (error) => {
+          console.error('Error:', error);
+        },
+      },
+    );
+
+    // Clean up when done
+    return () => subscription.unsubscribe();
+  };
+
+  return (
+    <div>
+      <button onClick={() => sendMessage('Hello!')}>Send</button>
+      <div>
+        {messages.map((msg, i) => (
+          <span key={i}>{msg}</span>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+:::note[Vanilla tRPC Client]
+For more details on the vanilla tRPC client, see the [tRPC Vanilla Client documentation](https://trpc.io/docs/client/vanilla).
+:::
+
+## Local Development
+
+The connection generator automatically configures `serve-local` integration for your react website:
+
+1. Running `nx serve-local <website>` will also start the agent's local server
+2. The runtime config is overridden to point to the local WebSocket URL (e.g., `ws://localhost:8081/ws`)
+3. Like with connected APIs, authentication is skipped in `serve-local` mode when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
+
+:::tip[Hot Reloading]
+The website and connected agent will hot-reload, enabling you to quickly iterate on both together without deploying to AWS.
+:::
+
+## Type Safety
+
+The integration provides complete end-to-end type safety. Your IDE will provide full autocompletion and type checking for all agent procedure calls. The types are automatically inferred from your agent's tRPC router definition, ensuring that any changes to your agent's API are immediately reflected in your frontend code.
+
+## More Information
+
+For more information, please refer to:
+
+- <Link path="guides/ts-agent">TypeScript Agent Guide</Link>
+- [tRPC WebSocket Client](https://trpc.io/docs/client/links/wsLink)
+- [tRPC TanStack React Query Integration](https://trpc.io/docs/client/tanstack-react-query)
+- [Bedrock AgentCore Runtime WebSocket](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-websocket.html)