protobufjs-loader

3.1.1 verified Sat Apr 25 auth: no javascript

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.

Common errors

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

cause protobufjs is not installed as a dependency.

fix

Run: npm install protobufjs

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

cause 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 Error: pbjs failed: Error: unknown option `--no-encode' ↓

cause 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

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

cause 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

Warnings

breaking protobufjs-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.

breaking protobufjs-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.

deprecated pbts 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.

gotcha Using 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).

gotcha pbts generation only works with 'static-module' target (default). ↓

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

Install

npm install protobufjs-loader

yarn add protobufjs-loader

pnpm add protobufjs-loader

Imports

Root (from .proto)

wrong

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

correct

import Root from './my.proto';

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

protobufjs-loader module rule

wrong

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

correct

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

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

require/proto with callback
wrong
```
const root = require('./lib/compiled.json');
```
correct
```
const Root = require('./my.proto');
```
Loader returns a synchronous Root object; no async callbacks needed.

Quickstart

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);