Node.js HTTP API for Browsers

Common errors

• TypeError: Cannot read properties of undefined (reading 'request')

  cause The `http` object was not correctly imported or `require`d, or it's being used in an environment where it's not available.
  fix Ensure you are using the correct `import` or `require` statement for your module system (e.g., `import http from 'stream-http'` for ESM, `const http = require('stream-http')` for CommonJS).

• XMLHttpRequest cannot load [URL]. No 'Access-Control-Allow-Origin' header is present on the requested resource.

  cause A cross-origin request was blocked by the browser's Same-Origin Policy. The server does not send the necessary CORS headers.
  fix Ensure the server you are requesting from is configured to send `Access-Control-Allow-Origin` headers that permit requests from your domain. For requests that need to send cookies or authentication, set `options.withCredentials = true` in your request configuration.

• Response content-type header is 'text/plain; charset=x-user-defined' when expecting JSON/XML/etc.

  cause The `options.mode` was set to 'allow-wrong-content-type' or 'prefer-streaming', which can override or misreport the actual Content-Type header in some older browsers or specific configurations.
  fix Remove or set `options.mode` to 'default' (or `undefined`) unless you explicitly understand and accept the content-type reporting inaccuracies for streaming benefits. Verify browser compatibility for your chosen `mode`.

Warnings

• breaking As of version 3.0.0, Internet Explorer 10 and below are no longer supported. IE11 support remains but users of older IE versions must stick to stream-http v2 or earlier.
  Fix: Upgrade to a modern browser (IE11+) or use an older version of `stream-http` if IE10- support is critical.
• gotcha Using `options.mode` set to 'allow-wrong-content-type' or 'prefer-streaming' can lead to incorrect 'content-type' response headers (e.g., 'text/plain; charset=x-user-defined') in some browsers, notably Safari and Chrome 42 and older. 'prefer-streaming' can also corrupt binary data.
  Fix: Use the default `options.mode` for general purpose requests, especially with binary data or when accurate Content-Type headers are critical. Only use 'prefer-streaming' for known text data.
• gotcha Due to inherent browser limitations, `stream-http` cannot replicate the Node.js `http` module's API and behavior with 100% fidelity. Specific features like fine-grained control over redirects or certain socket options are unavailable.
  Fix: Review the `stream-http` documentation and browser API capabilities for specific features that might not be fully supported. Adjust application logic to account for browser-specific behaviors like silent redirects.

Install

• npm install stream-http npm
• yarn add stream-http yarn
• pnpm add stream-http pnpm

Imports

• http
  wrong:

  const http = require('stream-http')

  correct:

  import http from 'stream-http'

  For modern module bundlers and ESM environments. This is the recommended way.
• http
  wrong:

  import http from 'stream-http'

  correct:

  const http = require('stream-http')

  CommonJS style, typically used with older bundlers like Browserify or Webpack < 5 without specific ESM configuration.
• METHODS, STATUS_CODES
  wrong:

  import { METHODS, STATUS_CODES } from 'stream-http'

  correct:

  import http from 'stream-http'; const { METHODS, STATUS_CODES } = http;

  METHODS and STATUS_CODES are properties of the default `http` export, not named exports from the module root.

Quickstart

This quickstart demonstrates how to make a GET request using the `http.request` method, similar to Node.js. It shows how to set request options, handle the response stream, and process incoming data chunks until the request ends, including error handling.

import http from 'stream-http';

// Example: Fetch data from a public API
const options = {
  host: 'jsonplaceholder.typicode.com',
  path: '/posts/1',
  method: 'GET'
};

const req = http.request(options, (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);

  let data = '';
  res.on('data', (chunk) => {
    data += chunk;
  });

  res.on('end', () => {
    console.log('No more data in response.');
    try {
      const parsedData = JSON.parse(data);
      console.log('Response body:', parsedData);
    } catch (e) {
      console.error('Failed to parse JSON:', e);
      console.log('Raw response body:', data);
    }
  });
});

req.on('error', (e) => {
  console.error(`problem with request: ${e.message}`);
});

req.end();