or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

grpc-tools

grpc-tools provides essential development tools for working with gRPC in Node.js environments. It distributes the Protocol Buffers compiler (protoc) along with a specialized plugin for generating client and service objects compatible with Node gRPC libraries.

Package Information

Package Name: grpc-tools
Package Type: npm
Language: JavaScript
Installation: npm install --save-dev grpc-tools (typically as dev dependency)

Core Imports

grpc-tools is primarily a command-line tool, but exports an empty object from its main module:

const grpcTools = require("grpc-tools");
// grpcTools is {} - use CLI commands instead

Basic Usage

grpc-tools provides two main command-line executables for working with Protocol Buffers and gRPC:

# Generate JavaScript and gRPC files from proto definitions
grpc_tools_node_protoc \
  --js_out=import_style=commonjs,binary:./generated \
  --grpc_out=grpc_js:./generated \
  --plugin=protoc-gen-grpc=`which grpc_tools_node_protoc_plugin` \
  path/to/service.proto

# The plugin is automatically included, so this works too:
grpc_tools_node_protoc \
  --js_out=import_style=commonjs,binary:./generated \
  --grpc_out=grpc_js:./generated \
  service.proto

Architecture

grpc-tools consists of several key components:

Protocol Buffers Compiler: Native protoc binary for compiling .proto files
Node.js gRPC Plugin: Specialized plugin for generating Node.js-compatible gRPC code
Well-known Protobuf Definitions: Standard Google protobuf types included for compilation
Wrapper Scripts: Node.js executables that interface with the native binaries

Capabilities

Protocol Buffer Compilation

Core protoc functionality for compiling .proto files into JavaScript with full protoc feature support.

grpc_tools_node_protoc [protoc_options] [proto_files...]

# Standard protoc options supported:
# --js_out=import_style=commonjs,binary:OUTPUT_DIR
# --proto_path=IMPORT_PATHS
# --descriptor_set_out=FILE
# And all other standard protoc options

Available import styles for --js_out:

commonjs: CommonJS module format (default)
closure: Google Closure Library format
binary: Include binary serialization/deserialization support

gRPC Code Generation

Generates Node.js gRPC client and service code from .proto service definitions.

grpc_tools_node_protoc --grpc_out=[option:]OUTPUT_DIR [proto_files...]

# Available grpc_out options:
# grpc_js: Use @grpc/grpc-js library (recommended)
# generate_package_definition: Generate PackageDefinition objects
# omit_serialize_instanceof: Skip instanceof checks for messages

grpc_js option (recommended):

grpc_tools_node_protoc --grpc_out=grpc_js:./generated service.proto

generate_package_definition option:

grpc_tools_node_protoc --grpc_out=generate_package_definition:./generated service.proto

omit_serialize_instanceof option:

grpc_tools_node_protoc --grpc_out=omit_serialize_instanceof:./generated service.proto

Plugin Execution

Standalone gRPC plugin execution for use with external protoc installations.

grpc_tools_node_protoc_plugin

# Used as protoc plugin:
protoc --plugin=protoc-gen-grpc=grpc_tools_node_protoc_plugin \
       --grpc_out=./generated \
       service.proto

Well-known Protocol Buffer Types

Includes standard Google protobuf definitions available for import in .proto files.

// Available well-known types:
import "google/protobuf/any.proto";
import "google/protobuf/api.proto";
import "google/protobuf/compiler/plugin.proto";
import "google/protobuf/descriptor.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/source_context.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/type.proto";
import "google/protobuf/wrappers.proto";

Programmatic Module Export

The main module exports an empty object - the package is designed for CLI usage.

/**
 * Main module export (empty object)
 * Use CLI commands instead of programmatic API
 */
module.exports = {};

Usage Examples

Generating gRPC Code for @grpc/grpc-js

# Generate JavaScript and gRPC files for the modern gRPC library
grpc_tools_node_protoc \
  --js_out=import_style=commonjs,binary:./proto \
  --grpc_out=grpc_js:./proto \
  protos/helloworld.proto

Multiple Proto Files with Custom Import Paths

# Compile multiple protos with custom import paths
grpc_tools_node_protoc \
  --proto_path=./protos \
  --proto_path=./vendor/protos \
  --js_out=import_style=commonjs,binary:./generated \
  --grpc_out=grpc_js:./generated \
  user.proto order.proto inventory.proto

Package Definition Generation

# Generate PackageDefinition objects for use with loadPackageDefinition
grpc_tools_node_protoc \
  --js_out=import_style=commonjs,binary:./proto \
  --grpc_out=generate_package_definition:./proto \
  service.proto

# Use in Node.js:
# const packageDefinition = require('./proto/service_grpc_pb.js');
# const grpc = require('@grpc/grpc-js');
# const protoLoader = require('@grpc/proto-loader');
# const serviceProto = grpc.loadPackageDefinition(packageDefinition);

Using Well-known Types

syntax = "proto3";

import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";

service TimeService {
  rpc GetCurrentTime(google.protobuf.Empty) returns (google.protobuf.Timestamp);
}

Common Integration Patterns

npm Scripts Integration

{
  "scripts": {
    "proto:generate": "grpc_tools_node_protoc --js_out=import_style=commonjs,binary:./src/proto --grpc_out=grpc_js:./src/proto --proto_path=./protos protos/*.proto",
    "proto:clean": "rm -rf ./src/proto/*"
  }
}

Build Pipeline Integration

# Pre-build step in CI/CD
npm run proto:generate
npm test
npm run build

Error Handling

grpc-tools executables will exit with non-zero status codes on compilation errors:

Exit code 1: Compilation errors, invalid proto syntax, missing imports
Exit code 2: Invalid command-line arguments
Plugin errors: Stderr output contains detailed error messages

Common error scenarios:

Missing proto imports: Ensure --proto_path includes all import directories
Plugin not found: The plugin is automatically included with grpc_tools_node_protoc
Invalid proto syntax: Check proto file syntax against Protocol Buffers spec
Permission errors: Ensure output directories are writable