Getting started

Connect-Node is a library for serving Connect, gRPC, and gRPC-Web compatible HTTP APIs using Node.js. It brings the Connect Protocol to Node with full TypeScript compatibility and support for all four types of remote procedure calls: unary and the three variations of streaming.

This ten-minute walkthrough helps you create a small Connect service in Node.js. It demonstrates what you'll be writing by hand, what Connect generates for you, and how to call your new API.

Prerequisites

We'll set up a project from scratch and then augment it to serve a new endpoint.

• You'll need Node.js installed - we recommend the most recent long-term support version (LTS).
• We'll use the package manager npm, but we are also compatible with yarn and pnpm.
• We'll also use cURL. It's available from Homebrew and most Linux package managers.

Project setup

Let's initialize a project with TypeScript, and install some code generation tools:

$ mkdir connect-example
$ cd connect-example
$ npm init -y
$ npm install typescript tsx
$ npx tsc --init
$ npm install @bufbuild/buf @bufbuild/protobuf @bufbuild/protoc-gen-es @connectrpc/connect

Define a service

First, we need to add a Protobuf file that includes our service definition. For this tutorial, we are going to construct a unary endpoint for a service that is a stripped-down implementation of ELIZA, the famous natural language processing program.

$ mkdir -p proto && touch proto/eliza.proto

Open up the above file and add the following service definition:

syntax = "proto3";

package connectrpc.eliza.v1;

message SayRequest {
  string sentence = 1;
}

message SayResponse {
  string sentence = 1;
}

service ElizaService {
  rpc Say(SayRequest) returns (SayResponse) {}
}

Generate code

We're going to generate our code using Buf, a modern replacement for Google's protobuf compiler. We installed Buf earlier, but we also need a configuration file to get going. (If you'd prefer, you can skip this section and use protoc instead — protoc-gen-es behaves like any other plugin.)

First, scaffold a basic buf.yaml at the root of your repository:

$ npx buf config init

Then, edit buf.yaml to use our proto directory:

version: v2
modules:
  - path: proto
lint:
  use:
    - DEFAULT
breaking:
  use:
    - FILE

Next, tell Buf how to generate code by putting this into buf.gen.yaml:

version: v2
plugins:
  - local: protoc-gen-es
    out: gen
    # Also generate any imported dependencies
    include_imports: true
    opt: target=ts

With those configuration files in place, you can lint your schema and generate code:

$ npx buf lint
$ npx buf generate

You should now see a generated TypeScript file:

.
├── buf.gen.yaml
├── buf.yaml
├── gen
│   └── eliza_pb.ts
├── node_modules
├── package-lock.json
├── package.json
├── proto
│   └── eliza.proto
└── tsconfig.json

Next, we are going to use these files to implement our service.

Implement the service

We defined the ElizaService - now it's time to implement it, and register it with the ConnectRouter. First, let's create a file where we can put the implementation:

Create a new file connect.ts with the following contents:

import type { ConnectRouter } from "@connectrpc/connect";
import { ElizaService } from "./gen/eliza_pb";

export default (router: ConnectRouter) =>
  // registers connectrpc.eliza.v1.ElizaService
  router.service(ElizaService, {
    // implements rpc Say
    async say(req) {
      return {
        sentence: `You said: ${req.sentence}`
      }
    },
  });

That's it! There are many other alternatives to implementing a service, and you have access to a context object for headers and trailers, but let's keep it simple for now.

Start a server

Connect services can be plugged into vanilla Node.js servers, Next.js, Express, or Fastify. We are going to use Fastify here. Let's install it, along with our plugin for Fastify:

$ npm install fastify @connectrpc/connect-node @connectrpc/connect-fastify

Create a new file server.ts with the following contents:

import { fastify } from "fastify";
import { fastifyConnectPlugin } from "@connectrpc/connect-fastify";
import routes from "./connect";

async function main() {
  const server = fastify();
  await server.register(fastifyConnectPlugin, {
    routes,
  });
  server.get("/", (_, reply) => {
    reply.type("text/plain");
    reply.send("Hello World!");
  });
  await server.listen({ host: "localhost", port: 8080 });
  console.log("server is listening at", server.addresses());
}
// You can remove the main() wrapper if you set type: module in your package.json,
// and update your tsconfig.json with target: es2017 and module: es2022.
void main();

Congratulations. Your endpoint is ready to go! You can start your server with:

$ npx tsx server.ts

Make requests

The simplest way to consume your new API is an HTTP/1.1 POST with a JSON payload. If you have a recent version of cURL installed, it's a one-liner:

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

You can also make requests using a Connect client. Create a new file client.ts with the following contents:

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

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

async function main() {
  const client = createClient(ElizaService, transport);
  const res = await client.say({ sentence: "I feel happy." });
  console.log(res);
}
void main();

With your server still running in a separate terminal window, you can now run your client:

$ npx tsx client.ts
Output
SayResponse { sentence: 'You said: I feel happy.' }

Congratulations — you've built your first Connect service! 🎉

From the browser

You can run the same client from a web browser, just by swapping out the Transport:

import { createClient } from "@connectrpc/connect";
import { ElizaService } from "./gen/eliza_pb";
import { createConnectTransport } from "@connectrpc/connect-web";

const transport = createConnectTransport({
  baseUrl: "http://localhost:8080",
  // Not needed. Web browsers use HTTP/2 automatically.
  // httpVersion: "1.1"
});

async function main() {
  const client = createClient(ElizaService, transport);
  const res = await client.say({ sentence: "I feel happy." });
  console.log(res);
}
void main();

Use the gRPC protocol instead of the Connect protocol

On Node.js, we support three protocols:

• The gRPC protocol that is used throughout the gRPC ecosystem.
• The gRPC-Web protocol used by grpc/grpc-web, allowing servers to interop with grpc-web frontends without the need for an intermediary proxy (such as Envoy).
• The new Connect protocol, a simple, HTTP-based protocol that works over HTTP/1.1 or HTTP/2. It takes the best portions of gRPC and gRPC-Web, including streaming, and packages them into a protocol that works equally well in browsers, monoliths, and microservices. The Connect protocol is what we think the gRPC protocol should be. By default, JSON- and binary-encoded Protobuf is supported.

So far, we have been using the http:// scheme in our examples. We were not using TLS (Transport Layer Security). If you want to use gRPC and browser clients during local development, you need TLS.

Actually, that only takes a minute to set up! We will use mkcert to make a certificate. If you don't have it installed yet, please run the following commands:

brew install mkcert
mkcert -install
mkcert localhost 127.0.0.1 ::1
export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"

If you don't use macOS or brew, see the mkcert docs for instructions. You can copy the last line to your ~/.zprofile or ~/.profile, so that the environment variable for Node.js is set every time you open a terminal.

If you already use mkcert, just run mkcert localhost 127.0.0.1 ::1 to issue a certificate for our example server.

Let's update our server.ts to use this certificate:

import { fastify } from "fastify";
import { fastifyConnectPlugin } from "@connectrpc/connect-fastify";
import routes from "./connect";
import { readFileSync } from "fs";

async function main() {
  const server = fastify({
    http2: true,
    https: {
      key: readFileSync("localhost+2-key.pem", "utf8"),
      cert: readFileSync("localhost+2.pem", "utf8"),
    }
  });
  await server.register(fastifyConnectPlugin, {
    routes,
  });
  await server.listen({ host: "localhost", port: 8443 });
  console.log("server is listening at", server.addresses());
}
void main();

That's it! After you restarted the server, you can still open https://localhost:8443/ in your browser, but along with gRPC-Web and Connect, any gRPC client can access it too. Here's an example using buf curl:

npx buf curl --protocol grpc --schema . -d '{"sentence": "I feel happy."}' \
   https://localhost:8443/connectrpc.eliza.v1.ElizaService/Say

In your client.ts, update the URL and use HTTP version 2 and you're set. It will pick up the locally-trusted certificate authority, just like your web browser and other apps.

So what?

With just a few lines of hand-written code, you've built a real API server that supports both the gRPC and Connect protocols. Unlike a hand-written REST service, you didn't need to design a URL hierarchy, hand-write request and response objects, or parse typed values out of query parameters. More importantly, your users got an idiomatic, type-safe client without any extra work on your part.