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

Ensure you have already configured @hey-api/openapi-ts. Update your configuration to use the TanStack Query plugin.

react

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

vue

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

solid

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

svelte

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

You can now run openapi-ts to generate TanStack Query artifacts. 🎉

Output

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

Queries

Queries are generated from GET and POST endpoints. The generated functions follow the naming convention of services 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 services 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 services 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.

Sponsoring

Love Hey API? Please consider becoming a sponsor.