TanStack Query

WARNING

TanStack Query plugin is currently in beta. The interface might change before it becomes stable. We encourage you to leave feedback on GitHub.

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

Features

• 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

Assuming you have already created a configuration file, simply add TanStack Query to your plugins and you'll be ready to generate TanStack Query artifacts. 🎉

react

import { defaultPlugins } from '@hey-api/openapi-ts';

export default {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: 'src/client',
  plugins: [
    ...defaultPlugins,
    '@tanstack/react-query', 
  ],
};

vue

import { defaultPlugins } from '@hey-api/openapi-ts';

export default {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: 'src/client',
  plugins: [
    ...defaultPlugins,
    '@tanstack/vue-query', 
  ],
};

angular

import { defaultPlugins } from '@hey-api/openapi-ts';

export default {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: 'src/client',
  plugins: [
    ...defaultPlugins,
    '@tanstack/angular-query-experimental', 
  ],
};

svelte

import { defaultPlugins } from '@hey-api/openapi-ts';

export default {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: 'src/client',
  plugins: [
    ...defaultPlugins,
    '@tanstack/svelte-query', 
  ],
};

solid

import { defaultPlugins } from '@hey-api/openapi-ts';

export default {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: 'src/client',
  plugins: [
    ...defaultPlugins,
    '@tanstack/solid-query', 
  ],
};

Output

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

Queries

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

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

Infinite Queries

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

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

Mutations

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

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

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

Query Keys

Query keys are generated for both queries and infinite queries. If you have access to the result of query or infinite query options function, you can get the query key from the queryKey field.

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

Alternatively, you can access the same query key by calling QueryKey or InfiniteQueryKey function.

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

Examples

You can view live examples on StackBlitz.

Sponsors

Love Hey API? Become our sponsor.

•