Skip to content

doc: endorse "worker" and "dom" conditions

Rodrigo Muino Tomonari requested to merge github/fork/wooorm/worker into master

This adds two new conditions to the endorsed conditions list in the Node.js documentation.

Their goal is to be more specific that the browser condition (and its predecessor, the browser field), around DOM APIs, specifically for web workers and non-web-workers.

The problem this solves is that most bundlers have a switch that is either browser or node, but this switch is not specific enough for web workers (or their alternative, “normal” web scripts/modules), which don’t have access to most importantly the DOM, but don’t have access to Node modules such as path or crypto or you name it. Folks (or tooling), typically pick the browser condition for web workers, but I as a package maintainer use browser to choose code that uses DOM APIs *(which is explicitly mentioned as a valid use case by the browser field spec).

A practical example is: https://github.com/wooorm/parse-entities/blob/6d7cef95baa04c3430f929cb017b541f54b9e863/package.json#L28-L40, although there isn’t a worker field, so that isn’t supported there. But what it does is: Use the full package by default, switch to the DOM version (which is very small because it uses DOM APIs) in browsers, and switch back to the default in places that don’t have a DOM (react-native, which is currently mentioned on the latest website but not in this file I changed).

This is why I propose a worker condition, which is already supported in webpack. But also it’s inverse (dom), because I think similar to dev/prod, it makes sense to have both.

Currently, webpack supports worker, and esbuild and rollup don’t (but then again webpack does workers out of the box and the rest allows arbitrary conditions). dom is a name I made up myself.

Here are links to the relevant code in what I believe are the primary bundlers for the web and where they handle conditions:

Qs:

  • worker has support in webpack, but on the other hand, it seems similar to the react-native field that is currently on the website but no longer in the source files, in that it means “no dom”. Open to alternatives
  • dom has no existing support, but i think it makes sense to provide an antonym to worker, because otherwise I as a package maintainer have to list all the platforms that have no DOM (worker, react-native, etc)

/cc @guybedford @defunctzombie @alexander-akait Related-to: GH-40708 (in that this is my first PR to Node and I modelled it after a similar PR)

Can someone ping @nodejs/modules I guess?

Merge request reports