MetaEngine Protobuf React

Generate React TypeScript hooks and models from Protobuf definitions.

gRPC/Connect transport over the native Fetch API, with optional TanStack Query (useQuery/useMutation) hooks and gRPC-native error handling — generated straight from your .proto sources.

Installation

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

Or use directly with npx:

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

Requirements

• Node.js 18.0 or later
• .NET 8.0 or later runtime (Download)
• React 18+ (and @tanstack/react-query if you use --tanstack-query)

Quick Start

Basic

npx @metaengine/protobuf-react service.proto ./src/api \
  --documentation \
  --tanstack-query

Production setup

npx @metaengine/protobuf-react service.proto ./src/api \
  --tanstack-query \
  --bearer-auth API_TOKEN \
  --timeout 30 \
  --error-handling

With npm scripts

{
  "scripts": {
    "generate:api": "metaengine-protobuf-react service.proto ./src/api --tanstack-query --error-handling"
  }
}

CLI Options

| Option | Description | Default | |--------|-------------|---------| | --base-url-env <name> | Environment variable name for base URL | REACT_APP_API_BASE_URL | | --service-suffix <suffix> | Service naming suffix | Api | | --options-threshold <n> | Parameter count for options object | 4 | | --documentation | Generate JSDoc comments | false | | --tanstack-query | Generate TanStack Query hooks (useQuery/useMutation) | false | | --middleware | Emit fetch middleware infrastructure (Middleware + chainMiddleware + createFetchWithMiddleware) | false | | --error-handling | gRPC-native error handling keyed on gRPC status codes | false | | --bearer-auth <env-var-name> | Bearer token from env var; adds Authorization: Bearer to all requests | - | | --basic-auth <userEnv:passEnv> | Basic auth from two env vars | - | | --timeout <seconds> | Per-request timeout via AbortSignal.timeout | - | | --custom-header <header=envVarName> | Static header from env var. Repeatable. | - | | --date-transformation | Convert google.protobuf.Timestamp response fields to Date objects | false | | --types-barrel | Emit an index.ts barrel per folder plus a root index.ts | false | | --clean | Clean output directory (remove files not in generation) | false | | --verbose | Enable verbose logging | false | | --type-mapping <name=target> | Override the TS type for a protobuf type. Repeatable. | - | | --help, -h | Show help message | - |

Generated Code Structure

output/
  ├── types/                        # One file per message/enum
  │   ├── entity.ts                 # export interface Entity { ... }
  │   ├── create-entity-request.ts
  │   └── ...
  ├── api/                          # One file per proto service
  │   ├── entity.api.ts             # EntityApi functions (+ hooks with --tanstack-query)
  │   └── ...
  ├── client.ts                     # ClientConfig, createClient, auth/headers/timeout
  └── errors.ts                     # error helpers

• With --error-handling, two extra types are emitted: types/grpc-status-code.ts and types/grpc-error.ts.

Features

TanStack Query hooks

npx @metaengine/protobuf-react service.proto ./src/api --tanstack-query

Generates useQuery/useMutation hooks alongside the plain API functions. Requires @tanstack/react-query in your project.

Bearer authentication

npx @metaengine/protobuf-react service.proto ./src/api --bearer-auth API_TOKEN

The client reads the token from process.env.API_TOKEN (or an explicit config value / async provider) and adds Authorization: Bearer <token> to every request.

Basic authentication

npx @metaengine/protobuf-react service.proto ./src/api --basic-auth API_USER:API_PASS

Reads the username and password from the two named env vars and sends Authorization: Basic <base64(user:password)>.

Timeout

npx @metaengine/protobuf-react service.proto ./src/api --timeout 30

Uses AbortSignal.timeout(seconds * 1000) and composes with consumer-supplied AbortSignal.

Custom headers from env vars

npx @metaengine/protobuf-react service.proto ./src/api \
  --custom-header X-Tenant-ID=TENANT_ID \
  --custom-header X-App-Id=APP_ID

Repeatable. Each header value is read from a separate env var.

gRPC-native error handling

npx @metaengine/protobuf-react service.proto ./src/api --error-handling

Emits a GrpcError type and a GrpcStatusCode taxonomy. Errors are classified by gRPC status code rather than HTTP status: NOT_FOUND / PERMISSION_DENIED return null; INVALID_ARGUMENT / ALREADY_EXISTS / FAILED_PRECONDITION return the error body; UNAUTHENTICATED / INTERNAL / UNAVAILABLE throw.

Middleware

npx @metaengine/protobuf-react service.proto ./src/api --middleware

Emits fetch middleware infrastructure (Middleware type + chainMiddleware + createFetchWithMiddleware) to compose cross-cutting behavior around requests.

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-react 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. A bigint target is therefore not offered.

Programmatic Usage

The NuGet package allows programmatic use in .NET projects. See the website documentation for the full C# API reference.

Support

• Issues: GitHub Issues
• Email: [email protected]
• Website: metaengine.eu

License

MIT License - see LICENSE file for details.