Plugin options

@bufbuild/protoc-gen-es supports a small set of options to control the generated output. To find the right options for Vite, Next.js, Node.js, Deno, or Bun, see Configure for your environment.

With the Buf CLI, specify multiple options as a YAML list:

version: v2
plugins:
  - local: protoc-gen-es
    out: src/gen
    opt:
      - target=ts
      - import_extension=js

With protoc, you can repeat --es_opt, or pass a single comma-separated value such as target=ts,import_extension=js.

target

This option controls which files the plugin generates:

• target=js: Generate _pb.js files.
• target=ts: Generate _pb.ts files.
• target=dts: Generate _pb.d.ts files.

You can combine targets with +. For example, target=js+dts generates JavaScript and declaration files.

By default, the plugin generates JavaScript and TypeScript declaration files. If you prefer fully generated TypeScript source, use target=ts.

import_extension

By default, generated import paths do not include a file extension. Bundlers don’t need one, but ECMAScript modules in Node.js typically require .js, and Deno typically requires .ts.

Use this option when your environment requires file extensions in imports:

• import_extension=none: No extension. This is the default.
• import_extension=js: Add .js.
• import_extension=ts: Add .ts.

map_imports

By default, generated code imports dependencies from the local output with a relative path. For example, the file generated for foo/bar.proto imports a message from buf/validate/validate.proto from ../buf/validate/validate_pb.

If a dependency is provided by a package instead, use map_imports to import it from there. For example, @bufbuild/protovalidate exports the code generated for buf/validate/validate.proto, so there is no need to generate it again:

version: v2
plugins:
  - local: protoc-gen-es
    out: src/gen
    opt:
      - map_imports=buf/validate/:@bufbuild/protovalidate/gen

With this option, buf/validate/validate.proto is imported from @bufbuild/protovalidate/gen/buf/validate/validate_pb.js.

The option takes the form map_imports=<pattern>:<target> and can be repeated. The pattern is matched against the path of the Protobuf file, and the first matching pattern wins. The target is prepended to the path of the generated file. Patterns support a subset of glob:

• * matches zero or more characters except /.
• ** matches zero or more characters, including /.
• **/ matches zero or more directories.
• A trailing / matches every file in the directory and its subdirectories.

Package imports always end in _pb.js. Well-known types are always imported from @bufbuild/protobuf/wkt.

js_import_style

By default, Protobuf-ES generates ECMAScript import and export statements.

• js_import_style=module: Generate ESM. This is the default.
• js_import_style=legacy_commonjs: Generate CommonJS require() calls.

If you are starting a new project, keep the default.

keep_empty_files=true

By default, the plugin omits empty output files. Set keep_empty_files=true to keep them.

This is mainly useful for Bazel and other tooling that requires every declared output file to exist.

ts_nocheck=true

Generated TypeScript works with current TypeScript versions under standard settings.

If your project uses compiler settings that still complain about generated files, set ts_nocheck=true to add // @ts-nocheck at the top of every generated file.

elide_plugin_version=true

By default, generated files include the plugin version in the preamble.

Set elide_plugin_version=true to remove it. We usually recommend keeping the version because mismatches between the generator and runtime are easier to spot that way.

json_types=true

Generate JSON types for every Protobuf message and enumeration.

When this option is enabled, toJson() returns those JSON types automatically when available. See JSON types.

valid_types (experimental)

Generate a Valid type for every message.

• valid_types=legacy_required: Treat proto2 required message fields and Edition LEGACY_REQUIRED message fields as non-optional in the generated Valid type.
• valid_types=protovalidate_required: Treat message fields with Protovalidate’s required rule as non-optional in the generated Valid type.

You can combine both with +, for example valid_types=legacy_required+protovalidate_required.

See Valid types for details.

erasable_syntax=true (experimental)

Generates Protobuf enums as an object with as const instead of a TypeScript enum. See Enums vs Objects for details.

Use this option to:

• Run TypeScript natively in Node.js. Combine it with target=ts and import_extension=ts.
• Compile with the tsconfig option erasableSyntaxOnly.