Add an ES module build for browsers

CHANGELOG.md

@@ -17,6 +17,17 @@
   browser bundles. In a browser, `td.replaceEsm()` now throws a clear
   "only supported under Node.js" error, and `td.listReplacedModules()` returns
   `[]` [#531](https://github.com/testdouble/testdouble.js/issues/531)
+* Add an ES module build for browsers, so `import * as td from 'testdouble'`
+  works in tools that load native ES modules, like @web/test-runner. Tools that
+  resolve with the `browser` export condition get `dist/testdouble.mjs`. Webpack,
+  Vite and esbuild apply it when targeting the browser; @web/test-runner needs
+  `nodeResolve: { exportConditions: ['browser', 'development'] }` in its config.
+  `testdouble/dist/testdouble.js` can be imported by path again
+  [#494](https://github.com/testdouble/testdouble.js/issues/494)
+* **Behavior change:** any `import` of testdouble resolved with the `browser`
+  condition now gets the browser build, which can't replace modules. That
+  includes Jest's jsdom environment with `--experimental-vm-modules`, and Node
+  run with `--conditions=browser`. `require('testdouble')` is unaffected
 
 ## 3.23.0
 

docs/1-installation.md

@@ -41,9 +41,32 @@ $ npm install --save-dev testdouble
 And then find the browser distribution of the library in
 `node_modules/testdouble/dist/testdouble.js`.
 
-testdouble.js can also be bundled for the browser with webpack 5 and other
-bundlers. Module replacement with `td.replace(path)` and `td.replaceEsm()` is
-only supported under Node.js.
+#### As an ES module
+
+You can also `import * as td from 'testdouble'` in browser tests. Tools that
+resolve packages with the `browser` export condition get a self-contained ES
+module build of the library, `testdouble/dist/testdouble.mjs`. That build
+doesn't set a `td` global.
+
+Bundlers that target the browser apply the `browser` condition already, so
+they need no setup. That includes webpack 5 (`target: 'web'`), Vite and
+esbuild (`--platform=browser`).
+
+[@web/test-runner](https://modern-web.dev/docs/test-runner/overview/) and
+@web/dev-server don't apply it by default. Turn it on in your config file:
+
+```js
+// web-test-runner.config.mjs
+export default {
+  nodeResolve: {
+    exportConditions: ['browser', 'development']
+  }
+}
+```
+
+Module replacement with `td.replace(path)` and `td.replaceEsm()` is only
+supported under Node.js, so the browser build throws an error if you call them.
+`td.replace(object, property)` works everywhere.
 
 #### via unpkg
 

examples/web-test-runner/.gitignore

@@ -0,0 +1 @@
+/node_modules/*