Registry / devops / grpc-alt-proto-loader

grpc-alt-proto-loader

library0.5.0jsnpmunverified

Utility package for loading .proto files for gRPC, using Protobuf.js. Version 0.5.0 runs on Node >=6 and ships TypeScript types. It provides both async (load) and sync (loadSync) loading of protobuf definitions, returning a package definition object that can be consumed by gRPC libraries (grpc or @grpc/grpc-js). Supports options like keepCase, longs, enums, bytes, defaults, arrays, objects, oneofs, and includeDirs. It is the recommended replacement for the deprecated grpc.load(). Community-maintained, part of the grpc-node monorepo.

devops

npm install grpc-alt-proto-loader

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRPC-ALT-PROTO-LOA

grpc-alt-proto-loader

devopsjavascriptv0.5.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

load

✓ import { load } from '@grpc/proto-loader'

✗ const protoLoader = require('@grpc/proto-loader'); const load = protoLoader.default.load;

ESM named export. Also available as a property of the default export in CommonJS.

loadSync

✓ import { loadSync } from '@grpc/proto-loader'

✗ const { loadSync } = require('@grpc/proto-loader');

Valid both as ESM named import and CommonJS destructure.

default export

✓ import protoLoader from '@grpc/proto-loader'

✗ const protoLoader = require('@grpc/proto-loader').default;

Default export is an object with load and loadSync functions. CommonJS require returns the same object, not a default property.

GrpcObject

✓ import type { GrpcObject } from '@grpc/proto-loader'

TypeScript type export, only available as a type import.

Loads a .proto file synchronously and creates a gRPC client using @grpc/grpc-js.

import { loadSync } from '@grpc/proto-loader'; import { loadPackageDefinition, credentials } from '@grpc/grpc-js'; const packageDefinition = loadSync('helloworld.proto', { keepCase: true, longs: String, enums: String, defaults: true, oneofs: true, }); const helloProto = loadPackageDefinition(packageDefinition).helloworld; const client = new helloProto.Greeter('localhost:50051', credentials.createInsecure()); client.sayHello({ name: 'world' }, (err, response) => { console.log('Greeting:', response.message); });

Debug

Known issues

gotchaload() and loadSync() return package definitions compatible with grpc.loadPackageDefinition, but the format differs from grpc.load() output.

fix

Always use grpc.loadPackageDefinition (or @grpc/grpc-js equivalent) to convert the result.

affects: >=0.1.0

deprecatedThe 'grpc' package (non-@grpc) is deprecated in favor of @grpc/grpc-js.

fix

Use @grpc/grpc-js instead of grpc.

affects: >=0.5.0

gotchaOptions keepCase: false (default) converts field names to camelCase, which may break existing code expecting original names.

fix

Set keepCase: true to preserve original field names.

affects: >=0.1.0

gotchaUsing longs: String converts Long values to strings, which may lose numeric precision for very large numbers.

fix

Use longs: Number for 64-bit integers within safe integer range, or leave default (Long object) for full precision.

affects: >=0.1.0

gotchaThe enum option defaults to numeric values; setting enums: String returns enum names instead.

fix

Explicitly set enums: String if you need names, or leave default for numbers.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Package definition is not a valid gRPC package definition

The result of load/loadSync was directly used as a gRPC object without calling loadPackageDefinition.

fix

Always pass the package definition to grpc.loadPackageDefinition (or @grpc/grpc-js equivalent).

Cannot find module '@grpc/proto-loader'

Package not installed, or using wrong import path.

fix

Install: npm install @grpc/proto-loader

TypeError: protoLoader.loadSync is not a function

CommonJS require returns the module exports directly; the function is named loadSync.

fix

Use const { loadSync } = require('@grpc/proto-loader'); or const protoLoader = require('@grpc/proto-loader'); then protoLoader.loadSync().

Upgrade

Version history

0.5.0latest on npm

Audit

Dependencies

protobufjsrequiredCore library for parsing .proto files

lodash.camelcaserequiredUsed for camelCase conversion of field names when keepCase is false

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/grpc/grpc-node ↗

packagegrpc-alt-proto-loader ↗

homepagehttps://grpc.io/ ↗