simple-get

4.0.1 · active · verified Wed Apr 22

simple-get is a minimalist HTTP client library for Node.js, providing the simplest way to make HTTP GET requests with essential features like HTTPS support, automatic redirect following, and gzip/deflate decompression. It focuses on being a lightweight wrapper (under 120 lines of code) around Node.js's native `http` and `https` modules, minimizing overhead. The current stable version is 4.0.1. It maintains a stable API, primarily using callback patterns, and is known for its reliability and efficiency in basic request scenarios. Key differentiators include its small footprint and stream-first approach, making it ideal for scenarios where a full-featured HTTP client is overkill, or when composing with other stream-based utilities.

Common errors

```
Error: connect ECONNREFUSED 127.0.0.1:80
```
cause The client failed to connect to the specified host and port, likely because the server is not running or is inaccessible.

fix Verify that the target server is online and listening on the correct IP address and port. Check firewall rules or network connectivity if connecting to a remote host.
```
Error: Request timed out
```
cause The request took longer than the specified `timeout` option to complete, causing `simple-get` to abort the connection.

fix Increase the `timeout` option value in milliseconds to allow more time for the request to complete, or investigate why the server is slow to respond. `get({ url: '...', timeout: 5000 }, callback)`
```
TypeError: Cannot read properties of undefined (reading 'statusCode')
```
cause This typically occurs when the callback function is executed with an `err` object, but the code proceeds to access properties of the `res` (response) object without checking if `res` is undefined or null, which happens on network errors.

fix Always check for an `err` object first in the callback: `get(opts, function (err, res) { if (err) { /* handle error */ return; } console.log(res.statusCode); });`

Warnings

gotcha By default, `simple-get` returns an `IncomingMessage` stream object (res) for GET requests. If you don't consume or pipe this stream, the connection may hang or resources may not be released, especially in long-running applications. The `get.concat` method is provided for convenience to automatically buffer the entire response body.
Fix: Always pipe or consume the `res` stream: `res.pipe(someStream)` or `res.on('data', ...)`, `res.on('end', ...)`. Alternatively, use `get.concat(url, callback)` to buffer the response automatically.
gotcha `simple-get` uses a callback-based API, which can be less ergonomic for modern JavaScript projects that primarily use Promises or `async/await`. While the library itself doesn't provide a Promise-based interface, users often wrap it manually.
Fix: Wrap `simple-get` calls in a Promise. For example: `new Promise((resolve, reject) => get.concat(opts, (err, res, data) => err ? reject(err) : resolve({ res, data })))`.
gotcha The `json: true` option for requests only handles automatic JSON serialization for the request `body` and parsing for the response `data`. It does not set the `Content-Type: application/json` header automatically for requests, which is crucial for many APIs.
Fix: When sending JSON, explicitly set the `Content-Type` header in the `opts` object: `{ headers: { 'Content-Type': 'application/json' }, json: true, body: myObject }`.

Install

npm install simple-get npm
yarn add simple-get yarn
pnpm add simple-get pnpm

Imports

get
wrong:
```
import get from 'simple-get'
```
correct:
```
const get = require('simple-get')
```
simple-get is primarily a CommonJS module. While Node.js's CJS-ESM interoperability allows `import get from 'simple-get'`, the canonical and most reliable way to import it, especially for older Node.js versions or complex module setups, is `require`.
get.concat
wrong:
```
import { concat } from 'simple-get'
```
correct:
```
const get = require('simple-get'); get.concat('http://example.com', cb)
```
The `concat` method is a property of the main `get` function, not a named export. It's used for convenience when buffering the entire response is desired instead of handling a stream.
get.post
wrong:
```
import { post } from 'simple-get'
```
correct:
```
const get = require('simple-get'); get.post(opts, cb)
```
Similar to `concat`, `post` is a method attached to the default exported `get` function. `simple-get` uses this pattern for all HTTP methods beyond GET.

Quickstart

Demonstrates a basic GET request using `get.concat` to fetch and parse JSON data from a public API, including error handling for network issues and non-200 responses.

const get = require('simple-get');

async function fetchData() {
  const url = 'https://jsonplaceholder.typicode.com/posts/1';
  console.log(`Fetching data from: ${url}`);

  return new Promise((resolve, reject) => {
    get.concat(url, function (err, res, data) {
      if (err) {
        console.error('Request failed:', err.message);
        return reject(err);
      }
      if (res.statusCode !== 200) {
        console.error(`Received status code ${res.statusCode}`);
        return reject(new Error(`Server responded with status ${res.statusCode}`));
      }
      try {
        const json = JSON.parse(data.toString());
        console.log('Received data successfully:');
        console.log(json);
        resolve(json);
      } catch (parseErr) {
        console.error('Failed to parse JSON:', parseErr.message);
        reject(parseErr);
      }
    });
  });
}

fetchData().catch(e => console.error('Overall error:', e.message));

view raw JSON →