Tinyreq HTTP(s) Requests

3.4.3 · maintenance · verified Wed Apr 22

Tinyreq is a minimalist JavaScript library designed for making HTTP and HTTPS requests, aiming for simplicity and a small footprint. Currently at version 3.4.3, it offers both traditional callback-based and modern Promise-based APIs for handling responses. Its release cadence is generally conservative, with updates focusing on maintenance tasks such as documentation improvements, minor dependency upgrades (e.g., `follow-redirects`), and occasional bug fixes (e.g., addressing Promise handling in 3.2.5). A key differentiating factor is its commitment to being a "tiny" utility, providing core request functionality without the extensive feature sets found in larger HTTP clients, making it suitable for environments where bundle size and minimal dependencies are crucial.

Common errors

```
TypeError: tinyreq is not a function
```
cause Attempting to use `tinyreq` after an incorrect import, likely a named import in ESM or incorrect destructuring in CJS.

fix For CommonJS, use `const tinyreq = require('tinyreq');`. For ESM, use `import tinyreq from 'tinyreq';`.
```
Error: getaddrinfo ENOTFOUND example.com
```
cause The hostname specified in the URL could not be resolved, indicating a DNS issue or incorrect URL.

fix Verify the URL for typos and ensure network connectivity or correct DNS configuration. Try pinging the domain from your environment.
```
TypeError: tinyreq(...).then is not a function
```
cause This usually indicates an older version of `tinyreq` (pre-3.2.5) that did not fully support Promises for response body retrieval, or the function was called without a valid URL/options object preventing a Promise from being returned.

fix Ensure you are using `tinyreq` version 3.2.5 or newer. Also, verify that `tinyreq` is called with a string URL or an object with a `url` property, which should return a Promise when no callback is provided.

Warnings

breaking Prior to version 3.2.5, using `tinyreq` with Promises (via `.then()`) might not correctly store or return the response body unless a callback was also provided. This was a significant bug affecting Promise-based usage.
Fix: Upgrade to `tinyreq` version 3.2.5 or higher to ensure correct Promise behavior for accessing response bodies.
gotcha The library's primary examples and typical usage patterns are geared towards CommonJS (`require`). While it generally interoperates with ESM via default imports, direct ESM module exports or named exports are not explicitly provided, which might require bundler configurations in strict ESM environments.
Fix: Use `import tinyreq from 'tinyreq';` for ESM, and ensure your build setup correctly handles CommonJS modules. Avoid `import { tinyreq } from 'tinyreq';`.
gotcha HTTP status codes indicating errors (e.g., 4xx, 5xx) will typically trigger the `err` parameter in callbacks or the `.catch()` block in Promises, consistent with standard error handling for network requests. However, the exact behavior (e.g., if the response body is still accessible in error cases) depends on the specific error and version.
Fix: Always check both `err` and `body` in callbacks, and utilize `.catch()` for Promise-based requests to handle potential network or server errors gracefully.

Install

npm install tinyreq npm
yarn add tinyreq yarn
pnpm add tinyreq pnpm

Imports

tinyreq
```
const tinyreq = require('tinyreq');
```
This package is primarily designed for CommonJS environments, and `require()` is the canonical import method.
tinyreq
wrong:
```
import { tinyreq } from 'tinyreq';
```
correct:
```
import tinyreq from 'tinyreq';
```
For ESM environments, use a default import. Named imports are not provided, and direct ESM module support might vary based on your bundler's CJS-to-ESM interop.

Quickstart

Demonstrates making basic GET requests using both callback and Promise patterns, and a POST request with data to an external endpoint.

const tinyreq = require("tinyreq");

// Make a basic GET request with a callback
tinyreq("http://example.com/", (err, body) => {
    if (err) {
        console.error("Callback GET error:", err);
        return;
    }
    console.log("Callback GET response body (first 100 chars):");
    console.log(body.substring(0, 100) + '...');
});

// Make a GET request with custom headers using Promises
tinyreq({
    url: "http://example.com/"
  , headers: {
        "User-Agent": "Tinyreq-App/1.0"
    }
}).then(body => {
    console.log("Promise GET response body (first 100 chars):");
    console.log(body.substring(0, 100) + '...');
}).catch(err => {
    console.error("Promise GET error:", err);
});

// Make a POST request with data to a test endpoint
tinyreq({
    url: "https://httpbin.org/post"
  , method: "POST"
  , data: {
        message: "Hello from tinyreq",
        timestamp: new Date().toISOString()
    }
}, (err, body) => {
    if (err) {
        console.error("Callback POST error:", err);
        return;
    }
    console.log("Callback POST response:", JSON.parse(body).json);
});

view raw JSON →