rsbuild-plugin-protobufjs

English | 中文

An Rsbuild plugin that integrates protobufjs. It compiles .proto files into JavaScript modules that run in browsers or Node.js, and can optionally generate TypeScript declaration files (.d.ts).

• What it does: Automatically matches and transforms .proto files
• Built-in cache: Uses Rsbuild cachePath and writes intermediates under protobufjs
• Configurable target: Passes --target to protobufjs-cli (default static-module)
• Type output: Generates .d.ts by default for better TS DX

Installation

pnpm add -D rsbuild-plugin-protobufjs
# or
npm i -D rsbuild-plugin-protobufjs
# or
yarn add -D rsbuild-plugin-protobufjs

• peerDependencies: protobufjs@^8.4.2 (install it in your project)
• dependencies: The plugin uses protobufjs-cli internally to run pbjs/pbts

Quick Start

Add the plugin in your Rsbuild configuration:

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import { protobufjsPlugin } from 'rsbuild-plugin-protobufjs';

export default defineConfig({
  plugins: [
    protobufjsPlugin({
      // optional, see "Options" below
    }),
  ],
});

Now import .proto files directly in your source code:

import client from './client.proto';

// With target=static-module (default), the imported object exposes static encode/decode APIs
console.log(client);

During build or dev, the plugin will:

• Use pbjs to compile .proto into a JS module, emitted into Rsbuild's cache directory under protobufjs.
• If dts is enabled (default true), run pbts to emit client.proto.d.ts next to the source .proto file.

Options

The plugin exports protobufjsPlugin(options?: Options).

interface Options {
  /**
   * Files to include. Same as Rspack RuleSetCondition.
   * @default /\.proto$/
   */
  test?: import('@rsbuild/core').Rspack.RuleSetCondition;

  /**
   * Value passed to protobufjs-cli `--target`.
   * Common values: 'static-module' (default), 'json-module', 'proto2', etc.
   * @default 'static-module'
   */
  target?: string;

  /**
   * Value passed to protobufjs-cli `--wrap` for module targets.
   * Defaults to 'esm' for ESM output environments and 'commonjs' otherwise.
   */
  wrap?: 'default' | 'commonjs' | 'amd' | 'esm' | 'closure' | string;

  /**
   * Whether to generate `.d.ts` for each `.proto`.
   * @default true
   */
  dts?: boolean;
}

• test: Which files to transform. Defaults to all .proto files.
• target: Forwarded directly to pbjs --target. static-module is recommended for most applications.
• wrap: Forwarded to pbjs --wrap for module targets. By default, the plugin uses esm when the current Rsbuild environment outputs ES modules and commonjs otherwise. Set this explicitly if you need default, amd, closure, or a custom wrapper path.
• dts: Whether to call pbts to emit a sibling .d.ts file next to the source.

Example

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import { protobufjsPlugin } from 'rsbuild-plugin-protobufjs';

export default defineConfig({
  plugins: [
    protobufjsPlugin({
      test: /\.proto$/,           // only process .proto files
      target: 'static-module',     // generate static module
      wrap: 'esm',                 // override wrapper; otherwise inferred per output environment
      dts: true,                   // generate type declarations
    }),
  ],
});

Project code:

// src/index.ts
import client from './client.proto';

// Use encode/decode APIs as needed
// Actual exports depend on the chosen target = static-module
console.log(client);

The declaration file will be emitted next to the source, e.g., src/client.proto.d.ts.

FAQ

• Q: Do I need both protobufjs and protobufjs-cli installed?

  • A: Yes. protobufjs is a peer dependency you install in your project; the plugin depends on protobufjs-cli for compilation.

• Q: Where are intermediate outputs written?

  • A: Under Rsbuild's cache directory, e.g., node_modules/.cache/rsbuild/<hash>/protobufjs/. This is an implementation detail; the final code is returned to Rsbuild's pipeline.

• Q: Can I emit JS without .d.ts?

  • A: Yes. Set dts: false.

• Q: How do I change pbjs output style?

  • A: Use target to pass a value supported by pbjs --target, such as json-module. Different targets produce different module shapes; see protobufjs-cli documentation.