Generating React Hooks from OpenAPI

Speakeasy can optionally generate React Hooks as part of your TypeScript SDK. React Hooks are built from your OpenAPI document using TanStack Query (formerly React Query), making it easier to build web applications that interact with your API.

How to generate React Hooks from an OpenAPI document

Follow these steps to generate React Hooks from your OpenAPI document:

Install the Speakeasy CLI

If you haven’t already, install the Speakeasy CLI:

Generate a TypeScript SDK

If you haven’t already generated a TypeScript SDK, run this command:

Then, follow the prompts to select TypeScript as your target language and complete the SDK configuration.

Enable React Hooks

Open the .speakeasy/gen.yaml file in your SDK directory and add the enableReactQuery flag to it:

Regenerate your SDK with React Hooks

Navigate to the folder that holds the generated SDK and run the following command:

This adds a new src/react-query directory, which contains all the generated React Hooks, to your SDK.

Install the SDK in your application

Once you’ve generated your SDK with React Hooks, you need to install it in your React application.

• If you’ve published your SDK to a package registry like npm, install it directly:

• Alternatively, if you’re working with a local SDK, use the package manager’s local path installation feature:

How to use the generated React Hooks

Before using React Hooks, you need to install their dependencies and configure your React Query provider.

Install required dependencies

The generated SDK with React Hooks has TanStack Query as a dependency that should be listed in the SDK’s package.json. Zod is bundled with the SDK. However, you might need to install TanStack Query explicitly in your application:

Set up the React Query provider

Add the TanStack Query provider to your React application:

Basic usage

You can use the generated Hooks in your components as follows:

How to customize React Hooks

The default naming convention for React Hooks follows the standalone function naming convention. For example, a standalone function called productsGetById will have a corresponding React Hook called useProductsGetById.

Sometimes, these names are not ideal for React Hooks. In those instances, you can use the x-speakeasy-react-hook OpenAPI extension to override the default name:

With the example above, the React Hook will be called by useProduct and, under the hood, it will use the productsGetById standalone function.

Generate queries and mutations

By default, the GET, HEAD, and QUERY operations generate React Query hooks, while other operations generate mutation hooks. This isn’t always correct, since certain operations may be “read” operations exposed under the POST endpoint. A great example of this is the complex search APIs that take a request body with filters and other arguments.

You can override these OpenAPI operations with the x-speakeasy-react-hook extension so that they come out as React Query hooks:

Disable React Hooks for an operation

React Hooks may not be useful or relevant for all operations in the API. Disable React Hook generation for an operation by setting the disabled flag under the x-speakeasy-react-hook extension:

Advanced usage

You can also use React Hooks for more advanced purposes.

Implement optimistic updates

When using mutation hooks, you can use TanStack Query’s optimistic update capabilities:

Customize configurations

You can pass custom TanStack Query options to your hooks:

Use infinite queries for pagination

For paginated endpoints, you can use infinite React Query hooks:

Next steps

Visit the following resources to:

• Learn about customizing your TypeScript SDK
• Explore how to set up your SDK documentation
• Check out the TanStack Query documentation  for advanced use cases