rorpc
Rust oRPC — annotation-driven Axum handlers with automatic TypeScript contract generation.
Overview
rorpc bridges Rust Axum handlers with TypeScript clients through compile-time metadata collection and automatic code generation. Annotate handlers with method-specific macros (#[rorpc::get], #[rorpc::post], etc.), derive Zod schemas, and generate type-safe TypeScript contracts with zero runtime overhead.
Features
- Zero boilerplate routing — Auto-discover handlers with
router!() - Type-safe contracts — Generate TypeScript Zod schemas from Rust types
- Compile-time registration — Uses
inventorycrate for link-time collection - Streaming support — SSE endpoints with
Sse<impl Stream> - Error schemas — TypeScript error enums from Rust error types
- Module filtering — Include/exclude handlers by module path
Quick Start
use ;
use ;
use ;
async
async
async
Configure the output path in Cargo.toml:
[]
= "../client/src/rpc/index.ts"
Macros
#[contract] — Automatic Contract Generation (New!)
Replaces manual generate_contract().output() boilerplate. Automatically generates TypeScript contracts in debug builds before main() runs.
Configure the output path in Cargo.toml:
[]
= "../client/src/rpc/bindings.ts"
async
Options:
#[contract]— reads[package.metadata.rorpc] client_pathfromCargo.toml#[contract("../client/bindings.ts")]— string literal#[contract(CLIENT_PATH)]— constant#[contract(concat!(...))]— expression
See docs/metadata-bridge.md for more options.
Method-Specific Shorthands (Recommended)
// GET request
async
async
async
async
async
Available methods: get, post, put, patch, delete
#[rorpc::route] — Explicit Method + Path
For non-standard methods or when you prefer explicit syntax:
async
Required attributes: method, path
Optional attributes: data (SSE handlers)
router!
Auto-discover all annotated handlers and build an Axum Router.
let app = router!; // all handlers, no state
let app = router!; // with state
let app = router!; // module filter
let app = router!; // wildcard
let app = router!; // brace expansion
let app = router!; // filter + state
#[derive(ZodTs)]
Generate TypeScript Zod schemas from Rust types.
#[derive(OrpcError)]
Generate TypeScript error schemas from Rust error enums.
Contract Generation
generate_contract
.output
.unwrap;
Generated TypeScript:
// AUTO-GENERATED by rorpc — do not edit manually.
import { z } from "zod";
import { oc } from "@orpc/contract";
import { openapi } from "@orpc/openapi";
export const PlanetSchema = z.object({
id: z.number().int(),
name: z.string().min(1).max(100),
description: z.string().optional(),
});
export type Planet = z.infer<typeof PlanetSchema>;
export const contract = {
planet: {
listPlanets: oc
.meta(openapi({ method: "GET", path: "/planet/list" }))
.output(z.array(PlanetSchema)),
findPlanet: oc
.meta(openapi({ method: "GET", path: "/planet/{id}" }))
.input(z.object({ id: z.number().int() }).extend(FindQuerySchema.shape))
.output(PlanetSchema)
.errors({ NOT_FOUND: {}, UNAUTHORIZED: {} }),
},
} as const;
export type Contract = typeof contract;
Architecture
rorpc (runtime + facade)
├── rorpc-macros (proc-macro bridge)
│ └── rorpc-parse (parsing + codegen)
│ └── Shared utilities used by both compile-time and runtime
└── dependencies:
├── inventory (compile-time registration)
├── axum (web framework)
└── serde (serialization)
Shared parsing utilities: The rorpc runtime crate reuses type-to-Zod conversion logic from rorpc-parse, ensuring consistency between compile-time macro expansion and runtime contract generation.
Module Structure
metadata—HandlerMetadatacollected by#[rorpc]for contract generationregistration—HandlerRegistrationwith type-erased route factories forrouter!()schema_registry—SchemaRegistrationfor Zod schemas from#[derive(ZodTs)]error_registry—ErrorRegistrationfor error enums from#[derive(OrpcErrors)]codegen— TypeScript contract generation (ContractBuilder)
Installation
[]
= "0.1"
= "0.8"
= { = "1.0", = ["derive"] }
= { = "1", = ["full"] }
Examples
See examples/ directory:
examples/axum-react/server— Basic exampleexamples/axum-react/better-auth-integration— Auth integration with Better Auth
License
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.