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.

About

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

Demo

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

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

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

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

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

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

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

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

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

Query Keys

If you have access to the result of 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 query key functions. The generated query key functions follow the naming convention of SDK functions and by default append QueryKey, e.g. getPetByIdQueryKey().

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

You can customize the naming and casing pattern for query key functions using the queryKeys.name and queryKeys.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().

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

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

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.

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

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

You can customize the naming and casing pattern for infinite query key functions using the infiniteQueryKeys.name and infiniteQueryKeys.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().

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

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