@aws/nx-plugin-mcp 1.0.0-rc.96 → 1.0.0-rc.98

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

@@ -126,6 +126,10 @@ For more fine-grained control, you can use the `watch-generate:<ApiName>-client`
 />
 :::
 
+:::note[The dev target requires the Nx Daemon]
+The `dev` target hot-reloads local dev servers. Many of these rely on [`nx watch`](https://nx.dev/docs/guides/tasks--caching/workspace-watching) to achieve this, which requires the [Nx Daemon](https://nx.dev/docs/concepts/nx-daemon) to be enabled.
+:::
+
 ### Using the API Hook
 
 The generator provides a `use<ApiName>` hook which you can use to call your API with TanStack Query.
@@ -143,13 +147,15 @@ function MyComponent() {
   const api = useMyApi();
   const item = useQuery(api.getItem.queryOptions({ itemId: 'some-id' }));
 
-  if (item.isLoading) return <div>Loading...</div>;
-  if (item.isError) return <div>Error: {item.error.message}</div>;
+  if (item.isPending) return <div>Loading...</div>;
+  if (item.isError) return <div>Error: {JSON.stringify(item.error.error)}</div>;
 
   return <div>Item: {item.data.name}</div>;
 }
 ```
 
+The error is a discriminated union of `{ status, error }` objects rather than an `Error`, so there is no top-level `message` to render. Narrow on `status` to read a specific response body — see [Error Handling](#error-handling) below.
+
 <Drawer title="Using the API client directly" trigger="Click here for an example using the vanilla client directly.">
 ```tsx {5,13}
 import { useState, useEffect } from 'react';
@@ -219,7 +225,7 @@ function CreateItemForm() {
 
       {createItem.isError && (
         <div className="error">
-          Error: {createItem.error.message}
+          Error: {JSON.stringify(createItem.error.error)}
         </div>
       )}
     </form>
@@ -245,7 +251,7 @@ const createItem = useMutation({
   onSettled: () => {
     // This will run when the mutation completes (success or error)
     // Good place to invalidate queries that might be affected
-    queryClient.invalidateQueries({ queryKey: api.listItems.queryKey() });
+    queryClient.invalidateQueries({ queryKey: api.listItems.queryKey({}) });
   }
 });
 ```
@@ -331,12 +337,12 @@ function ItemList() {
       }),
   });
 
-  if (items.isLoading) {
+  if (items.isPending) {
     return <LoadingSpinner />;
   }
 
   if (items.isError) {
-    return <ErrorMessage message={items.error.message} />;
+    return <ErrorMessage message={JSON.stringify(items.error.error)} />;
   }
 
   return (
@@ -456,7 +462,9 @@ function ItemList() {
 
 ### Error Handling
 
-The integration includes built-in error handling with typed error responses. An `<operation-name>Error` type is generated which encapsulates the possible error responses defined in the Smithy model. Each error has a `status` and `error` property, and by checking the value of `status` you can narrow to a specific type of error.
+The integration includes built-in error handling with typed error responses. An `<OperationName>Error` type is generated which is a union of one `<OperationName><StatusCode>Error` member per error status the operation models. Each member has a `status` and an `error` property, so switching on `status` narrows `error` to that status's payload.
+
+The example below assumes `CreateItem` models the [error structures defined further down this page](#errors) — a `422` `InvalidRequestError`, a `403` `UnauthorizedError` and a `500` `InternalServerError`. Only the statuses your model declares appear in the union, so a `case` for a status you haven't modelled is a compile error.
 
 ```tsx {12}
 import { useMutation } from '@tanstack/react-query';
@@ -471,8 +479,8 @@ function MyComponent() {
 
   if (createItem.error) {
     switch (createItem.error.status) {
-      case 400:
-        // error.error is typed as CreateItem400Response
+      case 422:
+        // error.error is typed as InvalidRequestErrorResponseContent
         return (
           <div>
             <h2>Invalid input:</h2>
@@ -480,7 +488,7 @@ function MyComponent() {
           </div>
         );
       case 403:
-        // error.error is typed as CreateItem403Response
+        // error.error is typed as UnauthorizedErrorResponseContent
         return (
           <div>
             <h2>Not authorized:</h2>
@@ -488,8 +496,7 @@ function MyComponent() {
           </div>
         );
       case 500:
-      case 502:
-        // error.error is typed as CreateItem5XXResponse
+        // error.error is typed as InternalServerErrorResponseContent
         return (
           <div>
             <h2>Server error:</h2>
@@ -520,8 +527,8 @@ function MyComponent() {
 
   if (error) {
     switch (error.status) {
-      case 400:
-        // error.error is typed as CreateItem400Response
+      case 422:
+        // error.error is typed as InvalidRequestErrorResponseContent
         return (
           <div>
             <h2>Invalid input:</h2>
@@ -529,7 +536,7 @@ function MyComponent() {
           </div>
         );
       case 403:
-        // error.error is typed as CreateItem403Response
+        // error.error is typed as UnauthorizedErrorResponseContent
         return (
           <div>
             <h2>Not authorized:</h2>
@@ -537,8 +544,7 @@ function MyComponent() {
           </div>
         );
       case 500:
-      case 502:
-        // error.error is typed as CreateItem5XXResponse
+        // error.error is typed as InternalServerErrorResponseContent
         return (
           <div>
             <h2>Server error:</h2>
@@ -573,21 +579,21 @@ These map to OpenAPI vendor extensions using the [`@specificationExtension` trai
 
 #### @query
 
-Then Apply the `@query` trait to your Smithy operation to force it to be treated as a query:
+Apply the `@query` trait to your Smithy operation to force it to be treated as a query:
 
 ```smithy
-@http(method: "POST", uri: "/items")
+@http(method: "POST", uri: "/search-items")
 @query
-operation ListItems {
-    input: ListItemsInput
-    output: ListItemsOutput
+operation SearchItems {
+    input: SearchItemsInput
+    output: SearchItemsOutput
 }
 ```
 
 The generated hook will provide `queryOptions` even though it uses the `POST` HTTP method:
 
 ```tsx
-const items = useQuery(api.listItems.queryOptions());
+const items = useQuery(api.searchItems.queryOptions({ term: 'widget' }));
 ```
 
 #### @mutation
@@ -607,6 +613,8 @@ The generated hook will provide `mutationOptions` even though it uses the `GET`
 
 ```tsx
 const startProcessing = useMutation(api.startProcessing.mutationOptions());
+
+startProcessing.mutate({ id: 'some-id' });
 ```
 
 ### Custom Pagination Cursor
@@ -616,39 +624,60 @@ By default, the generated hooks assume cursor-based pagination with a parameter
 Apply the `@cursor` trait with `inputToken` to change the name of the input parameter used for the pagination token:
 
 ```smithy
-@http(method: "GET", uri: "/items")
+@http(method: "GET", uri: "/paged-items")
 @cursor(inputToken: "nextToken")
-operation ListItems {
+operation ListPagedItems {
     input := {
+      @httpQuery("nextToken")
       nextToken: String
+      @httpQuery("limit")
       limit: Integer
     }
     output := {
+      @required
       items: ItemList
       nextToken: String
     }
 }
 ```
 
+`infiniteQueryOptions` then pages on `nextToken`:
+
+```tsx
+const items = useInfiniteQuery({
+  ...api.listPagedItems.infiniteQueryOptions(
+    { limit: 10 },
+    { getNextPageParam: (lastPage) => lastPage.nextToken || undefined },
+  ),
+});
+```
+
 If you would not like to generate `infiniteQueryOptions` for an operation which has an input parameter named `cursor`, you can disable cursor-based pagination:
 
 ```smithy
+@http(method: "GET", uri: "/unpaged-items")
 @cursor(enabled: false)
-operation ListItems {
+operation ListUnpagedItems {
     input := {
       // Input parameter named 'cursor' will cause this operation to be treated as a paginated operation by default
+      @httpQuery("cursor")
       cursor: String
     }
     output := {
-      ...
+      @required
+      items: ItemList
     }
 }
 ```
 
+`api.listUnpagedItems` then only provides `queryOptions`, `queryKey` and `queryFilter`.
+
 ### Grouping Operations
 
 The generated hooks and client methods are automatically organized based on the [`@tags` trait](https://smithy.io/2.0/spec/documentation-traits.html#tags-trait) in your Smithy operations. Operations with the same tags are grouped together, which helps keep your API calls organized and provides better code completion in your IDE.
 
+Within a group each operation keeps its own camelCased name, so an operation named `ListItems` tagged `"items"` is reached at `api.items.listItems` — not `api.items.list`.
+
 For example, with this Smithy model:
 
 ```smithy
@@ -657,27 +686,51 @@ service MyService {
 }
 
 @tags(["items"])
+@http(method: "GET", uri: "/items")
+@readonly
 operation ListItems {
-    input: ListItemsInput
-    output: ListItemsOutput
+    input := {}
+    output := {
+      @required
+      items: ItemList
+    }
 }
 
 @tags(["items"])
+@http(method: "POST", uri: "/items")
 operation CreateItem {
-    input: CreateItemInput
-    output: CreateItemOutput
+    input := {
+      @required
+      name: String
+    }
+    output := {
+      @required
+      id: String
+    }
 }
 
 @tags(["users"])
+@http(method: "GET", uri: "/users")
+@readonly
 operation ListUsers {
-    input: ListUsersInput
-    output: ListUsersOutput
+    input := {}
+    output := {
+      @required
+      users: UserList
+    }
 }
 
 @tags(["users"])
+@http(method: "POST", uri: "/users")
 operation CreateUser {
-    input: CreateUserInput
-    output: CreateUserOutput
+    input := {
+      @required
+      name: String
+    }
+    output := {
+      @required
+      id: String
+    }
 }
 ```
 
@@ -706,7 +759,7 @@ function ItemsAndUsers() {
     <div>
       <h2>Items</h2>
       <ul>
-        {items.data?.map(item => (
+        {items.data?.items.map(item => (
           <li key={item.id}>{item.name}</li>
         ))}
       </ul>
@@ -714,7 +767,7 @@ function ItemsAndUsers() {
 
       <h2>Users</h2>
       <ul>
-        {users.data?.map(user => (
+        {users.data?.users.map(user => (
           <li key={user.id}>{user.name}</li>
         ))}
       </ul>
@@ -805,7 +858,7 @@ Define your error structures in your Smithy model:
 
 ```smithy
 @error("client")
-@httpError(400)
+@httpError(422)
 structure InvalidRequestError {
     @required
     message: String
@@ -842,6 +895,10 @@ structure FieldError {
 }
 ```
 
+:::caution[400 is taken]
+Your service already declares Smithy's `ValidationException` on `400`, so every operation gets a `400` case carrying `ValidationExceptionResponseContent`. Give your own client errors a different status (`422` above) — two errors on the same status collide and only one payload reaches the generated client.
+:::
+
 #### Adding Errors to Operations
 
 Specify which errors your operations can return:
@@ -884,37 +941,21 @@ import { useMutation, useQuery } from '@tanstack/react-query';
 function ItemComponent() {
   const api = useMyApi();
 
-  // Query with typed error handling
-  const getItem = useQuery({
-    ...api.getItem.queryOptions({ itemId: '123' }),
-    onError: (error) => {
-      // Error is typed based on the errors in your Smithy model
-      switch (error.status) {
-        case 404:
-          // error.error is typed as ItemNotFoundError
-          console.error('Not found:', error.error.message);
-          break;
-        case 500:
-          // error.error is typed as InternalServerError
-          console.error('Server error:', error.error.message);
-          console.error('Trace ID:', error.error.traceId);
-          break;
-      }
-    }
-  });
+  const getItem = useQuery(api.getItem.queryOptions({ itemId: '123' }));
 
   // Mutation with typed error handling
   const createItem = useMutation({
     ...api.createItem.mutationOptions(),
     onError: (error) => {
+      // Error is typed based on the errors in your Smithy model
       switch (error.status) {
-        case 400:
-          // error.error is typed as InvalidRequestError
+        case 422:
+          // error.error is typed as InvalidRequestErrorResponseContent
           console.error('Validation error:', error.error.message);
           console.error('Field errors:', error.error.fieldErrors);
           break;
         case 403:
-          // error.error is typed as UnauthorizedError
+          // error.error is typed as UnauthorizedErrorResponseContent
           console.error('Unauthorized:', error.error.reason);
           break;
       }
@@ -923,10 +964,13 @@ function ItemComponent() {
 
   // Component rendering with error handling
   if (getItem.isError) {
-    if (getItem.error.status === 404) {
-      return <NotFoundMessage message={getItem.error.error.message} />;
-    } else if (getItem.error.status === 500) {
-      return <ErrorMessage message={getItem.error.error.message} />;
+    switch (getItem.error.status) {
+      case 404:
+        // error.error is typed as ItemNotFoundErrorResponseContent
+        return <NotFoundMessage message={getItem.error.error.message} />;
+      case 500:
+        // error.error is typed as InternalServerErrorResponseContent
+        return <ErrorMessage message={getItem.error.error.message} />;
     }
   }
 
@@ -962,11 +1006,11 @@ function ItemComponent() {
 
         switch (err.status) {
           case 404:
-            // err.error is typed as ItemNotFoundError
+            // err.error is typed as ItemNotFoundErrorResponseContent
             console.error('Not found:', err.error.message);
             break;
           case 500:
-            // err.error is typed as InternalServerError
+            // err.error is typed as InternalServerErrorResponseContent
             console.error('Server error:', err.error.message);
             console.error('Trace ID:', err.error.traceId);
             break;
@@ -987,13 +1031,13 @@ function ItemComponent() {
       const err = e as CreateItemError;
 
       switch (err.status) {
-        case 400:
-          // err.error is typed as InvalidRequestError
+        case 422:
+          // err.error is typed as InvalidRequestErrorResponseContent
           console.error('Validation error:', err.error.message);
           console.error('Field errors:', err.error.fieldErrors);
           break;
         case 403:
-          // err.error is typed as UnauthorizedError
+          // err.error is typed as UnauthorizedErrorResponseContent
           console.error('Unauthorized:', err.error.reason);
           break;
       }
@@ -1037,7 +1081,7 @@ import { useQuery } from '@tanstack/react-query';
 
 function ItemList() {
   const api = useMyApi();
-  const items = useQuery(api.listItems.queryOptions());
+  const items = useQuery(api.listItems.queryOptions({}));
 
   if (items.isLoading) {
     return <LoadingSpinner />;
@@ -1047,11 +1091,10 @@ function ItemList() {
     const err = items.error;
     switch (err.status) {
       case 403:
-        // err.error is typed as ListItems403Response
+        // err.error is typed as UnauthorizedErrorResponseContent
         return <ErrorMessage message={err.error.reason} />;
       case 500:
-      case 502:
-        // err.error is typed as ListItems5XXResponse
+        // err.error is typed as InternalServerErrorResponseContent
         return (
           <ErrorMessage
             message={err.error.message}
@@ -1064,7 +1107,7 @@ function ItemList() {
 
   return (
     <ul>
-      {items.data.map((item) => (
+      {items.data?.items.map((item) => (
         <li key={item.id}>{item.name}</li>
       ))}
     </ul>
@@ -1083,7 +1126,7 @@ function ItemList() {
   useEffect(() => {
     const fetchItems = async () => {
       try {
-        const data = await api.listItems();
+        const data = await api.listItems({});
         setItems(data);
       } catch (err) {
         setError(err);
@@ -1102,11 +1145,10 @@ function ItemList() {
     const err = error as ListItemsError;
     switch (err.status) {
       case 403:
-        // err.error is typed as ListItems403Response
+        // err.error is typed as UnauthorizedErrorResponseContent
         return <ErrorMessage message={err.error.reason} />;
       case 500:
-      case 502:
-        // err.error is typed as ListItems5XXResponse
+        // err.error is typed as InternalServerErrorResponseContent
         return (
           <ErrorMessage
             message={err.error.message}
@@ -1134,41 +1176,53 @@ Implement optimistic updates for a better user experience:
 
 ```tsx
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import type { ListItemsResponseContent } from '../generated/my-api/types.gen';
 
 function ItemList() {
   const api = useMyApi();
   const queryClient = useQueryClient();
 
   // Query to fetch items
-  const itemsQuery = useQuery(api.listItems.queryOptions());
+  const itemsQuery = useQuery(api.listItems.queryOptions({}));
 
   // Mutation for deleting items with optimistic updates
   const deleteMutation = useMutation({
     ...api.deleteItem.mutationOptions(),
-    onMutate: async (itemId) => {
+    onMutate: async ({ itemId }) => {
       // Cancel any outgoing refetches
-      await queryClient.cancelQueries({ queryKey: api.listItems.queryKey() });
+      await queryClient.cancelQueries({
+        queryKey: api.listItems.queryKey({}),
+      });
 
       // Snapshot the previous value
-      const previousItems = queryClient.getQueryData(api.listItems.queryKey());
+      const previousItems = queryClient.getQueryData<ListItemsResponseContent>(
+        api.listItems.queryKey({}),
+      );
 
       // Optimistically update to the new value
-      queryClient.setQueryData(
-        api.listItems.queryKey(),
-        (old) => old.filter((item) => item.id !== itemId)
+      queryClient.setQueryData<ListItemsResponseContent>(
+        api.listItems.queryKey({}),
+        (old) =>
+          old && {
+            ...old,
+            items: old.items.filter((item) => item.id !== itemId),
+          },
       );
 
       // Return a context object with the snapshot
       return { previousItems };
     },
-    onError: (err, itemId, context) => {
+    onError: (err, _input, context) => {
       // If the mutation fails, use the context returned from onMutate to roll back
-      queryClient.setQueryData(api.listItems.queryKey(), context.previousItems);
+      queryClient.setQueryData(
+        api.listItems.queryKey({}),
+        context?.previousItems,
+      );
       console.error('Failed to delete item:', err);
     },
     onSettled: () => {
       // Always refetch after error or success to ensure data is in sync with server
-      queryClient.invalidateQueries({ queryKey: api.listItems.queryKey() });
+      queryClient.invalidateQueries({ queryKey: api.listItems.queryKey({}) });
     },
   });
 
@@ -1182,11 +1236,11 @@ function ItemList() {
 
   return (
     <ul>
-      {itemsQuery.data.map((item) => (
+      {itemsQuery.data?.items.map((item) => (
         <li key={item.id}>
           {item.name}
           <button
-            onClick={() => deleteMutation.mutate(item.id)}
+            onClick={() => deleteMutation.mutate({ itemId: item.id })}
             disabled={deleteMutation.isPending}
           >
             {deleteMutation.isPending ? 'Deleting...' : 'Delete'}
@@ -1261,8 +1315,8 @@ function ItemForm() {
   if (createItem.error) {
     const error = createItem.error;
     switch (error.status) {
-      case 400:
-        // error.error is typed as InvalidRequestError
+      case 422:
+        // error.error is typed as InvalidRequestErrorResponseContent
         return (
           <FormError
             message="Invalid input"
@@ -1270,10 +1324,10 @@ function ItemForm() {
           />
         );
       case 403:
-        // error.error is typed as UnauthorizedError
+        // error.error is typed as UnauthorizedErrorResponseContent
         return <AuthError reason={error.error.reason} />;
       default:
-        // error.error is typed as InternalServerError for 500, etc.
+        // error.error is typed as InternalServerErrorResponseContent for 500, etc.
         return <ServerError message={error.error.message} />;
     }
   }
@@ -1309,16 +1363,16 @@ function ItemForm() {
       // ✅ Error type includes all possible error responses
       const err = e as CreateItemError;
       switch (err.status) {
-        case 400:
-          // err.error is typed as InvalidRequestError
+        case 422:
+          // err.error is typed as InvalidRequestErrorResponseContent
           console.error('Validation errors:', err.error.fieldErrors);
           break;
         case 403:
-          // err.error is typed as UnauthorizedError
+          // err.error is typed as UnauthorizedErrorResponseContent
           console.error('Not authorized:', err.error.reason);
           break;
         case 500:
-          // err.error is typed as InternalServerError
+          // err.error is typed as InternalServerErrorResponseContent
           console.error('Server error:', err.error.message);
           break;
       }
@@ -1329,7 +1383,7 @@ function ItemForm() {
   // Error UI can use type narrowing to handle different error types
   if (error) {
     switch (error.status) {
-      case 400:
+      case 422:
         return (
           <FormError
             message="Invalid input"

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

@@ -63,8 +63,7 @@ The generator creates the following structure in your React application:
     - 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
+    - use\<ApiName>.tsx Exports both `use<ApiName>`, returning the tRPC options proxy for TanStack Query integration, and `use<ApiName>Client`, returning the vanilla tRPC client for direct API calls
 
 </FileTree>
 
@@ -103,6 +102,8 @@ function MyComponent() {
   };
 
   if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!data) return null;
 
   return (
     <ul>
@@ -114,6 +115,8 @@ function MyComponent() {
 }
 ```
 
+`data` is `undefined` until the query resolves, so guard on it before dereferencing.
+
 ### 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:
@@ -157,6 +160,8 @@ function MyComponent() {
     );
   }
 
+  if (!data) return null;
+
   return (
     <ul>
       {data.map((user) => (
@@ -278,7 +283,7 @@ function UserList() {
 
   const users = useQuery(trpc.users.list.queryOptions());
 
-  if (users.isLoading) {
+  if (users.isPending) {
     return <LoadingSpinner />;
   }
 
@@ -338,7 +343,7 @@ function UserList() {
 
   return (
     <ul>
-      {users.map((user) => (
+      {users.data?.map((user) => (
         <li key={user.id}>
           {user.name}
           <button onClick={() => deleteMutation.mutate(user.id)}>Delete</button>
@@ -366,7 +371,7 @@ function UserList() {
 
   return (
     <ul>
-      {users.map((user) => (
+      {users.data?.map((user) => (
         <li key={user.id} onMouseEnter={() => prefetchUser(user.id)}>
           <Link to={`/users/${user.id}`}>{user.name}</Link>
         </li>
@@ -417,11 +422,13 @@ It is important to note that infinite queries can only be used for procedures wi
 The integration provides complete end-to-end type safety. Your IDE will provide full autocompletion and type checking for all your API calls:
 
 ```tsx
+import { useMutation } from '@tanstack/react-query';
+
 function UserForm() {
   const trpc = useMyApi();
 
   // ✅ Input is fully typed
-  const createUser = trpc.users.create.useMutation();
+  const createUser = useMutation(trpc.users.create.mutationOptions());
 
   const handleSubmit = (data: CreateUserInput) => {
     // ✅ Type error if input doesn't match schema