3. If using Jest, add moduleNameMapper entries mirroring the paths above in jest.config.ts.

4. No environment variables are required by the core library. Individual adapters (serverless, etc.) may require cloud-provider credentials at runtime — consult their README files inside source/.

5. Ensure "moduleResolution": "bundler" or "node16" in tsconfig.json for ESM compatibility.

Public API

initContract

import { initContract } from '@ts-rest/core';
const c = initContract();

Entry point for defining an API contract. Call c.router(...) to declare route shapes with method, path, query/body/response schemas. The returned contract object is the single source of truth shared between client and server.

initClient

import { initClient } from '@ts-rest/core';
const client = initClient(contract, {
  baseUrl: 'http://localhost:3000',
  baseHeaders: {},
});

Creates a fully typed RPC-like client from a contract. Each key on client is an async function whose parameters and return type are inferred from the contract definition. Use this on the frontend or in tests to call the API.

createExpressEndpoints

import { createExpressEndpoints } from '@ts-rest/express';
createExpressEndpoints(contract, router, app, options?);

Mounts all routes from a ts-rest server router onto an Express app, wiring up request validation, response shaping, and type checking automatically. Call this once during server startup after defining your implementation router.

RequestValidationError

import { RequestValidationError } from '@ts-rest/express';
// shape: { pathParams, headers, query, body } — each is a ZodError or undefined

Thrown (or passed to next()) when an incoming Express request fails contract validation. Catch it in an Express error handler to return structured 400 responses.

TsRestModule (NestJS)

import { TsRestModule } from '@ts-rest/nest';
@Module({ imports: [TsRestModule.register({ isGlobal: true })] })
export class AppModule {}

NestJS dynamic module that wires the ts-rest interceptor globally. Register it once in your root module; individual controllers then use @TsRest(contract) decorators.

Working examples

Scenario - Define a contract and call it from a client

Define the contract in a shared file, then consume it with initClient:

import { initContract } from '@ts-rest/core';
import { initClient } from '@ts-rest/core';
import { z } from 'zod';

const c = initContract();

export const contract = c.router({
  getUser: {
    method: 'GET',
    path: '/users/:id',
    pathParams: z.object({ id: z.string() }),
    responses: { 200: z.object({ id: z.string(), name: z.string() }) },
  },
  createUser: {
    method: 'POST',
    path: '/users',
    body: z.object({ name: z.string() }),
    responses: { 201: z.object({ id: z.string(), name: z.string() }) },
  },
});

const client = initClient(contract, {
  baseUrl: 'http://localhost:3000',
  baseHeaders: {},
});

async function main() {
  const result = await client.getUser({ params: { id: '42' } });
  if (result.status === 200) {
    console.log(result.body.name);
  }
}

Scenario - Implement the contract on an Express server

import express from 'express';
import { initServer } from '@ts-rest/core';
import { createExpressEndpoints, RequestValidationError } from '@ts-rest/express';
import { contract } from './contract';

const app = express();
app.use(express.json());

const s = initServer();

const router = s.router(contract, {
  getUser: async ({ params }) => {
    // params.id is typed as string
    return { status: 200, body: { id: params.id, name: 'Alice' } };
  },
  createUser: async ({ body }) => {
    return { status: 201, body: { id: 'new-id', name: body.name } };
  },
});

createExpressEndpoints(contract, router, app);

// Handle validation errors
app.use((err: unknown, _req: any, res: any, next: any) => {
  if (err instanceof RequestValidationError) {
    return res.status(400).json({ error: 'Validation failed', details: err.body?.issues });
  }
  next(err);
});

app.listen(3000);

Scenario - NestJS controller with ts-rest decorators

import { Controller } from '@nestjs/common';
import { TsRest, TsRestHandler, tsRestHandler } from '@ts-rest/nest';
import { contract } from './contract';

@Controller()
export class UserController {
  @TsRest(contract.getUser)
  @TsRestHandler(contract.getUser)
  async getUser() {
    return tsRestHandler(contract.getUser, async ({ params }) => {
      return { status: 200 as const, body: { id: params.id, name: 'Alice' } };
    });
  }
}

Register TsRestModule in AppModule and the interceptor handles response shaping automatically.

File walkthrough

• core/ - The foundation: initContract, initClient, initServer, Zod utilities, path helpers, type inference utilities, and error classes (ResponseValidationError, UnknownStatusError, ValidationError).
• express/ - Express adapter. createExpressEndpoints is the primary export; RequestValidationError surfaces validation failures; types.ts holds handler/options type definitions.
• fastify/ - Fastify plugin adapter. Exposes a single entry via ts-rest-fastify.ts.
• nest/ - Full NestJS integration: TsRestModule, @TsRest() route decorator, @TsRestRequest() param decorator, interceptor for response shaping, and tsRestHandler helper.
• next/ - Next.js API route helpers (createNextRouter) and a Next.js-compatible client factory.
• open-api/ - Generates an OpenAPI 3.x document from any ts-rest contract; no runtime dependency on Express or Fastify.
• react-query/ - Wraps initClient to return TanStack Query v4 hooks (useQuery, useMutation) typed from the contract.
• react-query-v5/ - Same as above but for TanStack Query v5 API.
• serverless/ - Adapters for AWS Lambda and Azure Functions; maps handler inputs/outputs to the ts-rest contract shape.
• solid-query/ - Solid.js TanStack Query hooks, mirroring the react-query adapter.
• vue-query/ - Vue TanStack Query hooks, mirroring the react-query adapter.

Common pitfalls and fixes

• Path alias not resolving at runtime: tsconfig paths are compile-time only; add the same mappings to tsconfig-paths or use a bundler that resolves them (Webpack, Vite, esbuild with alias).
• initServer missing from imports: It is exported from @ts-rest/core (re-exported via server.ts), not from the adapter packages; import it from @ts-rest/core.
• Zod version mismatch: ts-rest's Zod utilities target Zod v3; using Zod v4 can break z.object inference — pin "zod": "^3.22.0" in package.json.
• status must be const-asserted: Return { status: 200 as const, body: ... } in server handlers; without as const, TypeScript widens to number and the discriminated union breaks.
• NestJS global pipes conflict: Using ValidationPipe globally alongside ts-rest can double-validate bodies and throw before ts-rest sees the request; disable ValidationPipe for ts-rest routes or set validateCustomDecorators: false.
• ESM/CJS interop in monorepos: If your bundler emits ESM but a consumer expects CJS, set "module": "CommonJS" in the adapter's tsconfig.lib.json or configure dual-package exports in package.json.

Vibe-coding prompt template

I have the ts-rest source libraries located at `libs/ts-rest/` in my project.
I also have `USAGE.md` in the same directory as this prompt.

My project uses: [describe your stack: Express / NestJS / Next.js, Zod version, TypeScript version, monorepo tool if any].

Please help me integrate ts-rest step by step:
1. Read `USAGE.md` and the file excerpts to understand the real exports.
2. Create a shared contract file using `initContract` from `@ts-rest/core`.
3. Wire up the server adapter appropriate for my framework using the real
   exported functions (`createExpressEndpoints`, `TsRestModule`, etc.).
4. Create a typed client using `initClient` from `@ts-rest/core`.
5. Add tsconfig path aliases pointing to `libs/ts-rest/*/src/index.ts`.
6. Show me how to handle `RequestValidationError` (Express) or use
   `TsRestHandler` (NestJS) with real import paths from `libs/ts-rest/`.

Do not invent any exports. Only use symbols documented in `USAGE.md`.

License and credit

ts-rest is released under the MIT License (see source/LICENSE if present, or the GitHub repository). Upstream package: @ts-rest/core and related @ts-rest/* packages maintained by the ts-rest organization.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

Prism API Mock Server and Contract Testing Tool

Automation, Utilities & Developer Tools

무료