Your TypeScript is the contract. rivet-ts reads a type-only TypeScript contract with the TypeScript compiler and turns it into Rivet's contract JSON. The Rivet binary then emits an OpenAPI 3.1 spec from it, and the OpenAPI ecosystem does the rest: openapi-typescript types an openapi-fetch client, and the Hono runtime serves handlers typed against the same contract.

The contract is types and nothing else. There are no decorators and no router object; the contract module has nothing to run. Rivet does the same for a .NET server; rivet-ts is that pipeline when your server is TypeScript. Either way the Rivet binary writes the OpenAPI, so you can rewrite the contract in C# later, move the backend to .NET, and keep the client's call sites as they are.

Prerequisites

• Node.js 20.19+ or 22.12+. Scaffolded workspaces use Nuxt, which needs Node.js 22.19+ or 24.11+.
• pnpm 10 or later, and go-task for scaffolded workspaces.
• Network access the first time Rivet runs. The binary is downloaded from GitHub Releases, checked against its published digest, then cached. It never needs to be on PATH.

Install

pnpm add openapi-fetch
pnpm add -D @maxanstey-meridian/rivet-ts typescript

pnpm may warn that openapi-typescript wants typescript@^5. It runs on the TypeScript 6 rivet-ts brings, so the warning is harmless.

Three steps in

1. Write the contract

import type { Contract, Endpoint } from "@maxanstey-meridian/rivet-ts";

export interface MemberDto {
  id: string;
  email: string;
  role: "admin" | "member";
}

export interface CreateMemberRequest {
  email: string;
}

export interface MembersContract extends Contract<"MembersContract"> {
  List: Endpoint<{
    method: "GET";
    route: "/api/members";
    response: MemberDto[];
  }>;

  Create: Endpoint<{
    method: "POST";
    route: "/api/members";
    input: CreateMemberRequest;
    response: MemberDto;
    successStatus: 201;
  }>;
}

Routes, inputs, outputs, statuses, errors, examples and security sit in one place, as types. Brand<string, "Email"> and Format<string, "uuid"> carry meaning the wire type can't.

2. Generate the spec

pnpm exec rivet-ts --entry src/contracts.ts --out generated/api.contract.json
pnpm exec rivet-ts rivet -- --from generated/api.contract.json --output ./generated
pnpm exec rivet-ts generate --generated-root ./generated

Each artifact has one owner. rivet-ts writes api.contract.json, Rivet writes openapi.json, and rivet-ts generate writes schema.d.ts. rivet-ts pins Rivet 0.45.1; set RIVET_VERSION to use another.

3. Consume it typed

import createClient from "openapi-fetch";
import type { paths } from "./generated/schema";

const api = createClient<paths>({ baseUrl: "https://api.example.com" });

// Path, body and per-status responses all inferred.
const { data, error } = await api.POST("/api/members", {
  body: { email: "[email protected]" },
});

Serve it

The server loads rivet-ts at runtime, so add it as a production dependency along with hono (-P moves it out of devDependencies):

pnpm add -P hono @maxanstey-meridian/rivet-ts

Then register handlers against the contract JSON:

import { Hono } from "hono";
import { registerRivetHonoRoutes } from "@maxanstey-meridian/rivet-ts/hono";
import contract from "../generated/api.contract.json" with { type: "json" };
import type { MembersContract } from "./contracts.js";

export const app = new Hono();

registerRivetHonoRoutes<MembersContract>(app, contract, {
  handlers: {
    List: async () => [],
    // `body` is a CreateMemberRequest, and the result must be a MemberDto.
    Create: async ({ body }) => ({ id: "mem_1", email: body.email, role: "member" }),
  },
});

POST /api/members answers 201 with the new member. Change MemberDto and a handler that returns the old shape stops compiling straight away; regenerate, and the spec and client follow. A missing handler, an unused one or a duplicate route fails at registration, not on the first request.

Also in the box

• Scaffolding: scaffold emits a Hono API, a Nuxt SPA and a typed client package as one pnpm workspace; scaffold-mock derives that workspace from your contract, with a typed mock handler for every endpoint
• Local now, server later: the scaffolded API runs inside the browser during development, then becomes a real server with one task
• The Vite plugin: regenerates contract JSON, openapi.json and schema.d.ts when the contract or its local imports change
• .NET handoff: move the backend to Rivet on .NET and keep every client call site
• Stable diagnostic codes on every lowering error and scaffold warning, with the file and line where there is one, so you can grep for them
• Plumb (installed separately) checks scaffolds against Meridian's house rules: a fresh one starts with zero findings, and task plumb checks it stays there
• @maxanstey-meridian/rivet-ts/tooling: the contract-to-JSON pipeline as a library, for build tools that convert contracts themselves

Documentation

Getting Started · Tutorial · Hono Runtime · CLI Reference · Supported Shapes · Unsupported Shapes (what rivet-ts deliberately doesn't lower)

Contributors should read CONTRIBUTING.md. pnpm test builds first and needs network access: it downloads the pinned Rivet release once, and checks the copied-in contract schema against that release on every run.

License

MIT