Node.js HTTP Request Parser

2.1.2 verified Thu Apr 23 auth: no javascript abandoned

node-req is a minimalist I/O module designed to parse and extract specific values from Node.js's native `http.IncomingMessage` object, explicitly designed with no side-effects. It provides a set of helper methods for accessing common request components such as query strings, HTTP method, headers, IP addresses, protocol (HTTP/HTTPS), subdomains, and content negotiation details. Currently at version 2.1.2, this package has not received updates in approximately six years, indicating it is no longer actively maintained. Its core differentiation lies in its pure parsing approach, making no assumptions about routing or higher-level HTTP handling, thus allowing it to integrate into various Node.js server architectures as a low-level utility. It leverages the `qs` package internally for robust query string parsing.

Common errors

error TypeError: nodeReq.get is not a function ↓

cause Attempting to call `nodeReq.get` when `nodeReq` was not correctly `require`'d, or if `nodeReq` resolves to an unexpected value (e.g., `undefined`). This can happen if using `import nodeReq from 'node-req'` in an ESM file where it's treated as a default export, which is incorrect for this CJS package.

fix

Ensure you are using const nodeReq = require('node-req') for importing in a CommonJS context. If in an ESM project, consider using import * as nodeReq from 'node-req' or migrating to an ESM-compatible alternative.

error ERR_REQUIRE_ESM ↓

cause Trying to `require()` this CommonJS package directly within an ES Module (ESM) file, or in a project where `"type": "module"` is set in `package.json`.

fix

Either convert the consuming file back to CommonJS (by ensuring it does not use import/export and removing "type": "module" from its nearest package.json), or use a dynamic import (const nodeReq = await import('node-req')) within the ESM file, then access its properties (nodeReq.default.get(req)). The best long-term fix is to migrate to an actively maintained ESM-compatible library.

Warnings

breaking The `request` package, a popular HTTP client which shares a similar name, was fully deprecated in February 2020. While `node-req` is a distinct I/O parsing library and not a client, its lack of maintenance means it may contain unfixed bugs or security vulnerabilities and could become incompatible with newer Node.js versions. ↓

fix Consider migrating to actively maintained alternatives for HTTP request parsing or ensuring thorough security audits if continuing to use this library. For HTTP client functionality, use `undici`, `axios`, or native `fetch`.

gotcha This package is exclusively CommonJS (`require`) and does not support ES Modules (`import`). Attempting to use `import` syntax will result in `ERR_REQUIRE_ESM` or similar module resolution errors in projects configured for ESM. ↓

fix Ensure your project or the specific file using `node-req` is configured for CommonJS, or use dynamic `import()` if absolutely necessary within an ESM context, though this is generally not recommended for core dependencies.

gotcha The package has not been updated in approximately six years. This means it may not be compatible with the latest Node.js runtime features or security best practices, and any new issues discovered will likely not be addressed. ↓

fix For new projects, prefer modern, actively maintained libraries for HTTP request parsing. For existing projects, evaluate the risk of using an unmaintained dependency and consider gradual migration.

Install

npm install node-req

yarn add node-req

pnpm add node-req

Imports

nodeReq
wrong
```
import nodeReq from 'node-req'
```
correct
```
const nodeReq = require('node-req')
```
This package is CommonJS-only and relies on `require()`. Attempting to use `import` will result in an error in ESM contexts.
get
wrong
```
import { get } from 'node-req'
```
correct
```
const { get } = require('node-req')
```
While CommonJS destructuring works, the package's primary export pattern is a single object containing all methods. Direct named imports via `import` are not supported.
method
wrong
```
import { method } from 'node-req'
```
correct
```
const { method } = require('node-req')
```
As with other methods, this package is CommonJS-only. Destructuring individual methods from the `require`'d object is a valid pattern for convenience.

Quickstart

This quickstart demonstrates how to set up a basic Node.js HTTP server and use `node-req` to parse various components of an incoming request, including query parameters, HTTP method, headers, and client IP, then respond with the extracted information.

const http = require('http');
const nodeReq = require('node-req');

const server = http.createServer((req, res) => {
  // Parse query string (e.g., /?name=Alice&age=30)
  const query = nodeReq.get(req);
  const name = query.name || 'Guest';

  // Get HTTP method (e.g., GET, POST)
  const method = nodeReq.method(req);

  // Get all request headers
  const headers = nodeReq.headers(req);
  const userAgent = nodeReq.header(req, 'user-agent');

  // Get client IP address
  const ip = nodeReq.ip(req, true); // `true` for trusting proxy headers

  // Check if the request has a body (e.g., for POST, PUT)
  const hasBody = nodeReq.hasBody(req);

  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end(
    `Hello, ${name}!\n` +
    `Method: ${method}\n` +
    `User-Agent: ${userAgent}\n` +
    `Client IP: ${ip}\n` +
    `Has Body: ${hasBody}\n` +
    `Full Query: ${JSON.stringify(query)}\n`
  );
});

const PORT = process.env.PORT || 3000;
server.listen(PORT, () => {
  console.log(`Server listening on http://localhost:${PORT}`);
  console.log('Try visiting: http://localhost:3000/?name=Bob&city=NewYork');
});