Registry / devops / protoc-gen-pothos

protoc-gen-pothos

library0.8.0jsnpmunverified

protoc-gen-pothos (v0.8.0) is a protoc plugin that generates Pothos GraphQL DSL code from Protocol Buffers IDL files. It integrates with ts-proto for TypeScript type definitions and requires Buf or protoc for code generation. Released roughly monthly, it supports custom scalar mappings, optional emission of imported file types, and configuration via Buf plugins. Unlike manual GraphQL schema building, it auto-generates Pothos builder calls corresponding to protobuf messages, enums, services, and fields, reducing boilerplate. Requires Pothos GraphQL and ts-proto as peer dependencies, and is designed for TypeScript server applications using GraphQL and gRPC.

devops

npm install protoc-gen-pothos

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PROTOC-GEN-POTHOS

protoc-gen-pothos

devopsjavascriptv0.8.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

default

✓ import builder from '../../builder'

✗ import { builder } from '../../builder'

The generated code expects a default export of the Pothos SchemaBuilder from the file specified by pothos_builder_path.

Generated types (e.g., User, UserSchema)

✓ import { User, UserSchema } from '../proto/example'

✗ import * as proto from '../proto/example'

Generated types are named exports from the ts-proto output files. Use destructured imports.

Pothos generated schemas (e.g., User, UserResolver)

✓ import { User, UserResolver } from '../pothos/example'

✗ const User = require('../pothos/example').User

Generated Pothos schemas are ESM named exports. CommonJS require() may cause issues in TypeScript ESM projects.

Builder type for pothos_builder_path

✓ import type { SchemaBuilder } from '../../builder'

TypeScript projects often need to import the builder type for type annotations.

Shows full setup: install deps, configure Buf, create builder, generate code, and import generated Pothos objects.

// 1. Install dependencies // npm install --save-dev protoc-gen-pothos ts-proto // npm install @pothos/core // 2. Configure Buf (proto/buf.gen.yaml) // version: v1 // plugins: // - name: ts // out: ../src/__generated__/proto // strategy: all // path: ../node_modules/.bin/protoc-gen-ts_proto // opt: // - esModuleInterop=true // - unrecognizedEnum=false // - outputTypeRegistry=true // - name: pothos // path: ../node_modules/.bin/protoc-gen-pothos // out: ../src/__generated__/pothos // opt: // - pothos_builder_path=../../builder // - import_prefix=../proto // 3. Create builder file (src/builder.ts) import SchemaBuilder from '@pothos/core'; export default new SchemaBuilder({}); // 4. Run code generation // npx buf generate // 5. Use generated schemas in your resolver or schema stitching import { User, UserSchema } from './__generated__/pothos/example'; // The generated files export Pothos objects like: // export const User = builder.objectRef<UserType>('User'); // export const UserSchema = builder.objectType(User, { ... });

Debug

Known issues

gotchaPothos builder path must be relative to the output directory, not the project root.

fix

Ensure pothos_builder_path is relative to the 'out' directory in buf.gen.yaml, e.g., if out=../src/__generated__/pothos, set pothos_builder_path=../../builder to point to src/builder.ts.

affects: >=0.0.0

gotchaimport_prefix is required and must point to the ts-proto output directory relative to the pothos output directory.

fix

Set import_prefix to a path that resolves from the pothos output directory to the proto types output directory, e.g., if ts-proto out=../proto and pothos out=../pothos, then import_prefix=../proto.

affects: >=0.0.0

gotchats-proto options 'esModuleInterop=true', 'unrecognizedEnum=false', and 'outputTypeRegistry=true' are required for protoc-gen-pothos to work.

fix

Add these options to your ts-proto plugin config in buf.gen.yaml.

affects: >=0.0.0

breakingIn version 0.6.0, the output format changed: previously exported named objects directly, now exports builder calls which may require different import patterns.

fix

Update imports to match the new pattern: use named exports of type refs and schemas (e.g., User, UserSchema). Check release notes for migration guide.

affects: >=0.6.0 <0.7.0

deprecatedThe option 'emit_imported_files' may be removed in a future version.

fix

Consider manually importing types from imported proto files or waiting for alternative support.

affects: >=0.7.0

gotchaGenerated code expects the builder to be a default export, but TypeScript may not enforce this and cause runtime errors.

fix

Export the builder as default: export default new SchemaBuilder({});

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module '../../builder' or its corresponding type declarations.

pothos_builder_path is incorrect relative to the generated output file.

fix

Verify the relative path from the output directory to your builder file. Example: if output is src/__generated__/pothos and builder is src/builder.ts, then pothos_builder_path should be ../../builder.

Expected outputTypeRegistry to be true for ts-proto.

ts-proto option 'outputTypeRegistry=true' is missing.

fix

Add '- outputTypeRegistry=true' to your ts-proto plugin options in buf.gen.yaml.

TypeError: builder.objectRef is not a function

The builder file does not export a SchemaBuilder instance as default.

fix

Ensure the builder file exports default new SchemaBuilder({}); and that @pothos/core is installed.

Option 'import_prefix' is required but not provided.

Missing import_prefix configuration in buf.gen.yaml for the pothos plugin.

fix

Add '- import_prefix=../proto' (adjust path) to the pothos plugin options.

Upgrade

Version history

0.8.0latest on npm

Audit

Dependencies

@pothos/corerequiredRuntime dependency for generated Pothos builder code to work.

ts-protorequiredRequired for TypeScript type definitions from protobuf; protoc-gen-pothos expects ts-proto output.

Agent activity

8 hits · last 30 days

node

Resources

githubssh://git@github.com/proto-graphql/proto-graphql-js ↗

packageprotoc-gen-pothos ↗

homepagehttps://github.com/proto-graphql/proto-graphql-js#readme ↗