connect-es

@connectrpc/connect is the core TypeScript library behind Connect, a family of RPC frameworks built on Protobuf schemas. It generates fully typed clients and servers directly from your .proto definitions, letting you call remote procedures like ordinary async functions while the underlying wire protocol stays interchangeable between Connect’s own HTTP-friendly protocol, gRPC, and gRPC-Web.

On the server side, a ConnectRouter registers service implementations that any Connect-compatible adapter (Node.js, Fastify, Express, Next.js, Cloudflare Workers) can serve; on the client side, createClient and createCallbackClient produce promise- or callback-based clients with interceptor support for cross-cutting concerns like auth and logging. Structured errors (ConnectError) carry gRPC-style status codes and typed details, so failures are as strongly typed as successful responses.

What You Get

• Typed client generation via createClient/createCallbackClient from your Protobuf service schema
• A ConnectRouter for implementing RPC services and wiring them into any HTTP adapter
• Support for three interoperable wire protocols: Connect, gRPC, and gRPC-Web
• ConnectError with gRPC-compatible status codes and structured, typed error details
• An interceptor chain for cross-cutting request/response logic (auth, logging, tracing)
• A CORS helper and an in-process router transport for testing handlers without a network

Common Use Cases

• Building a type-safe internal RPC layer between TypeScript services without hand-written REST clients
• Serving the same RPC implementation over Connect, gRPC, and gRPC-Web from one codebase
• Adding request/response interceptors for auth tokens, logging, or Protovalidate validation
• Calling RPCs directly from a browser app over plain HTTP, without standing up a gRPC-Web proxy

Under The Hood

Architecture

Connect’s core package layers three RPC protocols behind one shared abstraction: src/protocol/universal-handler.ts defines UniversalHandler/UniversalHandlerOptions, and each protocol (protocol-connect, protocol-grpc, protocol-grpc-web) implements its own handler-factory.ts satisfying a common ProtocolHandlerFactory interface; router.ts’s createConnectRouter() collects service implementations via createServiceImplSpec/createMethodImplSpec (from implementation.ts) and dispatches them through all three factories at once, so one ConnectRouter produces handlers servable over any protocol. On the client side, promise-client.ts and callback-client.ts both build on any-client.ts’s makeAnyClient, which walks a DescService’s methods and wraps each one using the shared Transport interface, so adding a new client flavor means implementing one interface rather than rewriting call dispatch. Cross-cutting concerns run through interceptor.ts’s composable chain, applied uniformly to unary and streaming calls on both client and server; changing the core DescService/DescMethod abstraction from @bufbuild/protobuf would ripple through every layer, since router, client, and all three protocol handlers key off it directly.

Tech Stack

Pure TypeScript compiled twice per package (build:cjs targeting CommonJS, build:esm for native ESM) to ship dual-format output, with attw (Are The Types Wrong) run in CI to catch package.json/exports misconfiguration. The only runtime dependency is a peer dependency on @bufbuild/protobuf (Protobuf-ES) for schema types and message (de)serialization; there is no HTTP framework dependency in this package itself, since the actual server runtime is supplied by sibling adapter packages (@connectrpc/connect-node, -fastify, -express, -next, -cloudflare) in the same Turborepo monorepo. Turborepo orchestrates builds/tests/lint across the workspace packages, Biome handles both linting and formatting in one tool, and a CI matrix across multiple Node.js versions pins the supported runtime range.

Code Quality

Tests are colocated as spec files next to their source, run with Node’s built-in test runner via tsx, and the test command also runs a type-check first so type errors fail the same gate as unit tests. Error handling is explicit and typed throughout: ConnectError carries a Code enum and optional structured Protobuf “details,” and public APIs return or throw this type rather than raw strings or untyped exceptions. Exported symbols carry consistent JSDoc comments explaining intent, and a license-header script plus a CI diff-check enforce a copyright header on every source file. CI runs formatting, license-header, linting with warnings-as-errors, type-export validation, bundle-size regression checks, and a full build/test matrix across three Node.js versions.

API Design The package’s core idea — one Protobuf schema, three wire-compatible protocols served or called through one identical client/router API — means protocol selection happens in the adapter/transport layer instead of in application code, so teams aren’t locked into gRPC vs. a REST-like protocol upfront. This is a distinctive design choice for a TypeScript RPC library: most TypeScript RPC tooling commits to a single non-standard wire format, while this library interops with existing gRPC infrastructure alongside a plain-HTTP-friendly protocol of its own. The developer-facing surface stays small — createClient, createConnectRouter, Interceptor, and ConnectError cover most usage — with type inference from the generated service schema doing the work of avoiding boilerplate.