{"id":20481,"library":"protobufjs-loader","title":"protobufjs-loader","description":"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.","status":"active","version":"3.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/kmontag/protobufjs-loader","tags":["javascript","webpack","protobuf","protobufjs","ProtoBuf.js"],"install":[{"cmd":"npm install protobufjs-loader","lang":"bash","label":"npm"},{"cmd":"yarn add protobufjs-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add protobufjs-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency","package":"webpack","optional":true}],"imports":[{"note":"Loader returns a protobuf.js Root object directly; no need to compile separately.","wrong":"const protobuf = require('protobufjs/light'); const json = require('json!./my.proto'); const Root = protobuf.Root.fromJSON(json);","symbol":"Root (from .proto)","correct":"import Root from './my.proto';"},{"note":"Loader name is 'protobufjs-loader', not 'protobufjs'.","wrong":"module: { rules: [ { test: /\\.proto$/, loader: 'protobufjs' } ] }","symbol":"protobufjs-loader module rule","correct":"module: { rules: [ { test: /\\.proto$/, use: 'protobufjs-loader' } ] }"},{"note":"Loader returns a synchronous Root object; no async callbacks needed.","wrong":"const root = require('./lib/compiled.json');","symbol":"require/proto with callback","correct":"const Root = require('./my.proto');"}],"quickstart":{"code":"// webpack.config.js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.proto$/,\n        use: {\n          loader: 'protobufjs-loader',\n          options: {\n            target: 'static-module',\n            pbts: true\n          }\n        }\n      }\n    ]\n  }\n};\n\n// myModule.js\nimport Root from './my.proto';\n// Root is a protobuf.js Root instance, ready to use\nconst MyMessage = Root.lookupType('MyMessage');\nconst message = MyMessage.create({ field1: 'value' });\nconst buffer = MyMessage.encode(message).finish();\nconsole.log('Encoded message:', buffer);","lang":"javascript","description":"Configure webpack to load .proto files via protobufjs-loader, then import them as Root objects in your code."},"warnings":[{"fix":"Upgrade to webpack ^5.0.0, or stay on v2.x if you need webpack 4.","message":"protobufjs-loader v3 drops webpack 4 support; only webpack 5 is supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade Node to >=12.0.0 and ensure compatibility with protobufjs v7.","message":"protobufjs-loader v2 drops Node.js <12.0.0 and updates protobufjs to ^7.0.0.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"If using pbts output option, the function now receives (protobufFile) and returns a path or promise. See docs.","message":"pbts output function signature changed in v3.1.0.","severity":"deprecated","affected_versions":"<3.1.0"},{"fix":"Ensure the loader is applied to .proto files, and that protobufjs is installed (as a direct dependency, not just dev).","message":"Using require() with .proto files requires webpack and protobufjs-loader configured.","severity":"gotcha","affected_versions":"all"},{"fix":"Set target to 'static-module' or omit the option to use default.","message":"pbts generation only works with 'static-module' target (default).","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run: npm install protobufjs","cause":"protobufjs is not installed as a dependency.","error":"Module not found: Error: Can't resolve 'protobufjs' in ..."},{"fix":"Add protobufjs-loader rule to webpack.config.js: { test: /\\.proto$/, use: 'protobufjs-loader' }","cause":"Webpack is not configured to use protobufjs-loader for .proto files.","error":"Module parse failed: Unexpected token (1:0)\nYou may need an appropriate loader to handle this file type."},{"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","cause":"Passed an invalid pbjs argument.","error":"Error: pbjs failed: Error: unknown option `--no-encode'"},{"fix":"Ensure pbts.output is a function returning a string, e.g., (file) => `${file}.d.ts`","cause":"pbts output function is not a function or invalid.","error":"TypeError: Cannot read properties of undefined (reading 'protobufFile')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}