Installation

Install Express Zod API and configure your TypeScript project

Prerequisites

Before installing Express Zod API, make sure you have:

• Node.js: Version 20.19.0, 22.12.0, or 24.0.0 or higher
• TypeScript: Version 5.1.3 or higher
• Package Manager: npm, yarn, or pnpm

Express Zod API requires TypeScript and works best with strict type checking enabled.

Install with Package Manager

Choose your preferred package manager and install Express Zod API along with its required peer dependencies:

npm

# Install core dependencies
npm install express-zod-api express zod http-errors

# Install TypeScript type definitions
npm install -D @types/express @types/node @types/http-errors

pnpm

# Install core dependencies
pnpm add express-zod-api express zod http-errors

# Install TypeScript type definitions
pnpm add -D @types/express @types/node @types/http-errors

yarn

# Install core dependencies
yarn add express-zod-api express zod http-errors

# Install TypeScript type definitions
yarn add -D @types/express @types/node @types/http-errors

Required Dependencies

Here’s what each dependency does:

Package	Purpose	Type
express-zod-api	The main framework	Runtime
express	Web server (v5.x)	Runtime (peer)
zod	Schema validation (v4.x)	Runtime (peer)
http-errors	HTTP error handling	Runtime (peer)
@types/express	Express TypeScript types	Dev (peer)
@types/node	Node.js TypeScript types	Dev (peer)
@types/http-errors	HTTP errors TypeScript types	Dev (peer)

Express Zod API requires Express v5 and Zod v4. If you’re using older versions, you’ll need to upgrade or use an older version of Express Zod API (v23.x for Zod 3.x).

Optional Dependencies

Depending on your needs, you may want to install these optional packages:

File Uploads

For handling file uploads with multipart/form-data:

npm

npm install express-fileupload
npm install -D @types/express-fileupload

pnpm

pnpm add express-fileupload
pnpm add -D @types/express-fileupload

yarn

yarn add express-fileupload
yarn add -D @types/express-fileupload

Response Compression

For enabling gzip/brotli compression:

npm

npm install compression
npm install -D @types/compression

pnpm

pnpm add compression
pnpm add -D @types/compression

yarn

yarn add compression
yarn add -D @types/compression

Documentation UI

For serving interactive Swagger documentation:

npm

npm install swagger-ui-express
npm install -D @types/swagger-ui-express

pnpm

pnpm add swagger-ui-express
pnpm add -D @types/swagger-ui-express

yarn

yarn add swagger-ui-express
yarn add -D @types/swagger-ui-express

TypeScript Configuration

Express Zod API requires specific TypeScript compiler options to work correctly. Update your tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    // Required for Express Zod API
    "strict": true,
    "skipLibCheck": true,

    // Recommended settings
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

1. Enable strict mode

   The strict option enables all strict type checking options. This is essential for catching type errors early and ensuring Express Zod API works as expected.

2. Skip library checks

   The skipLibCheck option improves compilation speed by skipping type checking of declaration files. This is safe and recommended.

3. Configure module system

   Express Zod API works with both CommonJS and ES modules. The example above uses ES modules ("module": "ESNext"), which is recommended for new projects.

Using CommonJS? Set "module": "commonjs" and "moduleResolution": "node" instead. Both module systems are fully supported.

Project Structure

Here’s a recommended project structure for your Express Zod API application:

my-api/
├── src/
│   ├── config.ts          # Server configuration
│   ├── index.ts           # Entry point
│   ├── routing.ts         # Route definitions
│   ├── endpoints/
│   │   ├── users.ts       # User-related endpoints
│   │   └── auth.ts        # Auth-related endpoints
│   ├── middlewares/
│   │   ├── auth.ts        # Authentication middleware
│   │   └── logging.ts     # Logging middleware
│   └── factories/
│       └── authenticated.ts # Factories with middleware
├── package.json
└── tsconfig.json

Verify Installation

Create a simple test file to verify everything is installed correctly:

test.ts

import { createConfig, createServer, defaultEndpointsFactory } from "express-zod-api";
import { z } from "zod";

const config = createConfig({
  http: { listen: 8080 },
  cors: true,
});

const endpoint = defaultEndpointsFactory.build({
  method: "get",
  input: z.object({}),
  output: z.object({ message: z.string() }),
  handler: async () => ({ message: "Hello, Express Zod API!" }),
});

const routing = {
  test: endpoint,
};

createServer(config, routing);
console.log("Server running on http://localhost:8080");

Run it with:

tsx (recommended)

npx tsx test.ts

ts-node

npx ts-node test.ts

Compile first

npx tsc
node dist/test.js

If you see “Server running on http://localhost:8080”, you’re all set!

The tsx package is recommended for running TypeScript files directly during development. Install it with npm install -D tsx.

Troubleshooting

Module resolution errors

If you see errors about module resolution:

1. Make sure @types/node is installed
2. Check that your tsconfig.json has correct moduleResolution setting
3. For ES modules, ensure your package.json has "type": "module"

Peer dependency warnings

Express Zod API has several peer dependencies that must be installed:

• express (required)
• zod (required)
• http-errors (required)
• typescript (required for development)

Some peer dependencies are optional and only needed if you use specific features (compression, file uploads, etc.).

Type errors with Zod

If you’re seeing type errors related to Zod:

1. Ensure you’re using Zod v4.x (check with npm list zod)
2. Make sure strict mode is enabled in tsconfig.json
3. Clear your TypeScript cache: rm -rf node_modules/.cache

Express version conflicts

Express Zod API requires Express v5.x. If you have v4.x:

npm install express@^5.0.0 @types/express@^5.0.0

Note that Express v5 has some breaking changes from v4. See the Express migration guide.

Next Steps

Now that you have Express Zod API installed, let’s build your first API:

Quickstart Guide

Create a working API in under 5 minutes