Standardized HTTP responses for Node.js

A lightweight, flexible utility to format and send consistent HTTP responses in Express, Fastify, or any Node.js framework.

bash

npm install http-reply

Get Started View on GitHub

Features

Everything you need for clean API responses.

Framework Agnostic

Compatible with Express, Fastify, or custom frameworks via adapters.

Standardized Responses

Ensures consistent response structure across your entire API.

Configurable Options

Customize response fields, timestamps, logging, and more.

Static Methods

Send responses quickly without instantiating the class.

TypeScript Support

Fully typed with included TypeScript declarations for a better DX.

ESM + CJS Support

Native support for both ES6 modules and CommonJS without hacks.

Usage

Quick Start with common patterns.

javascript

import { HttpReply } from 'http-reply';
import express from 'express';

const app = express();

app.get('/example', (req, res) => {
  HttpReply.success(res, {
    message: 'Operation successful',
    data: { user: 'John Doe' },
    metaData: { requestId: '12345' },
  });
});

app.listen(3000, () => console.log('Server running on port 3000'));

Supported Methods

Built-in helpers for common HTTP status codes.

Method	Status Code	Description
`success`	200	Successful request
`created`	201	Resource created successfully
`accepted`	202	Request accepted for processing
`noContent`	204	No content to return
`badRequest`	400	Invalid request
`unauthorized`	401	Authentication required
`forbidden`	403	Access denied
`notFound`	404	Resource not found
`conflict`	409	Resource conflict
`tooManyRequests`	429	Rate limit exceeded
`error`	500	Internal server error
`notImplemented`	501	Feature not implemented
`serviceUnavailable`	503	Service temporarily unavailable
`response`	Custom	Generic response with custom status code

Configuration Options

Customize HttpReply to fit your needs.

Option	Type	Default	Description
`includeTimestamp`	Boolean	false	Include a timestamp in the response.
`includeCode`	Boolean	true	Include the status code in the response body.
`includeMessage`	Boolean	true	Include the message in the response body.
`includeError`	Boolean	true	Include error details in the response body.
`includeMetaData`	Boolean	true	Include metadata in the response body.
`enableLogging`	Boolean	true	Enable error logging for invalid configurations.
`stringify`	Boolean	false	Stringify the response body before sending.
`customFields`	Object	{}	Additional fields to include in every response.
`dateFormat`	String	'unix'	Format for timestamps ('iso' or 'unix').
`adapter`	Function	null	Custom adapter for non-Express/Fastify frameworks.

Custom Adapter

For non-Express/Fastify frameworks, provide a custom adapter to bridge HttpReply with your server's response object.

javascript

import { HttpReply } from 'http-reply';

const reply = new HttpReply({
  adapter: (res, statusCode, payload) => {
    res.setStatusCode(statusCode);
    res.setBody(payload);
    return res;
  },
});

reply.success(res, {
  message: 'Custom adapter response',
  data: { key: 'value' },
});

Response Shape

Standardized JSON output structure.

Default Output

json

{
  "message": "User fetched",
  "data": { "id": 1, "name": "John" },
  "metaData": { "total": 1 },
  "code": 200
}

With Timestamp

json

{
  "message": "User fetched",
  "data": { "id": 1, "name": "John" },
  "metaData": { "total": 1 },
  "code": 200,
  "timestamp": "2025-06-13T17:25:00.000Z"
}