refactor!: convert to native ESM (#1015)

Mirrors
[apify/crawlee@cc01b18](apify/crawlee@cc01b18)
and
[apify/apify-sdk-js@a381728](apify/apify-sdk-js@a381728),
which did the same for Crawlee v4 and for the SDK on its `v4` branch.

## What changed

- `"type": "module"`, and the dual CJS+ESM build is gone: no more
`dist/index.mjs`, no `gen-esm-wrapper` postbuild step, and the
`import`/`require` export conditions collapse into `types` + `browser` +
`default`.
- Every relative import in `src/` and `test/` gets its `.js` extension,
which is the bulk of the diff. It follows from `"type": "module"` alone:
the files now emit as ESM, and ESM has no extension guessing or
directory-index lookup. `tsc` never rewrites specifiers, so dropping
them type-checks clean and then fails at runtime with
`ERR_MODULE_NOT_FOUND`. crawlee v4 and apify-sdk-js `v4` do the same.
- `require('../package.json')` in `getVersionData()` becomes a JSON
import attribute, with `resolveJsonModule` off so the emit doesn't sink
into `dist/src`.
- `__dirname` becomes `import.meta.dirname` in the test helpers and the
Vitest config.
- tsconfig pins `module`/`moduleResolution` to `NodeNext` and `target`
to `ESNext`, matching crawlee v4 and the SDK.
- `test/tsconfig.json` maps `apify-client` to `../src/index.ts` rather
than the `../src` directory. `nodenext` has no directory-index lookup,
so the directory form type-checked the tests against `dist`.

## The browser bundle is now an ES module

`dist/bundle.js` keeps its name and path, but rsbuild now emits it as an
ES module with named exports instead of UMD. The `Apify` global is gone:
load it with `<script type="module">` and `import { ApifyClient } from
'.../bundle.js'`. Under `"type": "module"` Node parses a `.js` file as
ESM anyway, and the UMD file in that spot broke `pnpm test:bundling` on
all four bundlers. The `apify-client/browser` subpath is unchanged.

## Breaking change

The client is pure ESM and ships no CommonJS build.
`require('apify-client')` still resolves on Node.js 22.12 and newer,
which loads an ES module through `require()` directly. Anywhere else,
CommonJS consumers have to switch to `import` or a dynamic `import()`.
Documented in the v3 upgrading guide, along with the bundle format
change.

*✍️ Drafted by Claude Code*

---------

Co-authored-by: Martin Adámek <banan23@gmail.com>

Author: vdusek

.github/scripts/before-beta-release.js

@@ -1,12 +1,11 @@
 /* eslint-disable no-console */
-const { execSync } = require('node:child_process');
-const fs = require('node:fs');
-const path = require('node:path');
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 
-const PKG_JSON_PATH = path.join(__dirname, '..', '..', 'package.json');
+const PKG_JSON_PATH = path.join(import.meta.dirname, '..', '..', 'package.json');
 
-// eslint-disable-next-line import/no-dynamic-require
-const pkgJson = require(PKG_JSON_PATH);
+const pkgJson = JSON.parse(fs.readFileSync(PKG_JSON_PATH, 'utf8'));
 
 const PACKAGE_NAME = pkgJson.name;
 

CONTRIBUTING.md

@@ -100,7 +100,7 @@ scripts/
 # Build
 pnpm build                 # Full build (Node + browser bundle)
 pnpm build:node            # TypeScript compilation only
-pnpm build:browser         # RSBuild browser/UMD bundle
+pnpm build:browser         # RSBuild browser bundle (ESM)
 pnpm clean                 # Remove dist directory
 
 # Testing
@@ -123,12 +123,11 @@ pnpm format:check          # oxfmt check
 
 ### Build Output
 
-The build produces multiple formats:
+The build produces:
 
-- CommonJS: `dist/index.js`
-- ES Module: `dist/index.mjs`
+- ES module: `dist/index.js`
 - TypeScript definitions: `dist/index.d.ts`
-- Browser bundle (UMD): `dist/bundle.js`
+- Browser bundle (ESM): `dist/bundle.js`
 
 ## Code Style
 

README.md

@@ -26,7 +26,7 @@ automatic retries and convenience functions that improve the experience of using
 ## Quick Start
 
 ```js
-const { ApifyClient } = require('apify-client');
+import { ApifyClient } from 'apify-client';
 
 const client = new ApifyClient({
     token: 'MY-APIFY-TOKEN',
@@ -72,7 +72,7 @@ resources are created. There are two types of those clients. A client for manage
 resource and a client for a collection of resources.
 
 ```js
-const { ApifyClient } = require('apify-client');
+import { ApifyClient } from 'apify-client';
 const apifyClient = new ApifyClient({ token: 'my-token' });
 
 // Collection clients do not require a parameter.

docs/04_upgrading/upgrading_v3.md

@@ -9,6 +9,19 @@ import ApiLink from '@theme/ApiLink';
 
 This page summarizes the breaking changes when upgrading from v2 to v3 of `apify-client`.
 
+## The package is now pure ESM
+
+`apify-client` ships as an ES module. The CommonJS build is gone, along with the `dist/index.mjs` wrapper and the `require` condition in `exports`, so `import` is the supported way to load the client.
+
+```diff
+- const { ApifyClient } = require('apify-client'); // v2
++ import { ApifyClient } from 'apify-client';      // v3
+```
+
+A CommonJS project can keep calling `require('apify-client')`: the client has no top-level `await`, and Node.js 22.12 and newer load an ES module through `require()` directly. On Node.js 22.0 to 22.11, `require()` of an ES module is still behind the `--experimental-require-module` flag, so use `import` there.
+
+The browser bundle at `dist/bundle.js` is now an ES module instead of UMD, so it no longer defines an `Apify` global. Importing it, whether through a bundler or the `apify-client/browser` subpath, is unchanged. A classic `<script>` tag that read `Apify.ApifyClient` off the global has to become a `<script type="module">` that imports it instead. For details, see [Bundled environments](../02_concepts/05_bundled-environments.md).
+
 ## Argument validation switched from `ow` to `zod`
 
 The client now validates the arguments you pass with [zod](https://zod.dev) instead of `ow`. This changes what gets thrown for invalid arguments, and tightens a few gaps `ow` used to let through silently.

package.json

@@ -5,19 +5,18 @@
     "engines": {
         "node": ">=22.0.0"
     },
+    "type": "module",
     "main": "dist/index.js",
-    "module": "dist/index.mjs",
     "types": "dist/index.d.ts",
     "browser": "dist/bundle.js",
     "unpkg": "dist/bundle.js",
     "exports": {
         "./package.json": "./package.json",
         "./browser": "./dist/bundle.js",
         ".": {
-            "import": "./dist/index.mjs",
-            "require": "./dist/index.js",
             "types": "./dist/index.d.ts",
-            "browser": "./dist/bundle.js"
+            "browser": "./dist/bundle.js",
+            "default": "./dist/index.js"
         }
     },
     "keywords": [
@@ -54,7 +53,6 @@
     ],
     "scripts": {
         "build": "pnpm clean && pnpm build:node && pnpm build:browser",
-        "postbuild": "gen-esm-wrapper dist/index.js dist/index.mjs",
         "prepublishOnly": "(test $CI || (echo \"Publishing is reserved to CI!\"; exit 1))",
         "clean": "rimraf dist tsconfig.tsbuildinfo",
         "test": "pnpm build && vitest run --project unit",
@@ -111,7 +109,6 @@
         "compression": "^1.7.4",
         "esbuild": "0.28.2",
         "express": "^5.0.0",
-        "gen-esm-wrapper": "^1.1.2",
         "openapi-typescript": "7.13.0",
         "oxfmt": "0.65.0",
         "oxlint": "1.79.0",

pnpm-lock.yaml

@@ -49,13 +49,14 @@ export default defineConfig({
         rspack(config) {
             config.output = {
                 ...config.output,
-                library: {
-                    type: 'umd', // or 'umd', 'commonjs', etc.
-                    name: 'Apify',
-                },
-                globalObject: 'globalThis',
+                module: true,
+                library: { type: 'module' },
                 asyncChunks: false,
             };
+            config.experiments = {
+                ...config.experiments,
+                outputModule: true,
+            };
             config.optimization = {
                 ...config.optimization,
                 splitChunks: false,

rsbuild.config.ts

@@ -1,7 +1,7 @@
 import type { AxiosResponse } from 'axios';
 
-import { isomorphicBufferToString } from './body_parser';
-import { isBuffer } from './utils';
+import { isomorphicBufferToString } from './body_parser.js';
+import { isBuffer } from './utils.js';
 
 /**
  * Examples of capturing groups for "...at ActorCollectionClient._list (/Users/..."

src/apify_api_error.ts

@@ -5,34 +5,34 @@ import { ACTOR_ENV_VARS, ME_USER_NAME_PLACEHOLDER } from '@apify/consts';
 import type { Log } from '@apify/log';
 import logger from '@apify/log';
 
-import { HttpClient } from './http_client';
-import type { RequestInterceptorFunction } from './interceptors';
-import { ActorClient } from './resource_clients/actor';
-import { ActorCollectionClient } from './resource_clients/actor_collection';
-import { BuildClient } from './resource_clients/build';
-import { BuildCollectionClient } from './resource_clients/build_collection';
-import { DatasetClient } from './resource_clients/dataset';
-import { DatasetCollectionClient } from './resource_clients/dataset_collection';
-import { KeyValueStoreClient } from './resource_clients/key_value_store';
-import { KeyValueStoreCollectionClient } from './resource_clients/key_value_store_collection';
-import { LogClient } from './resource_clients/log';
-import type { RequestQueueUserOptions } from './resource_clients/request_queue';
-import { RequestQueueClient } from './resource_clients/request_queue';
-import { RequestQueueCollectionClient } from './resource_clients/request_queue_collection';
-import { RunClient } from './resource_clients/run';
-import { RunCollectionClient } from './resource_clients/run_collection';
-import { ScheduleClient } from './resource_clients/schedule';
-import { ScheduleCollectionClient } from './resource_clients/schedule_collection';
-import { StoreCollectionClient } from './resource_clients/store_collection';
-import { TaskClient } from './resource_clients/task';
-import { TaskCollectionClient } from './resource_clients/task_collection';
-import { UserClient } from './resource_clients/user';
-import { WebhookClient } from './resource_clients/webhook';
-import { WebhookCollectionClient } from './resource_clients/webhook_collection';
-import { WebhookDispatchClient } from './resource_clients/webhook_dispatch';
-import { WebhookDispatchCollectionClient } from './resource_clients/webhook_dispatch_collection';
-import { Statistics } from './statistics';
-import { parseArgument } from './utils';
+import { HttpClient } from './http_client.js';
+import type { RequestInterceptorFunction } from './interceptors.js';
+import { ActorClient } from './resource_clients/actor.js';
+import { ActorCollectionClient } from './resource_clients/actor_collection.js';
+import { BuildClient } from './resource_clients/build.js';
+import { BuildCollectionClient } from './resource_clients/build_collection.js';
+import { DatasetClient } from './resource_clients/dataset.js';
+import { DatasetCollectionClient } from './resource_clients/dataset_collection.js';
+import { KeyValueStoreClient } from './resource_clients/key_value_store.js';
+import { KeyValueStoreCollectionClient } from './resource_clients/key_value_store_collection.js';
+import { LogClient } from './resource_clients/log.js';
+import type { RequestQueueUserOptions } from './resource_clients/request_queue.js';
+import { RequestQueueClient } from './resource_clients/request_queue.js';
+import { RequestQueueCollectionClient } from './resource_clients/request_queue_collection.js';
+import { RunClient } from './resource_clients/run.js';
+import { RunCollectionClient } from './resource_clients/run_collection.js';
+import { ScheduleClient } from './resource_clients/schedule.js';
+import { ScheduleCollectionClient } from './resource_clients/schedule_collection.js';
+import { StoreCollectionClient } from './resource_clients/store_collection.js';
+import { TaskClient } from './resource_clients/task.js';
+import { TaskCollectionClient } from './resource_clients/task_collection.js';
+import { UserClient } from './resource_clients/user.js';
+import { WebhookClient } from './resource_clients/webhook.js';
+import { WebhookCollectionClient } from './resource_clients/webhook_collection.js';
+import { WebhookDispatchClient } from './resource_clients/webhook_dispatch.js';
+import { WebhookDispatchCollectionClient } from './resource_clients/webhook_dispatch_collection.js';
+import { Statistics } from './statistics.js';
+import { parseArgument } from './utils.js';
 
 const DEFAULT_TIMEOUT_SECS = 360;
 

src/apify_client.ts

@@ -1,7 +1,7 @@
-import type { ApifyClient } from '../apify_client';
-import type { HttpClient } from '../http_client';
-import type { PaginatedResponse, PaginationOptions } from '../utils';
-import { toPath, toPathSegment } from '../utils';
+import type { ApifyClient } from '../apify_client.js';
+import type { HttpClient } from '../http_client.js';
+import type { PaginatedResponse, PaginationOptions } from '../utils.js';
+import { toPath, toPathSegment } from '../utils.js';
 
 /** @private */
 export interface ApiClientOptions {