Typeweaver

Quickstart

This Typeweaver quickstart shows the shortest path from a new spec to generated code. You define one API contract, run the CLI, and get clients, validators, and server artifacts from the same source of truth.

Use it when you want a concrete first example before diving into the broader authoring and server integration docs.

Install the packages

npm install -D @rexeus/typeweaver
npm install @rexeus/typeweaver-core "zod@^4"

Typeweaver requires Zod v4 or later. See Getting Started for the full install matrix including plugin packages.

Create a minimal spec entrypoint

Create api/spec/index.ts:

import {
  defineOperation,
  defineResponse,
  defineSpec,
  HttpMethod,
  HttpStatusCode,
} from "@rexeus/typeweaver-core";
import { z } from "zod";

const todoSchema = z.object({
  id: z.string(),
  title: z.string(),
  completed: z.boolean(),
});

const GetTodoDefinition = defineOperation({
  operationId: "GetTodo",
  method: HttpMethod.GET,
  summary: "Get todo",
  path: "/todos/:todoId",
  request: {
    param: z.object({
      todoId: z.string(),
    }),
  },
  responses: [
    defineResponse({
      name: "GetTodoSuccess",
      statusCode: HttpStatusCode.OK,
      description: "Todo retrieved successfully",
      body: todoSchema,
    }),
  ],
});

export const spec = defineSpec({
  resources: {
    todo: {
      operations: [GetTodoDefinition],
    },
  },
});

This gives you one resource (todo) with one operation (GetTodo).

Generate code

Run the CLI against your spec entrypoint:

npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins clients,hono

What appears in api/generated

Typeweaver generates code you can use immediately, including:

  • request and response types
  • validators
  • a generated TodoClient
  • Hono server output for the todo resource

You will typically see a resource folder such as api/generated/todo, plus shared generated support files.

Was this page helpful?