Decide which bundlers we should support

[david-luna]

The goal of this issue is to produce a list of the JS bundlers (and versions) we have to support.

Current state

At the time of writing this issue the opentelemetry-js core repository has some things in place for bundlers like the browser entry in package.json files and it even added some tests for webpack@5 in open-telemetry/opentelemetry-js#5919

But we are not clear about which ones are supported or not and this leads to issues like open-telemetry/opentelemetry-js#5941 (TL;DR user is is using webpack@4 which does not supports subpaths by default, there is a workaround in open-telemetry/opentelemetry-js#5941 (comment))

Starting point

In last Browser's SIG (2025-10-02) this topic was discussed and decided to 1st list what bundler features we should support and from there extract the list of bundlers and its versions. Let's use the comments to list and discuss such features.

[BenoitZugmeyer]

Here is a first pass to get us started:

Feature	Description / Example	Verdict
exports field	Use of "exports" in package.json, including subpath exports like "./sub": "./dist/sub.mjs"	Required
Conditional exports	"import", "require", "browser" conditions to expose different builds	Not required
module field	ESM entrypoint	Recommended
browser field	Browser friendly entrypoint	Not required
Type field & extensions	type: "module" to identify how to parse modules (ESM/JS)	Not required
Explicit extensions	import "./foo.js" vs relying on extensionless resolution	Not required
Dynamic import()	Lazy loading: await import('./feature.js')	Not required
Top-level await	Await at module scope: const data = await fetch('x')	Not required
import.meta usage	import.meta.url, new URL('./asset.png', import.meta.url)	Not required
process.env usage	process.env.NODE_ENV	Not required
Supported ES syntax	Ability to parse ES2022 syntax	Required
Pure ESM tree shaking	Identify and tree-shake unused module that are side-effect free	Recommended
sideEffects field	Use of "sideEffects": false to mark pure modules	Recommended
PURE annotations	Comments like /*#__PURE__*/	Recommended
JSON modules	import data from './foo.json'	Not required
Workers / URLs	new Worker(new URL('./w.js'))	Not required

Notes:

• Should we support CJS, or can we just use ESM now? I'd say it's probably fine to only support ESM, but at the same time it's not a huge effort to produce CJS

• Should we support server side import (ex: in a SSR context) with node-friendly entrypoint? (main vs browser fields or conditional exports)

• I used a few otel packages as inspiration, but it's also a bit opinionated. Feel free to comment!

[overbalance]

I propose:

1. Ban top-level await, export ESM only, and limit Node to versions capable of handling require(esm): https://nodejs.org/api/modules.html#loading-ecmascript-modules-using-require

"engines": {
  "node": "^20.19.0 || >=22.12.0"
},

require() only supports loading ECMAScript modules that meet the following requirements:
The module is fully synchronous (contains no top-level await); and
One of these conditions are met:
The file has a .mjs extension.
The file has a .js extension, and the closest package.json contains "type": "module"
The file has a .js extension, the closest package.json does not contain "type": "commonjs", and the module contains ES module syntax.
If the ES Module being loaded meets the requirements, require() can load it and return the module namespace object. In this case it is similar to dynamic import() but is run synchronously and returns the name space object directly.

2. exports only. Not main or module or browser. browser in particular has been problematic because it was never clear if you were importing the browser version of a node library, or the CDN browser bundle of that library. main will confuse devs using a tool (e.g. Webpack 4 - see original link in this issue description) that reads main but is unable to read exports which is required for OTel to function. Note that Webpack 4 can still import packages with exports only, they just have to import specifying the relative path to the file.

3. Author ESNext (not ES2022) with the caveat that we only generate and export code that requires no polyfills to be baseline widely available.

Edited: uuid >= 12 is a good example of these rules https://github.com/uuidjs/uuid/blob/main/package.json

[pichlermarc]

export ESM only, and limit Node to versions capable of handling require(esm)

I suppose this proposal is limited to browser-only packages right now - correct? While I'm on board - I think we'd only be able to do this with Node.js and shared packages too in June/July next year with a potential 3.0 release. (we've tried dropping Node.js versions in non major releases before, the backlash was significant).

[overbalance]

Hey @pichlermarc! You're right to call that out, this would be browser-specific packages only.

For our packages, "engines": { "node": "^20.19.0 || >=22.12.0" } only gates development, not consumption, because users import pre-built files that never execute in Node.

I understand the concern about Node version bumps in the main otel-js repo since those packages run in Node at consumer runtime. Interestingly enough, with all the newer tooling (built in Rust, Zig, etc.), some web devs might not even have Node in their workflow.

One more parallel worth noting: for browser packages, the target in tsconfig acts like engines.node does for Node runtime packages.

For example, Webpack 4 (using acorn 6) can only parse up to ES2018/ES2019 syntax, so a package compiled to ES2022 would be incompatible with Webpack 4 users due to features like class properties. This is making me realize we need to add instructions to all the repos saying that if OTel browser packages work in webpack 4, it's because there is no modern code in that package just by happenstance...