@metaengine/protobuf-fetch

Generate TypeScript services and models from Protobuf definitions using the native Fetch API.

gRPC/Connect transport — framework-agnostic, runs on Node, browsers, Vite, SvelteKit, Next.js, and any TS runtime that ships fetch.

Install

npm install --save-dev @metaengine/protobuf-fetch

Or use directly with npx:

npx @metaengine/protobuf-fetch <input> <output>

Requirements

• Node.js 18.0 or later
• .NET 8.0 or later runtime (Download)

Quick start

npx @metaengine/protobuf-fetch service.proto ./src/api \
  --documentation \
  --result-pattern

Production setup

npx @metaengine/protobuf-fetch service.proto ./src/api \
  --bearer-auth API_TOKEN \
  --timeout 30 \
  --custom-header X-Tenant-ID=TENANT_ID \
  --error-handling

CLI options

| Option | Description | Default | |--------|-------------|---------| | --base-url-env <name> | Environment variable name for base URL (e.g. VITE_API_URL, NEXT_PUBLIC_API_URL) | API_BASE_URL | | --service-suffix <suffix> | Service naming suffix | Service | | --options-threshold <n> | Parameter count for options object | 4 | | --documentation | Generate JSDoc comments | false | | --import-meta-env | Use import.meta.env for env access (Vite, SvelteKit) | false | | --result-pattern | Return ApiResult<T> instead of T for structured error handling | false | | --middleware | Emit middleware hooks (onRequest, onResponse, onError) in client | false | | --error-handling | gRPC-native error handling keyed on gRPC status codes | false | | --bearer-auth <env-var-name> | Bearer token authentication (runtime token provider, adds Authorization: Bearer <token>) | - | | --basic-auth <userEnv:passEnv> | Basic auth from env vars (e.g. API_USER:API_PASS) | - | | --timeout <seconds> | Request timeout in seconds for all operations | - | | --custom-header <header=envVarName> | Static header from env var. Repeatable. | - | | --date-transformation | Convert google.protobuf.Timestamp fields in responses to Date objects | false | | --types-barrel | Emit an index.ts barrel per folder plus a root index.ts re-exporting everything | false | | --clean | Clean output directory (remove files not in generation) | false | | --verbose | Enable verbose logging | false | | --type-mapping <name=target> | Override TS type for a protobuf type. Repeatable. See Type mapping overrides | - | | --help, -h | Show help message | - |

Type mapping overrides

Use --type-mapping to override the TS type emitted for a protobuf type, keyed by its fully-qualified name. Repeatable. Unsupported targets are hard errors.

| Target | Emitted TS type | |--------|-----------------| | string | string | | number | number | | Date | Date | | boolean | boolean |

npx @metaengine/protobuf-fetch service.proto ./src/api \
  --type-mapping google.protobuf.Timestamp=string \
  --type-mapping google.protobuf.Duration=string

Integer scalars (including int64/uint64) map to number by design so request bodies survive JSON.stringify and parsed responses match the wire shape.

See it live

Try the generator with your own spec at https://www.metaengine.eu/converters.

License

MIT

Support

For issues and feature requests, please visit: https://github.com/meta-engine/protobuf-fetch/issues