@connectrpc/connect-node

What is @connectrpc/connect-node?

@connectrpc/connect-node is a package designed to facilitate the implementation of RPC (Remote Procedure Call) systems using the Connect protocol in Node.js applications. It provides tools for building both clients and servers that can communicate over HTTP/2, HTTP/1.1, and WebSockets, making it versatile for various network environments.

What are @connectrpc/connect-node's main functionalities?

Creating a Connect RPC Client

This feature allows you to create a Connect RPC client that can communicate with a Connect RPC server. The code sample demonstrates how to initialize a client with a base URL and a service definition, and then make a call to a method on that service.

const { createConnectClient } = require('@connectrpc/connect-node');
const client = createConnectClient({
  baseUrl: 'https://example.com',
  service: MyService,
});
const response = await client.myMethod({ myParameter: 'value' });

Setting up a Connect RPC Server

This feature enables you to set up a Connect RPC server that listens for incoming RPC calls. The code sample shows how to create a server with a list of services and start it on a specified port.

const { createConnectServer } = require('@connectrpc/connect-node');
const server = createConnectServer({
  services: [MyService],
  port: 8080,
});
server.start();

Handling Streaming RPCs

This feature supports streaming RPCs, allowing for bidirectional data flow between client and server. The code sample illustrates how to define a streaming method within a service, processing incoming items and yielding results back to the client.

const { createConnectServer } = require('@connectrpc/connect-node');
const server = createConnectServer({
  services: [
    {
      name: 'MyStreamingService',
      methods: {
        myStreamingMethod: async function* (request) {
          for (const item of request.items) {
            yield { result: processItem(item) };
          }
        }
      }
    }
  ],
  port: 8080,
});
server.start();

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.

README

@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",
+   httpVersion: "2"
+ });

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";

http2.createServer(
+ connectNodeAdapter({ routes }) // responds with 404 for other requests
).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",
  httpVersion: "2",
});

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.