npm NuGet v1.0.0 MIT

@metaengine/protobuf-react

Protobuf 3 → React hooks and message types with optional TanStack Query (useQuery, useMutation), gRPC/Connect transport over native Fetch, and gRPC-native error handling. React 18+.

Protobuf 3.xMetaEngine IRTypeScript · React
Install

Pick your registry

The same generator, published to every ecosystem we support. Install however your project expects.

npmPrimary@metaengine/protobuf-react
$npm install @metaengine/protobuf-react
v1.0.0
NuGetMetaEngine.TypeScript.Protobuf.React
$dotnet add package MetaEngine.TypeScript.Protobuf.React
v1.0.0
Usage

Drive it from the CLI or programmatically

npm ships a zero-config CLI. NuGet ships the same generator as a C# fluent API — same options, same output.

npm · npx · CI-friendly

After install, point the CLI at your OpenAPI spec. It writes the generated tree to your chosen output directory.

Basic syntax
terminal
npx @metaengine/protobuf-react <input> <output> [options]

Generates React hooks and message types from Protobuf 3 .proto files, with gRPC/Connect transport over native Fetch.

Quick examples
Generate from a .proto file
npx @metaengine/protobuf-react service.proto ./src/api
With TanStack Query
npx @metaengine/protobuf-react service.proto ./src/api \
  --tanstack-query \
  --documentation
Production setup with auth and middleware
npx @metaengine/protobuf-react service.proto ./src/api \
  --tanstack-query \
  --middleware \
  --bearer-auth API_TOKEN \
  --timeout 30 \
  --error-handling
CLI options
Option
Description
--base-url-env <name>
Environment variable name for base URL [default: REACT_APP_API_BASE_URL]. Use VITE_ prefix for Vite, NEXT_PUBLIC_ for Next.js.
--service-suffix <suffix>
Service naming suffix [default: Api]
--options-threshold <n>
Parameter count to use options object [default: 4]
--documentation
Generate JSDoc comments
--tanstack-query
Enable TanStack Query integration (useQuery / useMutation)
--middleware
Emit fetch middleware infrastructure (Middleware type + chainMiddleware + createFetchWithMiddleware)
--error-handling
Enable gRPC-native error handling keyed on gRPC status codes
--bearer-auth <env-var-name>
Bearer token from env var (adds Authorization header to all requests)
--basic-auth <userEnv:passEnv>
Basic auth from env vars. Format: <username-env>:<password-env> (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 (e.g. X-Tenant-ID=TENANT_ID)
--date-transformation
Convert google.protobuf.Timestamp fields in responses to JavaScript Date objects
--types-barrel
Emit an index.ts barrel per folder plus a root index.ts re-exporting everything
--type-mapping <mapping>
Override TS type for a protobuf type. Repeatable. Targets: string · number · Date · boolean (e.g. google.protobuf.Timestamp=string)
--clean
Clean output directory (remove files not in generation)
--verbose
Enable verbose logging
--help, -h
Show help message
Options reference

Every knob, documented

Every option is available on the C# fluent API as a method, and most are also exposed as CLI flags. Cross-cutting auth, headers, retries and timeouts apply across frameworks.

React Options

4
  • WithBaseUrlEnvVar(string)Environment variable name for base URL (default: "REACT_APP_API_BASE_URL"). Use VITE_ prefix for Vite, NEXT_PUBLIC_ for Next.js.
  • WithTanStackQuery()Generate TanStack Query hooks (useQuery / useMutation). Requires @tanstack/react-query.
  • WithMiddleware()Emit fetch middleware infrastructure (Middleware type + chainMiddleware + createFetchWithMiddleware)
  • WithResponseDateTransformation()Convert google.protobuf.Timestamp fields in responses to Date objects

Auth · Headers · Resilience

9
  • WithErrorHandling()Enable gRPC-native error handling keyed on gRPC status codes (NOT_FOUND / PERMISSION_DENIED → null · INVALID_ARGUMENT / FAILED_PRECONDITION → error body · UNAUTHENTICATED / INTERNAL / UNAVAILABLE → throw)
  • WithErrorHandling(grpc => grpc...)Tune the gRPC taxonomy: ReturnNullForCodes(...) · ReturnErrorForCodes(...) · ThrowForCodes(...) · MapGrpcCode(code, behavior). Overrides merge on top of the defaults
  • WithBearerAuth()Bearer token from env var (default API_TOKEN) — adds Authorization header
  • WithBearerAuth(string)Bearer token from a specific env var name
  • WithBearerAuth(string, string)Bearer token with custom header name
  • WithBasicAuth(string, string)HTTP Basic auth from username + password env vars
  • WithCustomHeader(string, string)Static header from env var. Repeatable (e.g. X-Tenant-ID ← TENANT_ID)
  • WithTimeout(double)Request timeout in seconds, emitted as a grpc-timeout header on every call
  • WithTimeout(double?, double?, double?, double?)Granular timeout: connect · read · write · pool

Protobuf Options

5
  • WithDocumentation()Generate JSDoc comments from .proto field and service descriptions
  • WithTypeFilter(Func)Filter extracted proto types before registration — only types returning true are generated
  • WithTypeMapping(string, Type)Override the TS mapping for a protobuf well-known type by fully-qualified name (e.g. google.protobuf.Timestamp → string)
  • WithMethodNames(Func)Custom method naming rule
  • WithOptionsObjectThreshold(int)Parameter count for options object (default: 4)

TypeScript Output

1
  • WithTypesBarrel()Emit an index.ts barrel per folder plus a root index.ts re-exporting everything

Naming Transformations

3
  • Types(Func)Transform type names
  • Paths(Func)Transform output paths
  • FileNames(Func)Transform file names

File Management

5
  • CleanDestination()Clean output directory before generation
  • AlwaysOverwrite()Always overwrite existing files
  • OnlyWhenModelChanged()Update only when model changes
  • OnlyWhenNew()Write only new files, preserve existing
  • CleanDirectories(...)Clean specific subdirectories

Diagnostics

1
  • EnableVerboseLogging()Enable detailed logging
Features

Why this package is different

Deterministic output
Same spec + same options produce byte-identical files. Safe to commit, safe to diff in review, safe to cache in CI.
Tree-shakeable
One file per tag (or per operation) means bundlers drop unused code at build time. No runtime dispatch table.
Zero runtime
Validation and clients opt in. The default emit is pure types with no dependency surface beyond your HTTP lib.
Flexible naming
Case conventions configurable per role — types, properties, operations, enums. Idiomatic in the target by default.
Type resolution
Discriminated unions for oneOf, proper nullability, bigint when the spec mandates it, refs flattened only when safe.
Semver-honest
Spec diff drives the version bump. Additive changes = minor, removed ops = major. Never a surprise in your lockfile.