repository·main·Indexed 23 days ago
https://github.com/connectrpc/connect-esA family of libraries for building type-safe APIs across TypeScript, web browsers, and Node.js. Includes support for various frameworks and environments via packages such as @connectrpc/connect-express, @connectrpc/connect-fastify, @connectrpc/connect-next, and @connectrpc/connect-cloudflare. The ecosystem provides tools for protocol support (Connect, gRPC-Web), conformance testing, and a migration tool (@connectrpc/connect-migrate) to transition projects to the @connectrpc organization.
Connect Conformance is a package that provides common artifacts and functionality used to run conformance tests against Connect-ES packages (such as @connectrpc/connect-node or @connectrpc/connect-web).
Note: This package does not execute the tests itself; it exports the necessary tools and logic for other packages to perform conformance testing.
Connect is a family of libraries for building type-safe APIs across different languages and platforms. The @connectrpc/connect package provides TypeScript support for web browsers and Node.js.
It follows a schema-first approach using Protocol Buffers. Once a schema is defined, code generation produces type-safe servers and clients. While the RPCs are type-safe end-to-end, they use regular HTTP under the hood, making them compatible with standard tools like curl and visible in network inspectors.
Connect supports three protocols:
This allows for high interoperability between Node.js services and clients running in web browsers, terminals, or native mobile environments.
service ElizaService {
rpc Say(SayRequest) returns (SayResponse) {}
}const answer = await eliza.say({ sentence: "I feel happy." });
console.log(answer);
// {sentence: 'When you feel happy, what do you do?'}curl \
--header 'Content-Type: application/json' \
--data '{"sentence": "I feel happy."}' \
https://demo.connectrpc.com/connectrpc.eliza.v1.ElizaService/SayIn Connect v2, API calls are strictly typed. You can no longer pass a message object that is a superset of the target type (e.g., passing MessageB to a method expecting MessageA). Only the exact specified target type will pass TypeScript compilation.
To pass a message with the same fields as a different message type, use object destructuring to remove the $typeName property before creating the new message.
// If you need to convert MessageA to MessageB by dropping the type name:
const messageA: MessageA = ...;
const { $typeName: _, ...properties } = messageA;
const messageB = create(MessageBSchema, properties);Connect is a type-safe RPC protocol that runs over regular HTTP. It is compatible with curl and can be inspected via standard network tools. Connect implements three protocols to ensure interoperability:
Connect uses Protobuf-ES for Protobuf compliance.
In Connect v2, the protoc-gen-connect-es plugin has been removed. Connect now relies on service descriptors generated by the Protobuf-ES v2 plugin protoc-gen-es. You must remove @connectrpc/protoc-gen-connect-es from your package.json.
Compatible dependencies should look similar to this:
"dependencies": {
"@bufbuild/protobuf": "^2.2.0",
"@bufbuild/protoc-gen-es": "^2.2.0",
"@connectrpc/connect": "^2.0.0",
- "@connectrpc/protoc-gen-connect-es": "^1.0.0",
"@connectrpc/connect-web": "^2.0.0",
"@connectrpc/connect-node": "^2.0.0",
"@connectrpc/connect-next": "^2.0.0",
"@connectrpc/connect-fastify": "^2.0.0",
"@connectrpc/connect-express": "^2.0.0",
"@connectrpc/connect-query": "^2.0.0",
"@connectrpc/protoc-gen-connect-query": "^2.0.0",
"@connectrpc/connect-playwright": "^0.6.0"
}Note: The connect-migrate tool handles these dependency updates automatically.
To verify that your @connectrpc/connect-fastify implementation correctly adheres to the Connect protocol, you can run the conformance tests. This implementation follows the conformance service specification. The tests are executed using the conformance runner via an npm script.
npm run conformanceIn Protobuf-ES v2, messages are no longer generated as classes. Instead, they are generated as a schema object and a plain TypeScript type.
Key changes:
create function from @bufbuild/protobuf with the schema instead of the new keyword.toBinary, equals, clone, toJson, toJsonString).$typeName property instead of .getType().typeName.isMessage(x, Schema) instead of isMessage(x, Class).PlainMessage<T> and PartialMessage<T> have been removed. Use the message type directly or Omit<T, "$typeName"> if you need to exclude the type name.The connect-migrate tool does not automatically upgrade generated SDKs. To upgrade from v1 to v2, follow these four steps:
connectrpc_es plugin. These are typically named @buf/{module_owner}_{module_name}.connectrpc_es.npx @connectrpc/connect-migrate@latest to update your @connect and @bufbuild package dependencies.bufbuild_es). For example, replace @buf/googleapis_googleapis.connectrpc_es with @buf/googleapis_googleapis.bufbuild_es@latest..connect.js to _pb.js).You can run conformance tests for both clients and servers for the @connectrpc/connect-cloudflare package using the conformance:client and conformance:server tasks. This is typically done via turbo in the repository environment.
To run both client and server conformance tests, use the following command:
npx turbo run --filter @connectrpc/connect-cloudflare conformance:client conformance:serverYou can integrate Connect RPCs into a Fastify server using the fastifyConnectPlugin. This plugin allows your server to handle gRPC, gRPC-Web, and Connect protocol requests.
When registering the plugin, you provide a routes object (a ConnectRouter) and can optionally provide interceptors, such as the createValidateInterceptor from @connectrpc/validate for request validation.
Note: For optimal performance with gRPC, it is recommended to enable http2: true in your Fastify configuration.
import { fastify } from "fastify";
import routes from "connect";
import { fastifyConnectPlugin } from "@connectrpc/connect-fastify";
import { createValidateInterceptor } from "@connectrpc/validate";
const server = fastify({
http2: true,
});
await server.register(fastifyConnectPlugin, {
// Validation via Protovalidate is almost always recommended
interceptors: [createValidateInterceptor()],
routes
});
await server.listen({
host: "localhost",
port: 8080,
});Conformance tests for @connectrpc/connect-web can be run in several environments and with two different client flavors. The tests implement the conformance service described in the Connect documentation.
createClientcreateCallbackClientUse the following pattern to run tests: npx turbo run conformance:<environment>:<flavor>
npx turbo run conformance:chrome:promiseConnect v2 introduces new features, simplifies APIs, and leverages Protobuf-ES v2.
@connectrpc/connect-migrate tool to automate dependency updates, plugin updates, and minor code changes.npx @connectrpc/connect-migrate@latest