zod-http-schemas

2.0.5 verified Sat Apr 25 auth: no javascript

Zod-powered HTTP schema library for strongly typed client-server communication. Version 2.0.5, stable. Combines runtime validation from zod with compile-time types for HTTP request and response shapes. Supports path parameters, request body, and response body schemas. Differentiates from plain zod by providing a unified schema definition for both client and server, automatic response trimming to prevent data leaks, and a client using Axios. Key differentiator: single source of truth for API contracts across client and server, with TypeScript type inference.

Common errors

error Cannot find module 'zod-http-schemas/client' or its corresponding type declarations. ↓

cause TypeScript does not recognize the subpath export; tsconfig may not support exports field.

fix

Use TypeScript 4.7+ with moduleResolution 'node16' or 'bundler', or add a path mapping.

error TypeError: zod_http_schemas.createHttpSchema is not a function ↓

cause Using CommonJS require() on an ESM-only package.

fix

Switch to dynamic import: const { createHttpSchema } = await import('zod-http-schemas');

error Property 'body' does not exist on type 'AxiosResponse<...>'. ↓

cause Client returns full AxiosResponse; response body is under .data, not .body.

fix

Access response data via result.data instead of result.body in client code.

Warnings

breaking Version 2.x uses Axios as HTTP client; migrate from 1.x which used fetch. ↓

fix Update client configuration options to align with Axios: baseURL, headers, etc.

deprecated createHttpClient from 'zod-http-schemas' (root) is deprecated; use 'zod-http-schemas/client'. ↓

fix Change import to import { createHttpClient } from 'zod-http-schemas/client'.

gotcha Extraneous response properties are stripped at runtime, which may remove expected fields if schema is incomplete. ↓

fix Ensure responseBody schema includes all properties you want to keep.

gotcha Path parameters must exactly match the URL template; extra or missing params cause TypeScript errors. ↓

fix Verify route string has matching placeholders and params object keys.

breaking Zod v3 peer dependency; zod v2 schemas are incompatible. ↓

fix Upgrade to zod@^3 and update any custom schemas to zod v3 API.

Install

npm install zod-http-schemas

yarn add zod-http-schemas

pnpm add zod-http-schemas

Imports

createHttpSchema

wrong

const createHttpSchema = require('zod-http-schemas')

correct

import { createHttpSchema } from 'zod-http-schemas'

ESM-only package; requires CommonJS users to use dynamic import or esm.

createHttpClient

wrong

import { createHttpClient } from 'zod-http-schemas'

correct

import { createHttpClient } from 'zod-http-schemas/client'

Client-related exports are only available from 'zod-http-schemas/client' subpath.

extractShape
wrong
```
import { extractShape } from 'zod-http-schemas'
```
correct
```
import type { extractShape } from 'zod-http-schemas'
```
extractShape is a type-only export; use import type to avoid runtime import in bundlers.

Quickstart

Creates a shared HTTP schema and uses the client to make two typed requests.

import { createHttpSchema } from 'zod-http-schemas';
import { createHttpClient } from 'zod-http-schemas/client';
import { z } from 'zod';

const apiSchema = createHttpSchema({
  'GET /greet/:name': {
    responseBody: z.string(),
  },
  'POST /sum': {
    requestBody: z.array(z.number()),
    responseBody: z.number(),
  },
});

const client = createHttpClient(apiSchema, { baseURL: process.env.API_BASE ?? 'http://localhost:3000' });

async function main() {
  const greeting = await client.get('/greet/:name', { params: { name: 'World' } });
  console.log(greeting);
  const sum = await client.post('/sum', { body: [1, 2, 3] });
  console.log(sum);
}
main().catch(console.error);