Hey API

Appearance

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.

js
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', 
  ],
};
js
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', 
  ],
};
js
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', 
  ],
};
js
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', 
  ],
};
js
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', 
  ],
};

You can now generate TanStack Query artifacts. 🎉

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().

ts
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().

ts
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().

ts
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.

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

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

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

Examples ​

You can view live examples on StackBlitz.

Sponsoring ​

Love Hey API? Become our sponsor.

  • Stainless logo