@connectrpc/connect

What is @connectrpc/connect?

@connectrpc/connect is an npm package designed to facilitate the creation and management of RPC (Remote Procedure Call) connections. It provides tools for defining, implementing, and consuming RPC services, making it easier to build distributed systems and microservices.

What are @connectrpc/connect's main functionalities?

Defining RPC Services

This feature allows you to define RPC services with specific methods. In this example, a service named 'MyService' is created with a method 'sayHello' that takes a 'HelloRequest' and returns a 'HelloResponse'.

const { Service } = require('@connectrpc/connect');

const myService = new Service({
  name: 'MyService',
  methods: {
    sayHello: {
      requestType: 'HelloRequest',
      responseType: 'HelloResponse',
      handler: (request) => {
        return { message: `Hello, ${request.name}!` };
      }
    }
  }
});

Implementing RPC Clients

This feature allows you to implement RPC clients that can communicate with the defined services. In this example, a client is created to connect to 'MyService' and call the 'sayHello' method.

const { Client } = require('@connectrpc/connect');

const client = new Client({
  service: myService,
  address: 'http://localhost:5000'
});

client.sayHello({ name: 'World' }).then(response => {
  console.log(response.message); // Output: Hello, World!
});

Handling RPC Requests

This feature allows you to handle incoming RPC requests by starting a server. In this example, a server is created to handle requests for 'MyService' on port 5000.

const { Server } = require('@connectrpc/connect');

const server = new Server({
  services: [myService],
  port: 5000
});

server.start().then(() => {
  console.log('Server is running on port 5000');
});

Other packages similar to @connectrpc/connect

grpc

The 'grpc' package is a popular library for implementing gRPC (Google Remote Procedure Call) in Node.js. It provides similar functionalities to @connectrpc/connect, such as defining services, creating clients, and handling requests. However, 'grpc' is more widely adopted and has a larger community.

grpc-web

The 'grpc-web' package allows gRPC to be used in web applications. It provides a JavaScript client library that can communicate with gRPC services. While @connectrpc/connect focuses on general RPC connections, 'grpc-web' is specifically designed for web environments.

protobufjs

The 'protobufjs' package is a library for working with Protocol Buffers in JavaScript. It can be used to define and serialize messages for RPC services. While it does not provide the full RPC framework like @connectrpc/connect, it is often used in conjunction with other RPC libraries.

README

@connectrpc/connect

Connect is a family of libraries for building type-safe APIs with different languages and platforms. @connectrpc/connect brings them to TypeScript, the web browser, and to Node.js.

With Connect, you define your schema first:

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

And with the magic of code generation, this schema produces servers and clients:

const answer = await eliza.say({ sentence: "I feel happy." });
console.log(answer);
// {sentence: 'When you feel happy, what do you do?'}

Unlike REST, the RPCs you use with Connect are typesafe end to end, but they are regular HTTP under the hood. You can see all requests in the network inspector, and you can curl them if you want:

curl \
    --header 'Content-Type: application/json' \
    --data '{"sentence": "I feel happy."}' \
    https://demo.connectrpc.com/connectrpc.eliza.v1.ElizaService/Say

With Connect for ECMAScript, you can spin up a service in Node.js and call it from the web, the terminal, or native mobile clients. Under the hood, it uses Protocol Buffers for the schema, and implements RPC (remote procedure calls) with three protocols: The widely available gRPC and gRPC-web, and Connect's own protocol, optimized for the web. This gives you unparalleled interoperability with full-stack type-safety.

Get started on the web

Follow our 10 minute tutorial where we use Vite and React to create a web interface for ELIZA.

React, Svelte, Vue, Next.js and Angular are supported (see examples), and we have an expansion pack for TanStack Query. We support all modern web browsers that implement the widely available fetch API and the Encoding API.

Get started on Node.js

Follow our 10 minute tutorial to spin up a service in Node.js, and call it from the web, and from a gRPC client in your terminal.

You can use vanilla Node.js, or our server plugins for Fastify or Express. We support the builtin http, and http2 modules on Node.js v18.14.1 and later.