Node.js HTTP Response Builder

5.0.1 · maintenance · verified Tue Apr 21

node-res is a lightweight Node.js module designed to simplify the creation of HTTP responses by providing a facade over the native `http.ServerResponse` object. It offers utility methods to easily set common HTTP headers, define response statuses, and automatically determine appropriate `Content-Type` headers based on the body content. As of its latest stable version `5.0.1`, published over seven years ago in August 2018, the library appears to be in a maintenance-only state with no active development or regular release cadence. Its key differentiator is its minimal footprint and focus on direct manipulation of the response object without introducing significant abstraction layers, offering helpers for common tasks like sending HTML, JSON, or JSONP, and handling ETags. It is primarily built for CommonJS environments.

Common errors

```
TypeError: nodeRes.send is not a function
```
cause Attempting to use named import syntax (e.g., `import { send } from 'node-res'`) for a CommonJS module that exports a single object, or destructuring `nodeRes` incorrectly.

fix Ensure you are importing the entire module object using `const nodeRes = require('node-res')` and then calling its methods as `nodeRes.send(...)`.
```
ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of index.js to a dynamic import()
```
cause Trying to `require()` an ESM-only package within an older CommonJS context, or `node-res` being used in an environment that incorrectly treats it as ESM.

fix `node-res` is CJS. This error is unlikely for `node-res` itself but could occur if you mix `node-res` with a different, genuinely ESM-only dependency in a CJS project. Ensure your project and dependencies are consistently CJS or ESM, or use dynamic `import()` for ESM modules in CJS.

Warnings

gotcha The `node-res` package has not been updated since August 2018. This means it may not actively address new security vulnerabilities, performance optimizations, or compatibility issues with very recent Node.js runtime versions or web standards.
Fix: Evaluate alternatives for new projects or thoroughly test existing applications with modern Node.js versions. Consider migrating to more actively maintained response utilities or framework-native response objects (e.g., Express.js `res`).
gotcha `node-res` is designed for CommonJS (CJS) environments using `require()`. While some tools might transpile it, direct `import` statements in native ES Modules (ESM) projects might lead to unexpected behavior or require specific build configurations.
Fix: For ESM projects, ensure your build setup correctly handles CJS interop, or stick to `require()` in CJS contexts. For new projects using ESM, consider libraries with explicit ESM support.
gotcha The library directly manipulates the native `http.ServerResponse` object. While this offers low-level control, it might not integrate seamlessly with higher-level web frameworks (like Express.js, Koa, Hapi) that often wrap or extend the native response object with their own abstractions and middleware chains.
Fix: Use `node-res` carefully within frameworks, understanding its interaction with the framework's `res` object. It's generally more suited for barebones Node.js HTTP servers or custom micro-frameworks where you control the entire response lifecycle.

Install

npm install node-res npm
yarn add node-res yarn
pnpm add node-res pnpm

Imports

nodeRes
wrong:
```
import nodeRes from 'node-res'
```
correct:
```
const nodeRes = require('node-res')
```
The library primarily exports a single object for CommonJS. While some transpilers might handle `import nodeRes from 'node-res'`, it's not a native ESM export.
send
wrong:
```
import { send } from 'node-res'
```
correct:
```
nodeRes.send(req, res, body, statusCode)
```
Methods like `send` are properties of the default exported `nodeRes` object, not named exports.
jsonp
wrong:
```
import { jsonp } from 'node-res'
```
correct:
```
nodeRes.jsonp(req, res, data, callbackFn)
```
Similar to `send`, `jsonp` is a method accessed via the `nodeRes` object.

Quickstart

Demonstrates how to set up a basic Node.js HTTP server and use `node-res` to send different types of responses (HTML, JSON, custom status messages, and JSONP) with automatic content-type handling.

const http = require('http');
const nodeRes = require('node-res');

const server = http.createServer((req, res) => {
  if (req.url === '/') {
    // Send a simple HTML response with status 200
    nodeRes.send(req, res, '<h1>Hello from node-res!</h1>');
  } else if (req.url === '/json') {
    // Send a JSON response with status 200
    nodeRes.send(req, res, { message: 'This is a JSON response', timestamp: Date.now() });
  } else if (req.url === '/error') {
    // Send a custom status (500) and message
    nodeRes.send(req, res, 'Something went wrong!', 500);
  } else if (req.url.startsWith('/jsonp')) {
    // Send a JSONP response, expecting '?callback=myCallback' query parameter
    const callbackFn = new URLSearchParams(req.url.split('?')[1]).get('callback') || 'callback';
    nodeRes.jsonp(req, res, { data: 'JSONP data from node-res' }, callbackFn);
  } else {
    // 404 Not Found response
    nodeRes.send(req, res, 'Not Found', 404);
  }
});

const PORT = process.env.PORT || 3000;
server.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log('Try visiting:');
  console.log(`- http://localhost:${PORT}/`);
  console.log(`- http://localhost:${PORT}/json`);
  console.log(`- http://localhost:${PORT}/error`);
  console.log(`- http://localhost:${PORT}/jsonp?callback=myCallbackFunction`);
});

view raw JSON →