@connectrpc/protoc-gen-connect-query

- @connectrpc/protoc-gen-connect-query
- Installation
- Generating Code
- example.proto
- buf.gen.yaml
- With the buf CLI
- With protoc
- With Node
- Generated Output
- Plugin options
- target
- import_extension
- keep_empty_files=true
- js_import_style
- ts_nocheck=true
- Example Generated Code

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 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:

``shell
npm install --save-dev @connectrpc/protoc-gen-connect-query @bufbuild/protoc-gen-es
npm 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

$3

For these examples, consider the following example proto file example.proto:

`protobuf
syntax = "proto3";

package example.v1;

message Nothing {}

message Todo {
string id = 1;
string name = 2;
bool completed = 3;
}

message Todos {
repeated Todo todos = 1;
}

service TodoService {
rpc GetTodos(Nothing) returns (Todos);
rpc AddTodo(Todo) returns (Nothing);
}
`

This file creates an RPC service with the following:

- GetTodos takes no inputs and returns an array of Todos.
- AddTodo adds a new Todo and returns nothing.

$3

Add a new configuration file buf.gen.yaml

`yaml
version: v2
plugins:
# This will invoke protoc-gen-es and write output to src/gen
- local: protoc-gen-es
out: src/gen
opt: target=ts
# This will invoke protoc-gen-connect-query
- local: protoc-gen-connect-query
out: src/gen
opt: target=ts
`

$3

To use the buf CLI to generate code for all protobuf files within your project, simply run:

`bash
npx @bufbuild/buf generate
`

> Note that buf can generate from various inputs, not just local protobuf files. For example, npm run generate buf.build/connectrpc/eliza generates code for the module connectrpc/eliza on the Buf Schema Registry.

$3

`bash
PATH=$PATH:$(pwd)/node_modules/.bin \
protoc -I . \
--es_out src/gen \
--es_opt target=ts \
--connect-query_out src/gen \
--connect-query_opt target=ts \
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_modules directory, you need to change the variable a bit:
>
> `bash
> PATH=$(dirname $(yarn bin protoc-gen-es)):$(dirname $(yarn bin protoc-gen-connect-es)):$PATH
> `

$3

Add a line to the scripts section of your package.json to run buf generate.

`json
"scripts": {
...
"buf:generate": "buf generate"
},
`

Finally, tell Buf to generate code by running your command:

`bash
npm run buf:generate
`

Now you should see your generated code:

`tree
.
└── gen/
├── example_pb.ts
└── example-TodoService_connectquery.ts
`

Generated Output

Connect-Query will create one output file for every service in every protofile. Say you have the following file structure:

`tree
.
└── proto/
├── pizza.proto
└── curry.proto
`

Where pizza.proto contains DetroitStyleService and ChicagoStyleService, and where curry.proto contains VindalooService. Your generated output will look like this:

`tree
.
└── gen/
├── pizza_pb.ts
├── pizza-DetroitStyleService_connectquery.ts
├── pizza-ChicagoStyleService_connectquery.ts
├── curry_pb.ts
└── curry-VindalooService_connectquery.ts
`

The 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 (making up the remainder). The Protobuf-ES generated files (_pb.ts) are important because those files are referenced from the _connectquery.ts files.

Plugin options

$3

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.js |
| target=ts | example-TodoService_connectquery.ts |
| target=dts | example-TodoService_connectquery.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.

$3

By default, protoc-gen-connect-query (and all other plugins based on @bufbuild/protoplugin) doesn't add file extensions to import paths. However, some environments require an import extension. For example, using ECMAScript modules in Node.js requires the .js extension, and Deno requires .ts. With this plugin option, you can add .js/.ts extensions in import paths with the given value. Possible values:

- import_extension=none: Doesn't add an extension. (Default)
- import_extension=js: Adds the .js extension.
- import_extension=ts. Adds the .ts extension.

$3

By default, protoc-gen-connect-query
(and all other plugins based on @bufbuild/protoplugin)
generate ECMAScript import and export statements. For use cases where
CommonJS is difficult to avoid, this option can be used to generate CommonJS
require() calls.

Possible values:

- js_import_style=module generate ECMAScript import / export statements -
the default behavior.
- js_import_style=legacy_commonjs generate CommonJS require() calls.

$3

This option exists for other plugins but is not applicable to protoc-gen-connect-query 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 will have no output.

$3

protoc-gen-connect-query generates valid TypeScript for current versions of the TypeScript compiler with standard settings. If you use compiler settings that yield an error for generated code, setting this option generates an annotation at the top of each file to skip type checks: // @ts-nocheck.

Example Generated Code

See eliza.proto` for example inputs, and look here to see the outputs those files generate.