Gathering detailed insights and metrics for @connectrpc/protoc-gen-connect-query-react
Gathering detailed insights and metrics for @connectrpc/protoc-gen-connect-query-react
TypeScript-first expansion pack for TanStack Query that gives you Protobuf superpowers.
Installations
npm install @connectrpc/protoc-gen-connect-query-reactDeveloper Guide
BETA
Typescript
No
Module System
N/A
Min. Node Version
>=16
Node Version
18.16.0
NPM Version
9.5.1
Releases
29
Languages
4
TypeScript
JavaScript
HTML
CSS
TypeScript (87.79%)
JavaScript (11.8%)
HTML (0.27%)
CSS (0.14%)
Developer
Download Statistics
Total Downloads
810
Last Day
1
Last Week
2
Last Month
30
Last Year
247
GitHub Statistics
Apache-2.0 License
311 Stars
229 Commits
22 Forks
14 Watchers
10 Branches
17 Contributors
Updated on Aug 31, 2025
Maintainers
7
Package Meta Information
Latest Version
0.5.1
Package Id
@connectrpc/protoc-gen-connect-query-react@0.5.1
Unpacked Size
66.00 kB
Size
14.68 kB
File Count
25
NPM Version
9.5.1
Node Version
18.16.0
Published on
Sep 26, 2023
Total Downloads
Cumulative downloads
Total Downloads
810
Last Day
0%
1
Compared to previous day
Last Week
-50%
2
Compared to previous week
Last Month
400%
30
Compared to previous month
Last Year
-56.1%
247
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
2
Peer Dependencies
1
@connectrpc/protoc-gen-connect-query-react
This is an experimental plugin, based on the protoc-gen-connect-query plugin. This plugin provides better DX while sacrificing some flexibility.
Instead of generating a single entry point per method:
1import { getTodos } from "./example-TodoService_connectquery"; 2import { useQuery } from "@tanstack/react-query"; 3 4... 5 6const Component = () => { 7 const { data, isLoading } = useQuery(getTodos.useQuery()); 8}
This plugin generates several methods per method, that all wrap their equivalent in react-query:
1import { useGetTodosQuery } from "./example-TodoService_connectquery_react"; 2 3... 4 5const Component = () => { 6 const { data, isLoading } = useGetTodosQuery(); 7}
The code generator for Connect-Query, a expansion pack for TanStack Query (react-query), that enables effortless communication with servers that speak the Connect Protocol.
Learn more about Connect-Query at github.com/connectrpc/connect-query-es.
Installation
protoc-gen-connect-query-react is a code generator plugin for Protocol Buffer compilers like buf and protoc. It generates clients from your Protocol Buffer schema, and works in tandem with
@bufbuild/protoc-gen-es, the code generator plugin for all Protocol Buffer base types. The code those two plugins generate requires the runtime libraries @connectrpc/connect-query, and @bufbuild/protobuf.
To install the plugins and their runtime libraries, run:
1npm install --save-dev @connectrpc/protoc-gen-connect-query-react @bufbuild/protoc-gen-es 2npm install @connectrpc/connect-query @bufbuild/protobuf
We use peer dependencies to ensure that code generator and runtime library are compatible with each other. Note that yarn and pnpm only emit a warning in this case.
Generating Code
example.proto
For these examples, consider the following example proto file example.proto:
1syntax = "proto3"; 2 3package example.v1; 4 5message Nothing {} 6 7message Todo { 8 string id = 1; 9 string name = 2; 10 bool completed = 3; 11} 12 13message Todos { 14 repeated Todo todos = 1; 15} 16 17service TodoService { 18 rpc GetTodos(Nothing) returns (Todos); 19 rpc AddTodo(Todo) returns (Nothing); 20}
This file creates an RPC service with the following:
GetTodostakes no inputs and returns an array ofTodos.AddTodoadds a newTodoand returns nothing.
buf.gen.yaml
Add a new configuration file buf.gen.yaml
1version: v1 2plugins: 3 # This will invoke protoc-gen-es and write output to src/gen 4 - name: es 5 out: src/gen 6 opt: target=ts 7 8 # This will invoke protoc-gen-connect-query-react 9 - name: connect-query-react 10 opt: 11 - target=ts 12 - import-hook-from=@tanstack/connect-query 13 out: dist
With the buf CLI
To use the buf CLI to generate code for all protobuf files within your project, simply run:
1npx @bufbuild/buf generate
Note that
bufcan generate from various inputs, not just local protobuf files. For example,npm run generate buf.build/connectrpc/elizagenerates code for the module connectrpc/eliza on the Buf Schema Registry.
With protoc
1PATH=$PATH:$(pwd)/node_modules/.bin \ 2 protoc -I . \ 3 --es_out src/gen \ 4 --es_opt target=ts \ 5 --connect-query_out src/gen \ 6 --connect-query_opt target=ts \ 7 --connect-query-react_out src/gen \ 8 --connect-query-react_opt target=ts,import-hook-from=@tanstack/connect-query \ 9 example.proto
Note that we are adding node_modules/.bin to the $PATH, so that the protocol buffer compiler can find them. This happens automatically with npm scripts.
Note: Since yarn v2 and above does not use a
node_modulesdirectory, you need to change the variable a bit:1PATH=$(dirname $(yarn bin protoc-gen-es)):$(dirname $(yarn bin protoc-gen-connect-es)):$PATH
With Node
Add a line to the scripts section of your package.json to run buf generate.
1"scripts": { 2 ... 3 "buf:generate": "npx @bufbuild/buf generate example.proto" 4},
Finally, tell Buf to generate code by running your command:
1npm run buf:generate
Now you should see your generated code:
1.
2└── gen/
3 ├── example_pb.ts
4 └── example-TodoService_connectquery_react.tsGenerated Output
Connect-Query will create one output file for every service in every protofile. Say you have the following file structure:
1. 2└── proto/ 3 ├── pizza.proto 4 └── curry.proto
Where pizza.proto contains DetroitStyleService and ChicagoStyleService, and where curry.proto contains VindalooService. Your generated output will look like this:
1.
2└── gen/
3 ├── pizza_pb.ts
4 ├── pizza-DetroitStyleService_connectquery_react.ts
5 ├── pizza-ChicagoStyleService_connectquery_react.ts
6 ├── curry_pb.ts
7 └── curry-VindalooService_connectquery_react.tsThe reason each service gets a separate file is to facilitate intellisense and language server protocol imports. Notice that one file per input proto is generated by protoc-gen-es (pizza_pb.ts and curry_pb.ts), and that one file per service is created by protoc-gen-connect-query-react (making up the remainder). The Protobuf-ES generated files (*_pb.ts) are important because those files are referenced from the *_connectquery_react.ts files.
Plugin options
target
This option controls whether the plugin generates JavaScript, TypeScript, or TypeScript declaration files.
Say, for example, you used example.proto:
| Target | Generated output |
|---|---|
target=js | example-TodoService_connectquery_react.js |
target=ts | example-TodoService_connectquery_react.ts |
target=dts | example-TodoService_connectquery_react.d.ts |
Multiple values can be given by separating them with +, for example target=js+dts.
By default, we generate JavaScript and TypeScript declaration files, which produces the smallest code size and is the most compatible with various bundler configurations. If you prefer to generate TypeScript, use target=ts.
import_extension=.js
By default, protoc-gen-connect-query-react (and all other plugins based on @bufbuild/protoplugin) uses a .js file extensions in import paths, even in TypeScript files.
This is unintuitive, but necessary for ECMAScript modules in Node.js.
Unfortunately, not all bundlers and tools have caught up yet, and Deno requires .ts. With this plugin option, you can replace .js extensions in import paths with the given value. For example, set
import_extension=noneto remove the.jsextensionimport_extension=.tsto replace the.jsextension with.ts
keep_empty_files=true
This option exists for other plugins but is not applicable to protoc-gen-connect-query-react because, unlike most other plugins, it does not generate a maximum of one output file for every input proto file. Instead, it generates one output file per service. If you provide a valid proto file that contains no services, protoc-gen-connect-query-react will have no output.
import-hook-from
This option allows you to specify the import path for the useQuery hook. By default, it is @tanstack/connect-query, but you can change it to whatever you want. For example, if you want to use the useQuery hook from @your-path/connect-query, you would set import-hook-from=@your-path/connect-query.
Example Generated Code
See eliza.proto for example inputs, and look here to see the outputs those files generate.e outputs those files generate.
No vulnerabilities found.