TanStack Query

v5

About

TanStack Query is a powerful asynchronous state management solution for TypeScript/JavaScript, React, Solid, Vue, Svelte, and Angular.

The TanStack Query plugin for Hey API generates functions and query keys from your OpenAPI spec, fully compatible with SDKs, transformers, and all core features.

Demo

Features

• TanStack Query v5 support
• seamless integration with @hey-api/openapi-ts ecosystem
• create query keys following the best practices
• type-safe query options, infinite query options, and mutation options
• minimal learning curve thanks to extending the underlying technology

Installation

In your configuration, add TanStack Query to your plugins and you'll be ready to generate TanStack Query artifacts. 🎉

react

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    '@tanstack/react-query', 
  ],
};

vue

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    '@tanstack/vue-query', 
  ],
};

angular

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    '@tanstack/angular-query-experimental', 
  ],
};

svelte

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    '@tanstack/svelte-query', 
  ],
};

solid

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    '@tanstack/solid-query', 
  ],
};

Output

The TanStack Query plugin will generate the following artifacts, depending on the input specification.

Queries

Queries are generated from GET and POST endpoints. The generated query functions follow the naming convention of SDK functions and by default append Options, e.g. getPetByIdOptions().

example

const { data, error } = useQuery({
  ...getPetByIdOptions({
    path: {
      petId: 1,
    },
  }),
});

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      queryOptions: true, 
    },
  ],
};

You can customize the naming and casing pattern for queryOptions functions using the .name and .case options.

Meta

You can use the meta field to attach arbitrary information to a query. To generate metadata for queryOptions, provide a function to the .meta option.

example

queryOptions({
  // ...other fields
  meta: {
    id: 'getPetById',
  },
});

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      queryOptions: {
        meta: (operation) => ({ id: operation.id }), 
      },
    },
  ],
};

Query Keys

Query keys contain normalized SDK function parameters and additional metadata.

example

const queryKey = [
  {
    _id: 'getPetById',
    baseUrl: 'https://get.heyapi.dev',
    path: {
      petId: 1,
    },
  },
];

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      queryKeys: true, 
    },
  ],
};

Tags

You can include operation tags in your query keys by setting tags to true. This will make query keys larger but provides better cache invalidation capabilities.

example

const queryKey = [
  {
    _id: 'getPetById',
    baseUrl: 'https://get.heyapi.dev',
    path: {
      petId: 1,
    },
    tags: ['pets', 'one', 'get'], 
  },
];

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      queryKeys: {
        tags: true, 
      },
    },
  ],
};

Accessing Query Keys

If you have access to the result of query options function, you can get the query key from the queryKey field.

example

const { queryKey } = getPetByIdOptions({
  path: {
    petId: 1,
  },
});

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      queryOptions: true, 
    },
  ],
};

Alternatively, you can access the same query key by calling query key functions. The generated query key functions follow the naming convention of SDK functions and by default append QueryKey, e.g. getPetByIdQueryKey().

example

const queryKey = getPetByIdQueryKey({
  path: {
    petId: 1,
  },
});

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      queryKeys: true, 
    },
  ],
};

You can customize the naming and casing pattern for queryKeys functions using the .name and .case options.

Infinite Queries

Infinite queries are generated from GET and POST endpoints if we detect a pagination parameter. The generated infinite query functions follow the naming convention of SDK functions and by default append InfiniteOptions, e.g. getFooInfiniteOptions().

example

const { data, error } = useInfiniteQuery({
  ...getFooInfiniteOptions({
    path: {
      fooId: 1,
    },
  }),
  getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
  initialPageParam: 0,
});

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      infiniteQueryOptions: true, 
    },
  ],
};

You can customize the naming and casing pattern for infiniteQueryOptions functions using the .name and .case options.

Meta

You can use the meta field to attach arbitrary information to a query. To generate metadata for infiniteQueryOptions, provide a function to the .meta option.

example

infiniteQueryOptions({
  // ...other fields
  meta: {
    id: 'getPetById',
  },
});

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      infiniteQueryOptions: {
        meta: (operation) => ({ id: operation.id }), 
      },
    },
  ],
};

Infinite Query Keys

Infinite query keys contain normalized SDK function parameters and additional metadata.

example

const queryKey = [
  {
    _id: 'getPetById',
    _infinite: true,
    baseUrl: 'https://get.heyapi.dev',
    path: {
      petId: 1,
    },
  },
];

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      infiniteQueryKeys: true, 
    },
  ],
};

Tags

You can include operation tags in your infinite query keys by setting tags to true. This will make query keys larger but provides better cache invalidation capabilities.

example

const queryKey = [
  {
    _id: 'getPetById',
    _infinite: true,
    baseUrl: 'https://get.heyapi.dev',
    path: {
      petId: 1,
    },
    tags: ['pets', 'one', 'get'], 
  },
];

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      infiniteQueryKeys: {
        tags: true, 
      },
    },
  ],
};

Accessing Infinite Query Keys

If you have access to the result of infinite query options function, you can get the query key from the queryKey field.

example

const { queryKey } = getPetByIdInfiniteOptions({
  path: {
    petId: 1,
  },
});

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      infiniteQueryOptions: true, 
    },
  ],
};

Alternatively, you can access the same query key by calling query key functions. The generated query key functions follow the naming convention of SDK functions and by default append InfiniteQueryKey, e.g. getPetByIdInfiniteQueryKey().

example

const queryKey = getPetByIdInfiniteQueryKey({
  path: {
    petId: 1,
  },
});

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      infiniteQueryKeys: true, 
    },
  ],
};

You can customize the naming and casing pattern for infiniteQueryKeys functions using the .name and .case options.

Mutations

Mutations are generated from DELETE, PATCH, POST, and PUT endpoints. The generated mutation functions follow the naming convention of SDK functions and by default append Mutation, e.g. addPetMutation().

example

const addPet = useMutation({
  ...addPetMutation(),
  onError: (error) => {
    console.log(error);
  },
});

addPet.mutate({
  body: {
    name: 'Kitty',
  },
});

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      mutationOptions: true, 
    },
  ],
};

You can customize the naming and casing pattern for mutationOptions functions using the .name and .case options.

Meta

You can use the meta field to attach arbitrary information to a mutation. To generate metadata for mutationOptions, provide a function to the .meta option.

example

const mutationOptions = {
  // ...other fields
  meta: {
    id: 'getPetById',
  },
};

config

export default {
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@tanstack/react-query',
      mutationOptions: {
        meta: (operation) => ({ id: operation.id }), 
      },
    },
  ],
};

API

You can view the complete list of options in the UserConfig interface.

Examples

You can view live examples on StackBlitz.

Sponsors

Help Hey API stay around for the long haul by becoming a sponsor.

Gold

• 

  Best-in-class SDKs and MCP for your API.

  stainless.com

Silver

• scalar.com
• fastapi.tiangolo.com

Bronze

•