tzin

Contract-first TypeScript framework. Types that scale. Realtime built in. AI-native from day one.

tzin — from Nahuatl -tzin, an honorific suffix for what is valued and beloved. A pact between client and server, declared once.

Status: stable (1.0.x). The core works end-to-end (see Benchmarks); 1.0.0 shipped the stable API, and 1.0.2 adds test coverage gates, a wider CI matrix and a public type-clean surface.

npm install @carlos-tzin/tzin

Or scaffold a new project:

npx create-tzin my-app

Documentation

Hosted site: tzin.tzinny.com

• API Reference — all exports, types, and options
• Architecture Guide — request pipeline, design decisions, internals
• Deployment Guide — Docker, Cloudflare Workers, multi-node clustering
• Roadmap — future features

Why another framework?

The TypeScript backend landscape is crowded — and still leaves real gaps:

tzin's answer: declare a contract once, get everything else for free.

import { t } from '@carlos-tzin/tzin'
import { contract, impl, createApp, listen } from '@carlos-tzin/tzin'

const getUser = contract({
  method: 'GET',
  path: '/users/:id',
  params: t.Object({ id: t.String() }),
  responses: {
    200: t.Object({ id: t.String(), name: t.String(), tags: t.Array(t.String()) }),
    404: t.Object({ error: t.String() }),
  },
})

export const getUserRoute = impl(getUser, async ({ params }) => {
  const user = await findUser(params.id)
  if (!user) throw new HttpError(404, 'user not found')
  return { status: 200, body: user }
})

const app = createApp([getUserRoute])
listen(app, 3000)

From that single declaration:

• Handler input is extracted, not guessed: { params } exists because you declared it; add query, body, headers or cookies to the contract and they appear, fully typed and validated per request.
• The compiler enforces your responses: returning a shape that doesn't match the declared 200 body is a type error. Thrown HttpErrors map to their status.
• OpenAPI 3.1 is free: contracts are JSON Schema (TypeBox), so generateOpenApi(routes) needs no translation layer.

Features

Core

Runtime

Realtime

AI-Native

Database

Auth

Jobs

Logging

Testing

Quick Start

1. Scaffold

npx create-tzin my-api
cd my-api

2. Define a contract

// src/routes/users.ts
import { t, contract, impl } from '@carlos-tzin/tzin'

export const getUser = contract({
  method: 'GET',
  path: '/users/:id',
  params: t.Object({ id: t.String() }),
  responses: {
    200: t.Object({ id: t.String(), name: t.String() }),
    404: t.Object({ error: t.String() }),
  },
})

export const getUserRoute = impl(getUser, async ({ params }) => {
  return { status: 200, body: { id: params.id, name: 'Ada' } }
})

3. Create the app

// src/app.ts
import { createApp } from '@carlos-tzin/tzin'
import { getUserRoute } from './routes/users.js'

export const app = createApp([getUserRoute], {
  openapi: true,
  mcp: true,
  meta: { title: 'My API', version: '1.0.0' },
})

4. Run

npm run dev    # tzin dev  -> dev server at http://localhost:3000
npm run build  # tzin build -> production build

The tzin binary ships with the package, so these scripts work after npm install. Without a local install, run it through npm exec:

npx --package @carlos-tzin/tzin tzin dev

CLI

tzin dev [--port N]                                # dev server with hot reload
tzin build                                         # build for production
tzin deploy --target node|workers [--pack] [--docker <tag> [--push]]  # deploy
tzin generate route <name>                         # scaffold a route
tzin generate middleware <name>                    # scaffold middleware
tzin generate test <name>                          # scaffold a test

Benchmarks

100 endpoints with distinct schemas, checked by tsc --extendedDiagnostics:

tzin grows strictly linearly (~130 types/endpoint).

Runtime throughput

Examples

Design principles

• Contract-first, flat registry. A route is data (contract({...})), not a link in a builder chain. Inference cost stays O(1) per endpoint.
• JSON Schema native. TypeBox schemas double as OpenAPI with zero conversion.
• Web Standards runtime. Request in, Response out; adapters stay thin.
• Extractors over magic. Handlers receive exactly what the contract declares.
• Errors are control flow. Throw typed errors; the response union already knows.
• Light DI without ceremony. provide(key, value) at app level seeds typed singletons into every request's context — handlers just ctx.require(db).

Development

npm install
npm test          # vitest — runtime + end-to-end client + type assertions
npm run typecheck # strict tsc across src/test/bench fixtures

License

MIT — see LICENSE.