Overview
This page provides a comprehensive reference for all configuration options available in Express Zod API. Options are organized by category.
Common Configuration
These options are available in all configurations:
cors
cors
boolean | HeadersProvider
required
Enables cross-origin resource sharing (CORS)
boolean | HeadersProvider
Required: Yes
Default: N/A (must be explicitly set)
Examples:
// Enable with default headers
cors: true
// Disable CORS
cors: false
// Custom CORS headers
cors: ({ defaultHeaders, request, endpoint, logger }) => ({
...defaultHeaders,
"Access-Control-Allow-Origin": "https://example.com",
"Access-Control-Max-Age": "86400",
})
logger
Type: BuiltinLoggerConfig | AbstractLogger
Default: { level: "debug", color: true, depth: 2 }
Built-in Logger Options:
| Option | Type | Description |
|---|
level | "debug" | "info" | "warn" | "error" | Minimum log level |
color | boolean | Enable colored output |
depth | number | Object inspection depth |
// Built-in logger
logger: { level: "info", color: false, depth: 3 }
// Winston
import winston from "winston";
logger: winston.createLogger({ ... })
// Pino
import pino from "pino";
logger: pino({ level: "info" })
errorHandler
Type: AbstractResultHandler
Default: defaultResultHandler
Description: Handles routing, parsing, and upload errors.
import { ResultHandler } from "express-zod-api";
errorHandler: new ResultHandler({
positive: (data) => ({ schema: z.object({ data }), mimeType: "application/json" }),
negative: z.object({ error: z.string() }),
handler: ({ error, response }) => {
if (error) {
response.status(500).json({ error: error.message });
}
},
})
Partial<InputSources>
Default:
{
get: ["query", "params"],
post: ["body", "params", "files"],
put: ["body", "params"],
patch: ["body", "params"],
delete: ["query", "params"],
}
input.
inputSources: {
get: ["headers", "query", "params"],
post: ["body", "params"],
}
childLoggerProvider
Type: (params: { parent: Logger; request: Request }) => Logger | Promise<Logger>
Default: None
Description: Creates a request-scoped child logger.
import { randomUUID } from "crypto";
childLoggerProvider: ({ parent, request }) =>
parent.child({ requestId: randomUUID() })
accessLogger
Type: ((request: Request, logger: Logger) => void) | null
Default: ({ method, path }, logger) => logger.debug(${method}: ${path})
Description: Logs each request. Set to null to disable.
accessLogger: ({ method, path, ip }, logger) =>
logger.info(`${method} ${path} from ${ip}`)
wrongMethodBehavior
Type: 404 | 405
Default: 405
Description: HTTP status code when wrong method is used.
404: Returns Not Found405: Returns Method Not Allowed with Allow header
methodLikeRouteBehavior
Type: "method" | "path"
Default: "method"
Description: How to treat routing keys that match HTTP method names.
startupLogo
Type: boolean
Default: true
Description: Show ASCII logo on server start.
Server Configuration
These options are for standalone servers (using createServer()):
http
Type: { listen: number | string | ListenOptions }
Description: HTTP server configuration.
// Port number
http: { listen: 8090 }
// UNIX socket
http: { listen: "/var/run/app.sock" }
// Full options
http: { listen: { port: 8090, host: "0.0.0.0" } }
https
Type: { options: ServerOptions; listen: number | string | ListenOptions }
Description: HTTPS server with TLS certificates.
import { readFileSync } from "fs";
https: {
options: {
cert: readFileSync("cert.pem"),
key: readFileSync("key.pem"),
},
listen: 443,
}
beforeRouting
Type: (params: { app: Express; getLogger: GetLogger }) => void | Promise<void>
Description: Configure Express app before routes are attached.
import swaggerUi from "swagger-ui-express";
beforeRouting: ({ app }) => {
app.use("/docs", swaggerUi.serve, swaggerUi.setup(spec));
}
jsonParser
Type: RequestHandler | false
Default: express.json()
Description: JSON body parser or false to disable.
import express from "express";
jsonParser: express.json({ limit: "10mb" })
RequestHandler | false
Default: express.urlencoded({ extended: false })
Description: Form body parser or false to disable.
import express from "express";
formParser: express.urlencoded({ extended: true })
upload
Type: boolean | UploadOptions
Description: Enable file uploads.
Options:
interface UploadOptions {
limits?: {
fileSize?: number;
files?: number;
fields?: number;
};
limitError?: HttpError;
beforeUpload?: (params: {
request: Request;
logger: Logger;
}) => void | Promise<void>;
debug?: boolean;
}
import createHttpError from "http-errors";
upload: {
limits: { fileSize: 5 * 1024 * 1024 },
limitError: createHttpError(413, "File too large"),
beforeUpload: ({ request }) => {
if (!request.headers.authorization) {
throw createHttpError(401, "Unauthorized");
}
},
}
compression
Type: boolean | CompressionOptions
Description: Enable GZIP/Brotli compression.
compression: {
threshold: "1kb",
level: 6,
filter: (req, res) => {
if (req.headers["x-no-compression"]) return false;
return compression.filter(req, res);
},
}
queryParser
Type: "simple" | "extended" | ((str: string) => any)
Default: "simple"
Description: Query string parser.
import qs from "qs";
// Simple parser
queryParser: "simple"
// Extended parser (nested objects)
queryParser: "extended"
// Custom parser
queryParser: (str) => qs.parse(str, { comma: true })
gracefulShutdown
Type: GracefulShutdownConfig
Options:
interface GracefulShutdownConfig {
timeout?: number; // milliseconds
events?: string[]; // default: ["SIGTERM", "SIGINT"]
beforeShutdown?: () => void | Promise<void>;
onShutdown?: (signal: string) => void | Promise<void>;
}
gracefulShutdown: {
timeout: 30000,
events: ["SIGTERM", "SIGINT", "SIGUSR2"],
beforeShutdown: async () => {
await db.disconnect();
await cache.quit();
},
onShutdown: async (signal) => {
logger.info(`Received ${signal}, shutting down`);
},
}
App Configuration
These options are for attaching to an existing Express app:
app
Type: Express | Router
Required: Yes (for app config)
Description: Express application or router instance.
import express from "express";
import { createConfig, attachRouting } from "express-zod-api";
const app = express();
const config = createConfig({
app,
cors: true,
logger: { level: "info" },
});
attachRouting(config, routing);
app.listen(8090);
Type Definitions
type InputSource = "query" | "body" | "files" | "params" | "headers";
type InputSources = Record<Method, InputSource[]>;
Method
type Method = "get" | "post" | "put" | "patch" | "delete";
type HeadersProvider = (params: {
defaultHeaders: Record<string, string>;
request: Request;
endpoint: AbstractEndpoint;
logger: Logger;
}) => Record<string, string> | Promise<Record<string, string>>;
See Also