Big update!Introducing GitHub Bot Commands. Learn more
Log inDemoInstall


Package Overview
File Explorer

Advanced tools


gRPC utility library for loading .proto files


Version published
Weekly downloads
increased by11.03%

Weekly downloads



@grpc/proto-loader 0.7.4

  • Support nominal typing with type branding (#2281 contributed by @LunaTK)



gRPC Protobuf Loader

A utility package for loading .proto files for use with gRPC, using the latest Protobuf.js package. Please refer to protobuf.js' documentation to understands its features and limitations.


npm install @grpc/proto-loader


const protoLoader = require('@grpc/proto-loader'); const grpcLibrary = require('grpc'); // OR const grpcLibrary = require('@grpc/grpc-js'); protoLoader.load(protoFileName, options).then(packageDefinition => { const packageObject = grpcLibrary.loadPackageDefinition(packageDefinition); }); // OR const packageDefinition = protoLoader.loadSync(protoFileName, options); const packageObject = grpcLibrary.loadPackageDefinition(packageDefinition);

The options parameter is an object that can have the following optional properties:

Field nameValid valuesDescription
keepCasetrue or falsePreserve field names. The default is to change them to camel case.
longsString or NumberThe type to use to represent long values. Defaults to a Long object type.
enumsStringThe type to use to represent enum values. Defaults to the numeric value.
bytesArray or StringThe type to use to represent bytes values. Defaults to Buffer.
defaultstrue or falseSet default values on output objects. Defaults to false.
arraystrue or falseSet empty arrays for missing array values even if defaults is false Defaults to false.
objectstrue or falseSet empty objects for missing object values even if defaults is false Defaults to false.
oneofstrue or falseSet virtual oneof properties to the present field's name. Defaults to false.
jsontrue or falseRepresent Infinity and NaN as strings in float fields, and automatically decode google.protobuf.Any values. Defaults to false
includeDirsAn array of stringsA list of search paths for imported .proto files.

The following options object closely approximates the existing behavior of grpc.load:

const options = { keepCase: true, longs: String, enums: String, defaults: true, oneofs: true }

Generating TypeScript types

The proto-loader-gen-types script distributed with this package can be used to generate TypeScript type information for the objects loaded at runtime. More information about how to use it can be found in the @grpc/proto-loader TypeScript Type Generator CLI Tool proposal document. The arguments mostly match the load function's options; the full usage information is as follows:

proto-loader-gen-types.js [options] filenames... Options: --help Show help [boolean] --version Show version number [boolean] --keepCase Preserve the case of field names [boolean] [default: false] --longs The type that should be used to output 64 bit integer values. Can be String, Number[string] [default: "Long"] --enums The type that should be used to output enum fields. Can be String [string] [default: "number"] --bytes The type that should be used to output bytes fields. Can be String, Array [string] [default: "Buffer"] --defaults Output default values for omitted fields [boolean] [default: false] --arrays Output default values for omitted repeated fields even if --defaults is not set [boolean] [default: false] --objects Output default values for omitted message fields even if --defaults is not set [boolean] [default: false] --oneofs Output virtual oneof fields set to the present field's name [boolean] [default: false] --json Represent Infinity and NaN as strings in float fields. Also decode google.protobuf.Any automatically [boolean] [default: false] --includeComments Generate doc comments from comments in the original files [boolean] [default: false] -I, --includeDirs Directories to search for included files [array] -O, --outDir Directory in which to output files [string] [required] --grpcLib The gRPC implementation library that these types will be used with [string] [required] --inputTemplate Template for mapping input or "permissive" type names [string] [default: "%s"] --outputTemplate Template for mapping output or "restricted" type names [string] [default: "%s__Output"] --inputBranded Output property for branded type for "permissive" types with fullName of the Message as its value [boolean] [default: false] --outputBranded Output property for branded type for "restricted" types with fullName of the Message as its value [boolean] [default: false]

Example Usage

Generate the types:

$(npm bin)/proto-loader-gen-types --longs=String --enums=String --defaults --oneofs --grpcLib=@grpc/grpc-js --outDir=proto/ proto/*.proto

Consume the types:

import * as grpc from '@grpc/grpc-js'; import * as protoLoader from '@grpc/proto-loader'; import { ProtoGrpcType } from './proto/example'; import { ExampleHandlers } from './proto/example_package/Example'; const exampleServer: ExampleHandlers = { // server handlers implementation... }; const packageDefinition = protoLoader.loadSync('./proto/example.proto'); const proto = (grpc.loadPackageDefinition( packageDefinition ) as unknown) as ProtoGrpcType; const server = new grpc.Server(); server.addService(proto.example_package.Example.service, exampleServer);


What is @grpc/proto-loader?

gRPC utility library for loading .proto files

Is @grpc/proto-loader popular?

The npm package @grpc/proto-loader receives a total of 7,513,400 weekly downloads. As such, @grpc/proto-loader popularity was classified as popular.

Is @grpc/proto-loader well maintained?

We found that @grpc/proto-loader demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.It has 3 open source maintainers collaborating on the project.

Last updated on 07 Dec 2022

Did you know?

Socket installs a Github app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install Socket
Socket[email protected]


Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc