rivet-ts

Appearance

rivet-tsTypeScript contracts to working APIs

Write a contract, scaffold a workspace, point the UI at the typed client, and regenerate artifacts with one command.

Get Started
View on GitHub
🧱

Contract first

Write one TypeScript contract that captures routes, inputs, outputs, status codes, errors, examples, and security metadata.

âš¡

Scaffold the workspace

Generate a runnable pnpm workspace — Hono API under `apps/api`, Nuxt SPA under `apps/ui`, typed client package under `packages/contracts`.

📦

OpenAPI 3.1 as the public artifact

The Rivet binary emits openapi.json from the reflected contract; openapi-typescript and openapi-fetch derive the typed client from the spec.

🚀

Promote later

The API runs in-browser during dev via in-process dispatch, becomes a real server with one task, and the contract story carries over to .NET.

Overview ​

  1. write a TypeScript contract (or let scaffold give you a worked example)
  2. scaffold the workspace once
  3. run task install && task dev
  4. consume the typed client from apps/ui/app/app.vue
  5. run task generate after contract changes
  6. promote to a real server (task api:run) when the browser runtime stops being enough

Contract shape ​

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

export interface UserDto {
  id: string;
  name: string;
  email: string;
}

export interface GetUserParams {
  id: string;
}

export interface UsersContract extends Contract<"UsersContract"> {
  GetUser: Endpoint<{
    method: "GET";
    route: "/users/{id}";
    params: GetUserParams;
    response: UserDto;
  }>;
}

Scaffold the app:

bash
pnpm exec rivet-ts scaffold-mock --entry ./contracts.ts --out ./myapp
cd ./myapp
task install
task dev

Then use the typed client (an openapi-fetch instance checked against the generated schema.d.ts):

ts
import { client } from "@myapp/contracts";

const { data, error } = await client.GET("/users/{id}", {
  params: { path: { id: "usr_123" } },
});

scaffold-mock emits the workspace with bootstrap artifacts already in place. After contract changes, task generate re-runs the pipeline: contract entry → api.contract.json (internal IR) → openapi.json (Rivet binary) → schema.d.ts (openapi-typescript).

Pages ​