Connect-Query Documentation

While protoc-gen-es generates service objects, the protoc-gen-connect-query plugin provides an additional convenience by exporting every RPC method individually. This allows you to import methods directly (e.g., say) instead of accessing them through a service object (e.g., ElizaService.say).

import { ElizaService } from "./eliza_pb";

/**
 * Say is a unary RPC. Eliza responds to the prompt with a single sentence.
 *
 * @generated from rpc connectrpc.eliza.v1.ElizaService.Say
 */
export const say: (typeof ElizaService)["method"]["say"];

Connect-Query generates one output file for every service defined in your proto files. This differs from @bufbuild/protoc-gen-es, which typically generates one file per proto file.

Example structure: If you have pizza.proto containing DetroitStyleService and ChicagoStyleService, the output will be:

• pizza_pb.ts (Generated by protoc-gen-es)
• pizza-DetroitStyleService_connectquery.ts (Generated by protoc-gen-connect-query)
• pizza-ChicagoStyleService_connectquery.ts (Generated by protoc-gen-connect-query)

The *_pb.ts files are required dependencies for the *_connectquery.ts files.

To use Connect-Query, you must wrap your application in both a TransportProvider (from @connectrpc/connect-query) and a QueryClientProvider (from @tanstack/react-query). The TransportProvider requires a transport instance created via @connectrpc/connect-web.

import { createConnectTransport } from "@connectrpc/connect-web";
import { TransportProvider } from "@connectrpc/connect-query";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const finalTransport = createConnectTransport({
  baseUrl: "https://demo.connectrpc.com",
});

const queryClient = new QueryClient();

function App() {
  return (
    <TransportProvider transport={finalTransport}>
      <QueryClientProvider client={queryClient}>
        <YourApp />
      </QueryClientProvider>
    </TransportProvider>
  );
}

To use Connect-Query, you need to install both the code generator plugins and the runtime libraries. The generator works in tandem with @bufbuild/protoc-gen-es.

Install the generator plugins as dev dependencies and the runtime libraries as regular dependencies:

npm install --save-dev @connectrpc/protoc-gen-connect-query @bufbuild/protoc-gen-es
npm install @connectrpc/connect-query @bufbuild/protobuf

When you do not have access to React context (e.g., during server-side rendering or in utility functions), you can use createQueryOptions and provide a transport directly in the options object. This allows you to use standard TanStack Query methods like queryClient.prefetchQuery.

import { say } from "./gen/eliza-ElizaService_connectquery";

function prefetch() {
  return queryClient.prefetchQuery(
    createQueryOptions(say, { sentence: "Hello" }, { transport: myTransport }),
  );
}

The recommended way to generate code is using the buf CLI.

1. Create a buf.gen.yaml configuration file in your project root:

version: v2
plugins:
  # Invokes protoc-gen-es to generate base types
  - local: protoc-gen-es
    out: src/gen
    opt: target=ts
  # Invokes protoc-gen-connect-query to generate Connect-Query clients
  - local: protoc-gen-connect-query
    out: src/gen
    opt: target=ts

2. Run the generation command:

npx @bufbuild/buf generate

You can also add this to your package.json scripts for easier access:

"scripts": {
    "buf:generate": "buf generate"
}