Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
HttpError
✓ import { HttpError } from 'http-response-kit';
✗ const HttpError = require('http-response-kit').HttpError;
Primary way to import the HttpError class for creating and throwing HTTP-specific errors.
HttpResponse
✓ import { HttpResponse } from 'http-response-kit';
✗ const HttpResponse = require('http-response-kit').HttpResponse;
Main class for formatting standardized success and error responses.
configure
✓ import { configure } from 'http-response-kit';
✗ require('http-response-kit').configure({});
Used for global configuration of the library, affecting behavior like development mode or timestamp inclusion in responses. Should be called early in your application lifecycle.
HttpError.notFound
✓ throw HttpError.notFound('Resource not found');
✗ throw new HttpError(404, { message: 'Resource not found' }); // Less concise
Recommended factory method for common 4xx client errors like '404 Not Found'. More readable and convenient than direct constructor calls.
Demonstrates setting up a basic Express server, configuring http-response-kit, handling successful API responses, throwing and catching `HttpError` instances, and implementing a global error handling middleware for consistent API error formatting.
import express from 'express';
import { HttpError, HttpResponse, configure } from 'http-response-kit';
const app = express();
// Configure the library globally
configure({
isDevelopment: process.env.NODE_ENV === 'development',
includeTimestamp: true,
// Optional: customize default messages or add global metadata
defaultErrorMessage: 'An unexpected error occurred.',
});
// Mock database function
const findUser = async (id: string) => {
if (id === '123') {
return { id: 123, name: 'John Doe', email: 'john.doe@example.com' };
}
return null;
};
// Define a route that uses http-response-kit
app.get('/users/:id', async (req, res) => {
try {
const user = await findUser(req.params.id);
if (!user) {
// Throw an HttpError directly
throw HttpError.notFound(`User with ID ${req.params.id} not found`);
}
// Format a success response
res.status(200).json(HttpResponse.ok(user, 'User retrieved successfully'));
} catch (err) {
// Ensure all errors are converted to HttpError for consistent output
const error = HttpError.fromError(err);
// Send the formatted error response with the correct status code
res.status(error.code).json(HttpResponse.error(error));
}
});
// Global error handler middleware for Express
// This should be defined AFTER all your routes and other middleware.
app.use((err: any, req: express.Request, res: express.Response, next: express.NextFunction) => {
// Convert any unhandled error (including non-HttpErrors) into a standardized HttpError
const error = HttpError.fromError(err);
// Log the error in development, or less detail in production
if (configure().isDevelopment) {
console.error('Unhandled API Error:', error.originalError || error);
}
// Send the standardized error response
res.status(error.code).json(HttpResponse.error(error));
});
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(`Server running on port ${PORT}`);
console.log(`Try: GET http://localhost:${PORT}/users/123`);
console.log(`Try: GET http://localhost:${PORT}/users/456`);
});
Errors
Common errors & fixes
TypeError: (0 , http_response_kit__WEBPACK_IMPORTED_MODULE_0__.HttpError).notFound is not a function
This typically occurs in a CommonJS environment or incorrect bundling when trying to access `HttpError.notFound` as a property of a default import, or if the library's exports are not correctly interpreted as named exports.
fixEnsure you are using named imports correctly: `import { HttpError } from 'http-response-kit';` for ESM/TypeScript. For CommonJS, use `const { HttpError } = require('http-response-kit');`. ReferenceError: configure is not defined
The `configure` function was not imported or is out of scope when called.
fixAdd `configure` to your named imports: `import { HttpError, HttpResponse, configure } from 'http-response-kit';`. UnhandledPromiseRejectionWarning: HttpError: User not found
An `HttpError` was thrown in an asynchronous context (e.g., an `async` function) but was not caught by a `try...catch` block, or the global error handler is not properly set up to catch such rejections.
fixEnsure all `async` route handlers and service functions that might throw `HttpError` are wrapped in `try...catch` blocks, or that your global error handling middleware in frameworks like Express correctly intercepts unhandled promise rejections.
Audit
Dependencies
No dependency data recorded yet.