State Management Overview

OpenAPI TypeScript can generate type-safe hooks, composables, and query helpers that integrate with popular data fetching libraries. This eliminates manual setup and ensures your API calls stay in sync with your OpenAPI specification.

Supported Libraries

OpenAPI TypeScript supports multiple state management and data fetching libraries across different frameworks:

TanStack Query

React, Vue, Svelte, Solid, and Angular support for queries, mutations, and infinite queries.

Pinia Colada

Vue composables for queries and mutations with type-safe query keys.

How It Works

State management plugins analyze your OpenAPI specification and generate:

Query Options - Pre-configured options for fetching data
Mutation Options - Type-safe mutation functions for POST/PUT/DELETE operations
Query Keys - Deterministic cache keys based on operation parameters
Hooks/Composables - Framework-specific functions (optional)

Generated Artifacts

Query Options

For GET operations, plugins generate query options that include:

Query function with proper typing
Query key generation
Error handling
Response type inference

// Generated query options
export const getPetByIdOptions = (options: Options<GetPetByIdData>) =>
  queryOptions({
    queryFn: async ({ queryKey, signal }) => {
      const { data } = await client.getPetById({
        ...options,
        ...queryKey[0],
        signal,
        throwOnError: true,
      });
      return data;
    },
    queryKey: getPetByIdQueryKey(options),
  });

Mutation Options

For POST/PUT/DELETE operations, plugins generate mutation options:

// Generated mutation options
export const addPetMutation = (
  options?: Partial<Options<AddPetData>>
) => ({
  mutationFn: async (fnOptions) => {
    const { data } = await client.addPet({
      ...options,
      ...fnOptions,
      throwOnError: true,
    });
    return data;
  },
});

Query Keys

Deterministic cache keys are generated for each operation:

// Generated query key function
export const getPetByIdQueryKey = (options: Options<GetPetByIdData>) =>
  createQueryKey('getPetById', options);

Configuration Options

All state management plugins share common configuration patterns:

Naming Conventions

Customize how generated functions are named:

export default defineConfig({
  plugins: [
    {
      name: '@tanstack/react-query',
      // Default: '{{name}}Options'
      queryOptions: '{{name}}QueryOptions',
      // Default: '{{name}}Mutation'
      mutationOptions: '{{name}}MutationOptions',
      // Default: '{{name}}QueryKey'
      queryKeys: '{{name}}Key',
    },
  ],
});

Feature Toggles

Enable or disable specific features:

export default defineConfig({
  plugins: [
    {
      name: '@tanstack/react-query',
      // Disable query keys generation
      queryKeys: false,
      // Enable useQuery hooks
      useQuery: true,
      // Disable infinite queries
      infiniteQueryOptions: false,
    },
  ],
});

Query Key Tags

Include operation tags in query keys for better cache invalidation:

export default defineConfig({
  plugins: [
    {
      name: '@tanstack/react-query',
      queryKeys: {
        tags: true, // Include operation tags
      },
    },
  ],
});

Custom Metadata

Add custom metadata to generated options:

export default defineConfig({
  plugins: [
    {
      name: '@tanstack/react-query',
      queryOptions: {
        meta: (operation) => ({
          operationId: operation.id,
          deprecated: operation.deprecated,
          tags: operation.tags,
        }),
      },
    },
  ],
});

Usage Patterns

Basic Query

import { useQuery } from '@tanstack/react-query';
import { getPetByIdOptions } from './client/@tanstack/react-query.gen';

function PetDetails({ petId }: { petId: number }) {
  const { data, error, isLoading } = useQuery(
    getPetByIdOptions({
      path: { petId },
    })
  );

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  return <div>{data.name}</div>;
}

<script setup lang="ts">
import { useQuery } from '@pinia/colada';
import { getPetByIdQuery } from './client/@pinia/colada.gen';

const petId = ref(1);
const { data, error, isLoading } = useQuery(
  getPetByIdQuery({
    path: { petId: petId.value },
  })
);
</script>

Mutations

import { useMutation } from '@tanstack/react-query';
import { addPetMutation } from './client/@tanstack/react-query.gen';

function AddPetForm() {
  const mutation = useMutation(addPetMutation());

  const handleSubmit = (formData: FormData) => {
    mutation.mutate({
      body: {
        name: formData.get('name') as string,
        status: 'available',
      },
    });
  };

  return <form onSubmit={handleSubmit}>{/* form fields */}</form>;
}

<script setup lang="ts">
import { useMutation } from '@pinia/colada';
import { addPetMutation } from './client/@pinia/colada.gen';

const { mutateAsync } = useMutation(addPetMutation());

const handleSubmit = async () => {
  await mutateAsync({
    body: {
      name: 'Fluffy',
      status: 'available',
    },
  });
};
</script>

Get Started

Configuration

Core Plugins

HTTP Clients

Validators