README.md

TypeScript Node.js gRPC Demo

This is a demo project to showcase a gRPC server and client for Node.js with TypeScript.

Features

• TypeScript for client and server:
  • nice-grpc(npm) for the main gRPC client and server
• Schema-first protobuf definitions with code generation
  • ts-proto (npm) for TypeScript codegen
  • @bufbuild/buf (npm) for CLI build using ts-proto
• Schema linting for best practices
  • @bufbuild/buf (npm) for CLI linting and lint rules definition
• Server reflection for introspection from client
  • nice-grpc-server-reflection (npm) to enable reflection in the server
  • @bufbuild/buf (npm) for CLI generation of binaries needed for server reflection
• Code generation for client with reflection
  • fullstorydev/grpcurl (github) for server reflection from client
  • @bufbuild/buf (npm) for CLI client codegen from reflection binaries
• Server health check procedures
  • nice-grpc-server-health (npm) for implementation of gRPC health v1 standard
• Server middlewares
  • nice-grpc-server-terminator (npm) to facilitate server graceful shutdown
• Client middlewares
  • nice-grpc-client-middleware-deadline (npm) for cancelling calls upon deadlines
  • nice-grpc-client-middleware-retry (npm) for automatic retries to idempotent calls
• OpenTelemetry tracing
  • nice-grpc-opentelemetry (npm) for server tracing with OpenTelemetry instrumentation

Requirements

• Node.js 20.x (if not using direnv with nix-shell)
• Docker for usage of grpcurl to run client introspection of server reflection

Setup

1. (Optional) If using direnv with nix-shell, run direnv allow
2. Run npm install to install dependencies
3. For ./server and ./client, run cp .env.sample .env to create environment files
4. In both .env files, replace <server-token-here> with the same string to use as auth token

Usage

Server

• npm run dev: to start the server for development in watch mode
• npm run serve: to build and start the server in production mode
• npm run build: to codegen the Protobuf schema and build the source
• npm run proto:build: to only codegen the Protobuf schema
• npm run server:build: to only build the server source
• npm start: to start the server in production mode (manual build is needed before)

Client

To run the client, the server must be running in the address specified in the .env file (localhost:50051 by default).

• npm run dev: to start the client in development in watch mode
• npm run serve: to build and start the client in production mode
• npm run proto: to run the client codegen from server reflection (requires Docker)
• npm run build: to build the client source
• npm start: to start the client in production mode (manual build is needed before)