React a FastAPI

El generador connection proporciona una forma de integrar rápidamente tu sitio web React con tu backend FastAPI. Configura toda la configuración necesaria para conectarse a tus backends FastAPI de manera segura en cuanto a tipos, incluyendo la generación de cliente y hooks de TanStack Query, soporte de autenticación AWS IAM y Cognito, y manejo adecuado de errores.

Requisitos previos

Antes de usar este generador, asegúrate de que tu aplicación React tenga:

1. Un archivo main.tsx que renderice tu aplicación
2. Un backend FastAPI funcional (generado usando el generador FastAPI)
3. Cognito Auth agregado a través del generador ts#website#auth si conectas una API que usa autenticación Cognito o IAM

Ejemplo de estructura requerida de main.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>,
);

Uso

Ejecutar el generador

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - connection
5. Complete los parámetros requeridos
6. Haga clic en Generate

Opciones

Parámetro	Tipo	Predeterminado	Descripción
sourceProject Requerido	string	-	El proyecto de origen
targetProject Requerido	string	-	El proyecto de destino al que conectar
sourceComponent	string	-	El componente de origen desde el que conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Use '.' para seleccionar explícitamente el proyecto como origen.
targetComponent	string	-	El componente de destino al que conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Use '.' para seleccionar explícitamente el proyecto como destino.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del generador

El generador realizará cambios en los siguientes archivos en tu proyecto FastAPI:

• Directorioscripts

  • generate_open_api.py Agrega un script que genera una especificación OpenAPI para tu API
• project.json Se agrega un nuevo target al build que invoca el script de generación anterior

El generador realizará cambios en los siguientes archivos en tu aplicación React:

• Directoriosrc

  • Directoriocomponents

    • <ApiName>Provider.tsx Proveedor para tu cliente API
    • QueryClientProvider.tsx Proveedor de cliente TanStack React Query
  • Directoriohooks

    • use<ApiName>.tsx Agrega un hook para llamar a tu API con estado gestionado por TanStack Query
    • use<ApiName>Client.tsx Agrega un hook para instanciar el cliente API vanilla que puede llamar a tu API.
    • useSigV4.tsx Agrega un hook para firmar solicitudes HTTP con SigV4 (si seleccionaste autenticación IAM)
• project.json Se agrega un nuevo target al build que genera un cliente seguro en cuanto a tipos
• .gitignore Los archivos de cliente generados son ignorados por defecto

El generador también agregará Runtime Config a la infraestructura de tu sitio web si no está presente ya, lo que garantiza que la URL de la API para tu FastAPI esté disponible en el sitio web y se configure automáticamente mediante el hook use<ApiName>.tsx.

Generación de código

En tiempo de compilación, se genera un cliente seguro en cuanto a tipos a partir de la especificación OpenAPI de tu FastAPI. Esto agregará tres nuevos archivos a tu aplicación React:

• Directoriosrc

  • Directoriogenerated

    • Directorio<ApiName>

      • types.gen.ts Tipos generados a partir de los modelos pydantic definidos en tu FastAPI
      • client.gen.ts Cliente seguro en cuanto a tipos para llamar a tu API
      • options-proxy.gen.ts Proporciona métodos para crear opciones de hooks TanStack Query para interactuar con tu API usando TanStack Query

Cliente generado en Git

Por defecto, el cliente generado se ignora del control de versiones. Si prefieres incluirlo, puedes eliminar la entrada del archivo .gitignore de tu aplicación React, sin embargo, ten en cuenta que cualquier cambio manual en los archivos .gen.ts se sobrescribirá cuando se compile tu proyecto.

Usar el código generado

El cliente seguro en cuanto a tipos generado se puede usar para llamar a tu FastAPI desde tu aplicación React. Se recomienda hacer uso del cliente a través de los hooks TanStack Query, pero puedes usar el cliente vanilla si lo prefieres.

Regenerar código de cliente

Siempre que realices cambios en tu FastAPI, necesitas reconstruir tu proyecto para que esos cambios se reflejen en el cliente generado. Por ejemplo:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Auto-regeneración

Si estás trabajando activamente tanto en tu aplicación React como en FastAPI juntos, usa el target dev de la aplicación React que regenerará automáticamente el cliente cada vez que tu API cambie, además de recargar en caliente tu sitio web y el servidor FastAPI local:

pnpm

pnpm nx dev <WebsiteProject>

yarn

yarn nx dev <WebsiteProject>

npm

npx nx dev <WebsiteProject>

bun

bunx nx dev <WebsiteProject>

Para un control más detallado, puedes usar el target watch-generate:<ApiName>-client para tu aplicación React para regenerar el cliente cada vez que realices cambios en la API:

pnpm

pnpm nx run <WebsiteProject>:"watch-generate:<ApiName>-client"

yarn

yarn nx run <WebsiteProject>:"watch-generate:<ApiName>-client"

npm

npx nx run <WebsiteProject>:"watch-generate:<ApiName>-client"

bun

bunx nx run <WebsiteProject>:"watch-generate:<ApiName>-client"

Dependencia del observador de archivos

watch-generate:<ApiName>-client depende del comando nx watch, que requiere que el Nx Daemon esté en ejecución. Por lo tanto, si has deshabilitado el daemon, el cliente no se regenerará automáticamente al realizar cambios en tu FastAPI.

Usar el hook de API

El generador proporciona un hook use<ApiName> que puedes usar para llamar a tu API con TanStack Query.

Consultas

Puedes usar el método queryOptions para obtener las opciones requeridas para llamar a tu API usando el hook useQuery de TanStack Query:

import { useQuery } from '@tanstack/react-query';
import { useState, useEffect } from 'react';
import { useMyApi } from './hooks/useMyApi';

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>;

  return <div>Item: {item.data.name}</div>;
}

Haz clic aquí para ver un ejemplo usando el cliente vanilla directamente.

Mutaciones

Los hooks generados incluyen soporte para mutaciones usando el hook useMutation de TanStack Query. Esto provee una forma limpia de manejar operaciones de creación, actualización y eliminación con estados de carga, manejo de errores y actualizaciones optimistas.

import { useMutation } from '@tanstack/react-query';
import { useMyApi } from './hooks/useMyApi';

function CreateItemForm() {
  const api = useMyApi();
  // Create a mutation using the generated mutation options
  const createItem = useMutation(api.createItem.mutationOptions());

  const handleSubmit = (e) => {
    e.preventDefault();
    createItem.mutate({ name: 'New Item', description: 'A new item' });
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* Form fields */}
      <button
        type="submit"
        disabled={createItem.isPending}
      >
        {createItem.isPending ? 'Creating...' : 'Create Item'}
      </button>

      {createItem.isSuccess && (
        <div className="success">
          Item created with ID: {createItem.data.id}
        </div>
      )}

      {createItem.isError && (
        <div className="error">
          Error: {createItem.error.message}
        </div>
      )}
    </form>
  );
}

También puedes añadir callbacks para diferentes estados de la mutación:

const createItem = useMutation({
  ...api.createItem.mutationOptions(),
  onSuccess: (data) => {
    // This will run when the mutation succeeds
    console.log('Item created:', data);
    // You can navigate to the new item
    navigate(`/items/${data.id}`);
  },
  onError: (error) => {
    // This will run when the mutation fails
    console.error('Failed to create item:', error);
  },
  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() });
  }
});

Haz clic aquí para ver un ejemplo usando el cliente directamente.

Carga de archivos

Para endpoints que aceptan una carga de archivo, el cliente generado envía la solicitud como FormData. Define una operación con un cuerpo multipart/form-data en tu FastAPI, por ejemplo usando UploadFile:

from fastapi import UploadFile

@app.post("/files")
async def upload_file(file: UploadFile, description: str = "") -> FileMetadata:
    contents = await file.read()
    ...

Los campos binarios se tipan como Blob en el cliente generado, y otros campos (como description arriba) mantienen sus tipos modelados. Pasa un Blob o File — por ejemplo, uno obtenido de un <input type="file">:

import { useMutation } from '@tanstack/react-query';
import { useMyApi } from './hooks/useMyApi';

function UploadForm() {
  const api = useMyApi();
  const uploadFile = useMutation(api.uploadFile.mutationOptions());

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (file) {
      uploadFile.mutate({ file, description: file.name });
    }
  };

  return <input type="file" onChange={handleChange} />;
}

El cliente construye un cuerpo FormData y permite que fetch establezca el Content-Type (incluyendo el límite multipart) automáticamente.

Paginación con consultas infinitas

Para endpoints que aceptan un parámetro cursor como entrada, los hooks generados proporcionan soporte para consultas infinitas usando el hook useInfiniteQuery de TanStack Query. Esto facilita la implementación de funcionalidad de “cargar más” o desplazamiento infinito.

import { useInfiniteQuery } from '@tanstack/react-query';
import { useMyApi } from './hooks/useMyApi';

function ItemList() {
  const api = useMyApi();
  const items = useInfiniteQuery({
    ...api.listItems.infiniteQueryOptions({
      limit: 10, // Number of items per page
    }, {
      // Make sure you define a getNextPageParam function to return
      // the parameter that should be passed as the 'cursor' for the
      // next page
      getNextPageParam: (lastPage) =>
        lastPage.nextCursor || undefined
      }),
  });

  if (items.isLoading) {
    return <LoadingSpinner />;
  }

  if (items.isError) {
    return <ErrorMessage message={items.error.message} />;
  }

  return (
    <div>
      {/* Flatten the pages array to render all items */}
      <ul>
        {items.data.pages.flatMap(page =>
          page.items.map(item => (
            <li key={item.id}>{item.name}</li>
          ))
        )}
      </ul>

      <button
        onClick={() => items.fetchNextPage()}
        disabled={!items.hasNextPage || items.isFetchingNextPage}
      >
        {items.isFetchingNextPage
          ? 'Loading more...'
          : items.hasNextPage
          ? 'Load More'
          : 'No more items'}
      </button>
    </div>
  );
}

Los hooks generados manejan automáticamente la paginación basada en cursor si tu API lo soporta. El valor nextCursor se extrae de la respuesta y se usa para obtener la próxima página.

APIs paginadas

Si tienes una API paginada que tiene su parámetro de paginación nombrado de manera diferente a cursor, puedes personalizarlo usando la extensión de proveedor OpenAPI x-cursor.

Haz clic aquí para ver un ejemplo usando el cliente directamente.

Manejo de errores

La integración incluye manejo de errores incorporado con respuestas de error tipadas. Se genera un tipo <operation-name>Error que encapsula las posibles respuestas de error definidas en la especificación OpenAPI. Cada error tiene una propiedad status y error, y al verificar el valor de status puedes reducir a un tipo específico de error.

import { useMutation } from '@tanstack/react-query';

function MyComponent() {
  const api = useMyApi();
  const createItem = useMutation(api.createItem.mutationOptions());

  const handleClick = () => {
    createItem.mutate({ name: 'New Item' });
  };

  if (createItem.error) {
    switch (createItem.error.status) {
      case 400:
        // error.error is typed as CreateItem400Response
        return (
          <div>
            <h2>Invalid input:</h2>
            <p>{createItem.error.error.message}</p>
            <ul>
              {createItem.error.error.validationErrors.map((err) => (
                <li key={err.field}>{err.message}</li>
              ))}
            </ul>
          </div>
        );
      case 403:
        // error.error is typed as CreateItem403Response
        return (
          <div>
            <h2>Not authorized:</h2>
            <p>{createItem.error.error.reason}</p>
          </div>
        );
      case 500:
      case 502:
        // error.error is typed as CreateItem5XXResponse
        return (
          <div>
            <h2>Server error:</h2>
            <p>{createItem.error.error.message}</p>
            <p>Trace ID: {createItem.error.error.traceId}</p>
          </div>
        );
    }
  }

  return <button onClick={handleClick}>Create Item</button>;
}

Haz clic aquí para ver un ejemplo usando el cliente vanilla directamente.

Consumir un stream

Si has configurado tu FastAPI para transmitir respuestas, tu hook useQuery actualizará automáticamente sus datos a medida que lleguen nuevos fragmentos del stream.

Por ejemplo:

function MyStreamingComponent() {
  const api = useMyApi();
  const stream = useQuery(api.myStream.queryOptions());

  return (
    <ul>
      {(stream.data ?? []).map((chunk) => (
        <li>
          {chunk.timestamp.toISOString()}: {chunk.message}
        </li>
      ))}
    </ul>
  );
}

Puedes usar las propiedades isLoading y fetchStatus para determinar el estado actual del stream si es necesario. Un stream sigue este ciclo de vida:

1. Se envía la solicitud HTTP para iniciar el streaming

   • isLoading es true
   • fetchStatus es 'fetching'
   • data es undefined

2. Se recibe el primer fragmento del stream

   • isLoading se convierte en false
   • fetchStatus permanece en 'fetching'
   • data se convierte en un array que contiene el primer fragmento

3. Se reciben fragmentos subsiguientes

   • isLoading permanece en false
   • fetchStatus permanece en 'fetching'
   • data se actualiza con cada fragmento subsiguiente tan pronto como se recibe

4. El stream se completa

   • isLoading permanece en false
   • fetchStatus se convierte en 'idle'
   • data es un array de todos los fragmentos recibidos

Haz clic aquí para ver un ejemplo usando el cliente vanilla directamente.

APIs de streaming

Si tienes una API de streaming que acepta un parámetro cursor, al usar el hook useInfiniteQuery, cada página esperará a que el stream termine antes de que se haya cargado.

Personalizar el código generado

Consultas y Mutaciones

Por defecto, las operaciones en tu FastAPI que usan los métodos HTTP PUT, POST, PATCH y DELETE se consideran mutaciones, y las demás se consideran consultas.

Puedes cambiar este comportamiento usando x-query y x-mutation.

x-query

@app.post(
    "/items",
    openapi_extra={
        "x-query": True
    }
)
def list_items():
    # ...

El hook generado proveerá queryOptions aunque use el método HTTP POST:

const items = useQuery(api.listItems.queryOptions());

x-mutation

@app.get(
    "/start-processing",
    openapi_extra={
        "x-mutation": True
    }
)
def start_processing():
    # ...

El hook generado proveerá mutationOptions aunque use el método HTTP GET:

// Generated hook will include the custom options
const startProcessing = useMutation(api.startProcessing.mutationOptions());

Cursor de paginación personalizado

Por defecto, los hooks generados asumen paginación basada en cursor con un parámetro llamado cursor. Puedes personalizar este comportamiento usando la extensión x-cursor:

@app.get(
    "/items",
    openapi_extra={
        # Specify a different parameter name for the cursor
        "x-cursor": "page_token"
    }
)
def list_items(page_token: str = None, limit: int = 10):
    # ...
    return {
        "items": items,
        "page_token": next_page_token
    }

Si no quieres generar infiniteQueryOptions para una operación, puedes establecer x-cursor en False:

@app.get(
    "/items",
    openapi_extra={
        # Disable cursor-based pagination for this endpoint
        "x-cursor": False
    }
)
def list_items(page: int = 1, limit: int = 10):
    # ...
    return {
        "items": items,
        "total": total_count,
        "page": page,
        "pages": total_pages
    }

Agrupar operaciones

Los hooks generados y los métodos del cliente se organizan automáticamente según las etiquetas OpenAPI en tus endpoints FastAPI. Esto ayuda a mantener tus llamadas API organizadas y facilita encontrar operaciones relacionadas.

Por ejemplo:

items.py

@app.get(
    "/items",
    tags=["items"],
)
def list():
    # ...

@app.post(
    "/items",
    tags=["items"],
)
def create(item: Item):
    # ...

users.py

@app.get(
    "/users",
    tags=["users"],
)
def list():
    # ...

Los hooks generados se agruparán por estas etiquetas:

import { useQuery, useMutation } from '@tanstack/react-query';
import { useMyApi } from './hooks/useMyApi';

function ItemsAndUsers() {
  const api = useMyApi();

  // Items operations are grouped under api.items
  const items = useQuery(api.items.list.queryOptions());
  const createItem = useMutation(api.items.create.mutationOptions());

  // Users operations are grouped under api.users
  const users = useQuery(api.users.list.queryOptions());

  // Usage example
  const handleCreateItem = () => {
    createItem.mutate({ name: 'New Item' });
  };

  return (
    <div>
      <h2>Items</h2>
      <ul>
        {items.data?.map(item => (
          <li key={item.id}>{item.name}</li>
        ))}
      </ul>
      <button onClick={handleCreateItem}>Add Item</button>

      <h2>Users</h2>
      <ul>
        {users.data?.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  );
}

Esta agrupación facilita la organización de tus llamadas API y proporciona una mejor finalización de código en tu IDE.

Haz clic aquí para ver un ejemplo usando el cliente directamente.

Dividir tu API

También puedes dividir tu API usando múltiples routers. Consulta la Documentación de FastAPI para más detalles.

Errores

Puedes personalizar las respuestas de error en tu FastAPI definiendo clases de excepción personalizadas, manejadores de excepciones y especificando modelos de respuesta para diferentes códigos de estado. El cliente generado manejará automáticamente estos tipos de error personalizados.

Definir modelos de error personalizados

Primero, define tus modelos de error usando Pydantic:

models.py

from pydantic import BaseModel

class ErrorDetails(BaseModel):
    message: str

class ValidationError(BaseModel):
    message: str
    field_errors: list[str]

Crear excepciones personalizadas

Luego crea clases de excepción para diferentes escenarios de error:

exceptions.py

class NotFoundException(Exception):
    def __init__(self, message: str):
        self.message = message

class ValidationException(Exception):
    def __init__(self, details: ValidationError):
        self.details = details

Agregar manejadores de excepciones

Registra manejadores de excepciones para convertir tus excepciones en respuestas HTTP:

main.py

from fastapi import Request
from fastapi.responses import JSONResponse

@app.exception_handler(NotFoundException)
async def not_found_handler(request: Request, exc: NotFoundException):
    return JSONResponse(
        status_code=404,
        content=exc.message,
    )

@app.exception_handler(ValidationException)
async def validation_error_handler(request: Request, exc: ValidationException):
    return JSONResponse(
        status_code=400,
        content=exc.details.model_dump(),
    )

Tipos de respuesta personalizados

JSONResponse acepta un diccionario, así que usamos el método model_dump de nuestro modelo Pydantic.

Especificar modelos de respuesta

Finalmente, especifica los modelos de respuesta para diferentes códigos de estado en tus endpoints:

main.py

@app.get(
    "/items/{item_id}",
    responses={
        404: {"model": str}
        500: {"model": ErrorDetails}
    }
)
def get_item(item_id: str) -> Item:
    item = find_item(item_id)
    if not item:
        raise NotFoundException(message=f"Item with ID {item_id} not found")
    return item

@app.post(
    "/items",
    responses={
        400: {"model": ValidationError},
        403: {"model": str}
    }
)
def create_item(item: Item) -> Item:
    if not is_valid(item):
        raise ValidationException(
            ValidationError(
                message="Invalid item data",
                field_errors=["name is required"]
            )
        )
    return save_item(item)

Usar tipos de error personalizados en React

El cliente generado manejará automáticamente estos tipos de error personalizados, permitiéndote verificar tipos y manejar diferentes respuestas de error:

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 responses in your FastAPI
      switch (error.status) {
        case 404:
          // error.error is a string as specified in the responses
          console.error('Not found:', error.error);
          break;
        case 500:
          // error.error is typed as ErrorDetails
          console.error('Server error:', error.error.message);
          break;
      }
    }
  });

  // Mutation with typed error handling
  const createItem = useMutation({
    ...api.createItem.mutationOptions(),
    onError: (error) => {
      switch (error.status) {
        case 400:
          // error.error is typed as ValidationError
          console.error('Validation error:', error.error.message);
          console.error('Field errors:', error.error.field_errors);
          break;
        case 403:
          // error.error is a string as specified in the responses
          console.error('Forbidden:', error.error);
          break;
      }
    }
  });

  // Component rendering with error handling
  if (getItem.isError) {
    if (getItem.error.status === 404) {
      return <NotFoundMessage message={getItem.error.error} />;
    } else {
      return <ErrorMessage message={getItem.error.error.message} />;
    }
  }

  return (
    <div>
      {/* Component content */}
    </div>
  );
}

Haz clic aquí para ver un ejemplo usando el cliente directamente.

Respuestas de error

Al definir respuestas de error en FastAPI, siempre usa el parámetro responses para especificar el modelo para cada código de estado. Esto garantiza que el cliente generado tenga información de tipo adecuada para el manejo de errores.

Mejores prácticas

Manejar estados de carga

Siempre maneja estados de carga y errores para una mejor experiencia de usuario:

import { useQuery } from '@tanstack/react-query';

function ItemList() {
  const api = useMyApi();
  const items = useQuery(api.listItems.queryOptions());

  if (items.isLoading) {
    return <LoadingSpinner />;
  }

  if (items.isError) {
    const err = items.error;
    switch (err.status) {
      case 403:
        // err.error is typed as ListItems403Response
        return <ErrorMessage message={err.error.reason} />;
      case 500:
      case 502:
        // err.error is typed as ListItems5XXResponse
        return (
          <ErrorMessage
            message={err.error.message}
            details={`Trace ID: ${err.error.traceId}`}
          />
        );
      default:
        return <ErrorMessage message="An unknown error occurred" />;
    }
  }

  return (
    <ul>
      {items.data.map((item) => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  );
}

Haz clic aquí para ver un ejemplo usando el cliente vanilla directamente.

Actualizaciones optimistas

Implementa actualizaciones optimistas para una mejor experiencia de usuario:

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

function ItemList() {
  const api = useMyApi();
  const queryClient = useQueryClient();

  // Query to fetch items
  const itemsQuery = useQuery(api.listItems.queryOptions());

  // Mutation for deleting items with optimistic updates
  const deleteMutation = useMutation({
    ...api.deleteItem.mutationOptions(),
    onMutate: async (itemId) => {
      // Cancel any outgoing refetches
      await queryClient.cancelQueries({ queryKey: api.listItems.queryKey() });

      // Snapshot the previous value
      const previousItems = queryClient.getQueryData(api.listItems.queryKey());

      // Optimistically update to the new value
      queryClient.setQueryData(
        api.listItems.queryKey(),
        (old) => old.filter((item) => item.id !== itemId)
      );

      // Return a context object with the snapshot
      return { previousItems };
    },
    onError: (err, itemId, context) => {
      // If the mutation fails, use the context returned from onMutate to roll back
      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() });
    },
  });

  if (itemsQuery.isLoading) {
    return <LoadingSpinner />;
  }

  if (itemsQuery.isError) {
    return <ErrorMessage message="Failed to load items" />;
  }

  return (
    <ul>
      {itemsQuery.data.map((item) => (
        <li key={item.id}>
          {item.name}
          <button
            onClick={() => deleteMutation.mutate(item.id)}
            disabled={deleteMutation.isPending}
          >
            {deleteMutation.isPending ? 'Deleting...' : 'Delete'}
          </button>
        </li>
      ))}
    </ul>
  );
}

Haz clic aquí para ver un ejemplo usando el cliente vanilla directamente.

Seguridad de tipos

La integración proporciona seguridad de tipos completa de extremo a extremo. Tu IDE proporcionará autocompletado completo y verificación de tipos para todas tus llamadas API:

import { useMutation } from '@tanstack/react-query';

function ItemForm() {
  const api = useMyApi();

  // Type-safe mutation for creating items
  const createItem = useMutation({
    ...api.createItem.mutationOptions(),
    // ✅ Type error if onSuccess callback doesn't handle the correct response type
    onSuccess: (data) => {
      // data is fully typed based on your API's response schema
      console.log(`Item created with ID: ${data.id}`);
    },
  });

  const handleSubmit = (data: CreateItemInput) => {
    // ✅ Type error if input doesn't match schema
    createItem.mutate(data);
  };

  // Error UI can use type narrowing to handle different error types
  if (createItem.error) {
    const error = createItem.error;
    switch (error.status) {
      case 400:
        // error.error is typed as CreateItem400Response
        return (
          <FormError
            message="Invalid input"
            errors={error.error.validationErrors}
          />
        );
      case 403:
        // error.error is typed as CreateItem403Response
        return <AuthError reason={error.error.reason} />;
      default:
        // error.error is typed as CreateItem5XXResponse for 500, 502, etc.
        return <ServerError message={error.error.message} />;
    }
  }

  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      handleSubmit({ name: 'New Item' });
    }}>
      {/* Form fields */}
      <button
        type="submit"
        disabled={createItem.isPending}
      >
        {createItem.isPending ? 'Creating...' : 'Create Item'}
      </button>
    </form>
  );
}

Haz clic aquí para ver un ejemplo usando el cliente vanilla directamente.

Los tipos se generan automáticamente a partir del esquema OpenAPI de tu FastAPI, asegurando que cualquier cambio en tu API se refleje en tu código frontend después de una compilación.

Autenticación personalizada

Si tu FastAPI usa autenticación Custom (Lambda Authorizer), necesitarás editar el proveedor de cliente generado para agregar los encabezados de autorización que tu autorizador espera. Busca la configuración fetch en el <ApiName>Provider.tsx generado y agrega tu token o clave API a los encabezados de la solicitud.