Got CommonJS Wrapper

12.5.4 · maintenance · verified Wed Apr 22

got-cjs is a utility package maintained by Apify, specifically designed to provide a CommonJS-compatible interface for the popular `got` HTTP client library in Node.js. It currently wraps `got` version 11.8.3, which was the last major version of `got` to fully support CommonJS modules. This package serves as a crucial bridge for projects that are still using CommonJS and cannot easily migrate to ECMAScript Modules (ESM), as the main `got` package transitioned to being ESM-only from version 12 onwards. got-cjs ensures that CJS-based applications can continue to leverage `got`'s robust feature set, including its Promise API, stream API, retries, and advanced error handling, without requiring a full module system migration. Its release cadence is likely tied to the maintenance and security updates of its underlying `got` v11 dependency. Its key differentiator is enabling `got`'s v11 API for CommonJS environments.

Common errors

```
ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/got/dist/source/index.js
```
cause Attempting to `require('got')` (the main `got` package) in a CommonJS environment when `got` version 12 or newer is installed.

fix Install `got-cjs` and change your import to `const got = require('got-cjs');`.
```
TypeError: got is not a function
```
cause This error can occur if you mistakenly try to use `require('got')` with `got` v12+ in a CJS file and then try to call it. While the `require` might partially work for an ESM module, the default export is not directly callable as a function in the CJS `require` context without specific interop.

fix If your project is CommonJS, use `const got = require('got-cjs');`. If your project is ESM, use `import got from 'got';`.

Warnings

breaking The primary `got` package (v12 and newer) is pure ESM and cannot be directly `require()`d. `got-cjs` specifically provides a CommonJS wrapper for `got` v11, which means it will not receive new features or API changes from `got` v12+.
Fix: For CommonJS projects, continue using `got-cjs`. For new projects or existing projects able to migrate, consider migrating to ESM and using `got` v12+ directly via `import` statements.
gotcha `got-cjs` bundles `got` v11.8.3. This means that any new features, performance improvements, or non-security bug fixes introduced in `got` v12 or later will not be available when using `got-cjs`. Only security patches for `got` v11 will likely be backported.
Fix: Review the changelogs for the main `got` package. If crucial new features or fixes are needed, migrating your project to ESM to use `got` v12+ is recommended.
gotcha While `got-cjs` enables CommonJS usage, the Node.js ecosystem is increasingly standardizing on ECMAScript Modules (ESM). Relying heavily on CJS wrappers might limit access to newer libraries or features in the long term.
Fix: Evaluate your project's module system. If feasible, migrate to ESM to leverage the broader modern JavaScript ecosystem and directly use `got` v12+.

Install

npm install got-cjs npm
yarn add got-cjs yarn
pnpm add got-cjs pnpm

Imports

got
wrong:
```
import got from 'got-cjs';
```
correct:
```
const got = require('got-cjs');
```
This package is explicitly for CommonJS environments. For ESM, use the main 'got' package directly.

got

wrong:

import { got } from 'got-cjs';

correct:

const got = require('got-cjs');
const { URLSearchParams } = require('url'); // Example for a common Node.js global

The primary export is a default `got` instance; named exports are not typical for this CJS wrapper.

GotReturn
wrong:
```
type GotReturn = ReturnType<typeof require('got-cjs')>;
```
correct:
```
import type { GotReturn } from 'got-cjs';
```
TypeScript types are provided and should be imported using standard ESM `import type` syntax, even in a CJS project if using TS.

Quickstart

Demonstrates a basic GET request with headers and timeout, followed by a JSON POST request, using the `got-cjs` API.

const got = require('got-cjs');

(async () => {
  try {
    const response = await got('https://httpbin.org/get', {
      headers: {
        'User-Agent': 'my-awesome-app/1.0'
      },
      timeout: {
        request: 5000 // 5 seconds
      }
    });
    console.log('Status Code:', response.statusCode);
    console.log('Body:', response.body.substring(0, 200) + '...');

    const postResponse = await got.post('https://httpbin.org/post', {
      json: {
        hello: 'world'
      },
      responseType: 'json'
    });
    console.log('Posted JSON:', postResponse.body);
  } catch (error) {
    console.error('Request failed:', error.message);
  }
})();

view raw JSON →