@connectrpc/connect-node

@connectrpc/connect-node

Connect is a family of libraries for building and consuming APIs on different languages and platforms, and @connectrpc/connect brings type-safe APIs with Protobuf to TypeScript.

@connectrpc/connect-node provides the following adapters for Node.js:

createConnectTransport()

Lets your clients running on Node.js talk to a server with the Connect protocol:

import { createClient } from "@connectrpc/connect";
+ import { createConnectTransport } from "@connectrpc/connect-node";
import { ElizaService } from "./gen/eliza_connect.js";

+ // A transport for clients using the Connect protocol with Node.js `http` module
+ const transport = createConnectTransport({
+   baseUrl: "https://demo.connectrpc.com",
+   httpVersion: "1.1"
+ });

const client = createClient(ElizaService, transport);
const { sentence } = await client.say({ sentence: "I feel happy." });
console.log(sentence) // you said: I feel happy.

createGrpcTransport()

Lets your clients running on Node.js talk to a server with the gRPC protocol:

import { createClient } from "@connectrpc/connect";
+ import { createGrpcTransport } from "@connectrpc/connect-node";
import { ElizaService } from "./gen/eliza_connect.js";

+ // A transport for clients using the gRPC protocol with Node.js `http2` module
+ const transport = createGrpcTransport({
+   baseUrl: "https://demo.connectrpc.com",
+ });

const client = createClient(ElizaService, transport);
const { sentence } = await client.say({ sentence: "I feel happy." });
console.log(sentence) // you said: I feel happy.

createGrpcWebTransport()

Lets your clients running on Node.js talk to a server with the gRPC-web protocol:

import { createClient } from "@connectrpc/connect";
+ import { createGrpcWebTransport } from "@connectrpc/connect-node";
import { ElizaService } from "./gen/eliza_connect.js";

+ // A transport for clients using the Connect protocol with Node.js `http` module
+ const transport = createGrpcWebTransport({
+   baseUrl: "https://demo.connectrpc.com",
+   httpVersion: "1.1"
+ });

const client = createClient(ElizaService, transport);
const { sentence } = await client.say({ sentence: "I feel happy." });
console.log(sentence) // you said: I feel happy.

connectNodeAdapter()

Run your Connect RPCs on the Node.js http, https, or http2 modules.

// connect.ts
import { ConnectRouter } from "@connectrpc/connect";

export default function (router: ConnectRouter) {
  // implement rpc Say(SayRequest) returns (SayResponse)
  router.rpc(ElizaService, ElizaService.methods.say, async (req) => ({
    sentence: `you said: ${req.sentence}`,
  }));
}

// server.ts
import * as http2 from "http2";
+ import routes from "connect";
+ import { connectNodeAdapter } from "@connectrpc/connect-node";
+ import { createValidateInterceptor } from "@connectrpc/validate";

http2.createServer(
+ connectNodeAdapter({
+   // Validation via Protovalidate is almost always recommended
+   interceptors: [createValidateInterceptor()],
+   routes
+ })
).listen(8080);

With that server running, you can make requests with any gRPC, gRPC-Web, or Connect client.

buf curl with the gRPC protocol:

buf curl --schema buf.build/connectrpc/eliza \
  --protocol grpc --http2-prior-knowledge \
  -d '{"sentence": "I feel happy."}' \
  http://localhost:8080/connectrpc.eliza.v1.ElizaService/Say

curl with the Connect protocol:

curl \
    --header "Content-Type: application/json" \
    --data '{"sentence": "I feel happy."}' \
     --http2-prior-knowledge \
    http://localhost:8080/connectrpc.eliza.v1.ElizaService/Say

Node.js with the gRPC protocol:

import { createClient } from "@connectrpc/connect";
import { createGrpcTransport } from "@connectrpc/connect-node";
import { ElizaService } from "./gen/eliza_connect.js";

const transport = createGrpcTransport({
  baseUrl: "http://localhost:8080",
});

const client = createClient(ElizaService, transport);
const { sentence } = await client.say({ sentence: "I feel happy." });
console.log(sentence); // you said: I feel happy.

A client for the web browser actually looks identical to this example - it would simply use createConnectTransport from @connectrpc/connect-web instead.

Getting started

To get started with Connect, head over to the docs for a tutorial, or take a look at our example.

Similar packages

Other packages similar to @connectrpc/connect-node

grpc

The grpc package is a popular choice for implementing gRPC in Node.js applications. It provides comprehensive support for gRPC, including streaming and unary calls, and is widely used in production environments. Compared to @connectrpc/connect-node, grpc is more established and has a larger community, but it is specifically tied to the gRPC protocol, whereas @connectrpc/connect-node supports the Connect protocol, which can be more flexible in certain scenarios.

@grpc/grpc-js

@grpc/grpc-js is a pure JavaScript implementation of gRPC for Node.js, designed to replace the native grpc package. It offers similar functionality to grpc but without the need for native code compilation, making it easier to use in environments where native dependencies are problematic. Like grpc, it is focused on the gRPC protocol, while @connectrpc/connect-node offers support for the Connect protocol.

grpc-web

grpc-web is a package that allows gRPC to be used in web applications by providing a JavaScript client library. It is designed to work with a proxy that translates between gRPC and HTTP/1.1. While grpc-web is specifically for web clients, @connectrpc/connect-node can be used for both server and client implementations in Node.js, offering more flexibility in server-side applications.