Registry / serialization / protobufjs-loader

protobufjs-loader

library3.1.1jsnpmunverified

Webpack loader for translating .proto definitions into protobuf.js modules, equivalent to running the pbjs CLI at build time. Current stable version is 3.1.1, released January 2025 with async/await refactor and custom TypeScript output locations. Requires webpack ^5.0.0 (breaking change from v2 to v3 dropped webpack 4 support). Supports both static-module and json-module targets, and optional pbts TypeScript declaration generation. Alternatives: grpc-tools or manual pbjs invocation. Release cadence irregular, maintained by kmontag.

serialization web-framework

npm install protobufjs-loader

github ↗package ↗

INSTALL

IMPORT

SIG · PROTOBUFJS-LOADER

protobufjs-loader

serializationjavascriptv3.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

Root (from .proto)

✓ import Root from './my.proto';

✗ const protobuf = require('protobufjs/light'); const json = require('json!./my.proto'); const Root = protobuf.Root.fromJSON(json);

Loader returns a protobuf.js Root object directly; no need to compile separately.

protobufjs-loader module rule

✓ module: { rules: [ { test: /\.proto$/, use: 'protobufjs-loader' } ] }

✗ module: { rules: [ { test: /\.proto$/, loader: 'protobufjs' } ] }

Loader name is 'protobufjs-loader', not 'protobufjs'.

require/proto with callback

✓ const Root = require('./my.proto');

✗ const root = require('./lib/compiled.json');

Loader returns a synchronous Root object; no async callbacks needed.

Configure webpack to load .proto files via protobufjs-loader, then import them as Root objects in your code.

// webpack.config.js module.exports = { module: { rules: [ { test: /\.proto$/, use: { loader: 'protobufjs-loader', options: { target: 'static-module', pbts: true } } } ] } }; // myModule.js import Root from './my.proto'; // Root is a protobuf.js Root instance, ready to use const MyMessage = Root.lookupType('MyMessage'); const message = MyMessage.create({ field1: 'value' }); const buffer = MyMessage.encode(message).finish(); console.log('Encoded message:', buffer);

Debug

Known issues

breakingprotobufjs-loader v3 drops webpack 4 support; only webpack 5 is supported.

fix

Upgrade to webpack ^5.0.0, or stay on v2.x if you need webpack 4.

affects: >=3.0.0

breakingprotobufjs-loader v2 drops Node.js <12.0.0 and updates protobufjs to ^7.0.0.

fix

Upgrade Node to >=12.0.0 and ensure compatibility with protobufjs v7.

affects: >=2.0.0 <3.0.0

deprecatedpbts output function signature changed in v3.1.0.

fix

If using pbts output option, the function now receives (protobufFile) and returns a path or promise. See docs.

affects: <3.1.0

gotchaUsing require() with .proto files requires webpack and protobufjs-loader configured.

fix

Ensure the loader is applied to .proto files, and that protobufjs is installed (as a direct dependency, not just dev).

affects: all

gotchapbts generation only works with 'static-module' target (default).

fix

Set target to 'static-module' or omit the option to use default.

affects: all

Errors

Common errors & fixes

Module not found: Error: Can't resolve 'protobufjs' in ...

protobufjs is not installed as a dependency.

fix

Run: npm install protobufjs

Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type.

Webpack is not configured to use protobufjs-loader for .proto files.

fix

Add protobufjs-loader rule to webpack.config.js: { test: /\.proto$/, use: 'protobufjs-loader' }

Error: pbjs failed: Error: unknown option `--no-encode'

Passed an invalid pbjs argument.

fix

Check valid pbjs CLI options. Common valid args: --target, --path, --no-create, --no-verify, --no-convert, --no-delimited, --no-beautify, --no-comments, --no-service, --no-typeurl, --no-stream

TypeError: Cannot read properties of undefined (reading 'protobufFile')

pbts output function is not a function or invalid.

fix

Ensure pbts.output is a function returning a string, e.g., (file) => `${file}.d.ts`

Upgrade

Version history

3.1.1latest on npm

Audit

Dependencies

webpackoptionalpeer dependency

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/kmontag/protobufjs-loader ↗

packagehttps://www.npmjs.com/package/protobufjs-loader ↗