Express Zod API

Start your API server with I/O schema validation and custom middlewares in minutes.

1. Overview
2. How it works
3. Quick start — Fast Track
4. Basic features
5. Routing including static file serving
6. Middlewares
7. Context
8. Using native express middlewares
9. Refinements
10. Query string parser
11. Transformations
12. Top level transformations and mapping
13. Dealing with dates
14. Pagination
15. Cross-Origin Resource Sharing (CORS)
16. Enabling HTTPS
17. Enabling compression
18. Customizing logger
19. Child logger
20. Advanced features
21. Customizing input sources
22. Headers as input source
23. Response customization
24. Empty response
25. Non-JSON response including file downloads
26. Error handling
27. Production mode
28. HTML Forms (URL encoded)
29. File uploads
30. Connect to your own express app
31. Testing endpoints
32. Testing middlewares
33. Integration and Documentation
34. Zod Plugin
35. End-to-End Type Safety
36. Creating documentation
37. Tagging the endpoints
38. Deprecated schemas and routes
39. Customizable brands handling
40. Special needs
41. Different responses for different status codes
42. Array response for migrating legacy APIs
43. Accepting raw data
44. Profiling
45. Graceful shutdown
46. Subscriptions
47. Caveats
48. Excessive properties in endpoint output
49. Your input to my output

See also Changelog and automated migration.

Overview

I made this framework because of the often repetitive tasks of starting web server APIs with the need to validate input data. It integrates and provides the capabilities of popular web server, logging, validation, and documenting solutions. Therefore, many basic tasks can be achieved faster and easier, in particular:

• You can describe web server routes as a hierarchical object.
• You can keep the endpoint's input and output type declarations right next to its handler.
• All input and output data types are validated, so it ensures you won't have an empty string, null or undefined where you expect a number.
• Variables within an endpoint handler have types according to the declared schema, so your IDE and TypeScript will provide you with necessary hints to focus on bringing your vision to life.
• All of your endpoints can respond consistently.
• The expected endpoint input and response types can be exported to the frontend, giving you end-to-end type safety so you don't get confused about the field names when you implement the client for your API.
• You can generate your API documentation in OpenAPI 3.1 and JSON Schema compatible format.

Contributors

These people contributed to the improvement of the framework by reporting bugs, making changes, and suggesting ideas:

How it works

Concept

The API operates object schemas for input and output validation. The object being validated is the combination of certain request properties. It is available to the endpoint handler as the input parameter. Middlewares have access to all request properties, they can provide endpoints with ctx (context). The object returned by the endpoint handler is called output. It goes to the ResultHandler which is responsible for transmitting consistent responses containing the output or possible error. Much can be customized to fit your needs.

Technologies

• Typescript first.
• Web server — Express.js v5.
• Schema validation — Zod 4.x;
• Supports any logger having info(), debug(), error() and warn() methods;
• Built-in console logger with colorful and pretty inspections by default.
• Generators:
• Documentation — OpenAPI 3.1 (former Swagger);
• Client side types — inspired by zod-to-ts.
• File uploads — Express-FileUpload (based on Busboy).

Quick start

Installation

Install the framework, its peer dependencies and type assistance packages using your favorite package manager.

# example for pnpm:
pnpm add express-zod-api express zod http-errors
pnpm add -D @types/express @types/node @types/http-errors

Environment preparation

Enable the following compilerOptions in your tsconfig.json to make it work as expected:

{
  "compilerOptions": {
    "strict": true,
    "skipLibCheck": true
  }
}

Set up config

Create a minimal configuration. Find out all configurable options in sources.

import { createConfig } from "express-zod-api";

const config = createConfig({
  http: { listen: 8090 }, // port, UNIX socket or Net::ListenOptions
  cors: false, // decide whether to enable CORS
});

Create your first endpoint

Use the default factory to make an endpoint that responds with "Hello, World" or "Hello, {name}" depending on inputs. Learn how to make factories for custom response and by adding middlewares.

```ts import { defaultEndpoi