From caff2dc728f615fe79b0a543910ad8ff41c63dcc Mon Sep 17 00:00:00 2001 From: Neal Beeken Date: Wed, 13 Nov 2024 11:11:10 -0500 Subject: [PATCH 1/2] chore: update migration guide TLA --- docs/upgrade-to-v5.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/upgrade-to-v5.md b/docs/upgrade-to-v5.md index 1ec6ee3c..7db8640a 100644 --- a/docs/upgrade-to-v5.md +++ b/docs/upgrade-to-v5.md @@ -66,6 +66,17 @@ bin.value(true).toString('utf16le'); new TextDecoder('utf-16le').decode(bin.value(true)); ``` +### Bundling Top-Level Await in BSON + +The `"export"` conditions in [package.json](../package.json) make it possible for the `bson` package to provide module resolutions for ES Module and CommonJS. +When using a bundler and targeting the browser the export condition `"browser"` will likely point your bundler at the bson.mjs file, an ES Module. +This ES Module form of `BSON` works in both Node.js and browser environments, however, one sticking point is often bundlers do not by default enable support of top-level await usage. + +For example, you may need to: +- enable Webpack's [`topLevelAwait`](https://webpack.js.org/configuration/experiments/#experimentstoplevelawait) setting to bypass the issue. +- override the [resolution](https://webpack.js.org/configuration/resolve/#resolve) of `bson` to use the CommonJS module, "bson.cjs". +- `require('bson')` instead of using `import`. + ## Other Changes ### TS "target" set to es2020 From 2c4aab9258dad6399b17b36646350b7b95835c95 Mon Sep 17 00:00:00 2001 From: Neal Beeken Date: Wed, 13 Nov 2024 13:59:34 -0500 Subject: [PATCH 2/2] chore: comments Co-authored-by: Warren James --- docs/upgrade-to-v5.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/upgrade-to-v5.md b/docs/upgrade-to-v5.md index 7db8640a..0d6a18a5 100644 --- a/docs/upgrade-to-v5.md +++ b/docs/upgrade-to-v5.md @@ -70,9 +70,9 @@ new TextDecoder('utf-16le').decode(bin.value(true)); The `"export"` conditions in [package.json](../package.json) make it possible for the `bson` package to provide module resolutions for ES Module and CommonJS. When using a bundler and targeting the browser the export condition `"browser"` will likely point your bundler at the bson.mjs file, an ES Module. -This ES Module form of `BSON` works in both Node.js and browser environments, however, one sticking point is often bundlers do not by default enable support of top-level await usage. +This ES Module form of `BSON` works in both Node.js and browser environments, however, one sticking point is that bundlers often do not enable support of top-level await usage by default. -For example, you may need to: +For example, when using Webpack you may need to: - enable Webpack's [`topLevelAwait`](https://webpack.js.org/configuration/experiments/#experimentstoplevelawait) setting to bypass the issue. - override the [resolution](https://webpack.js.org/configuration/resolve/#resolve) of `bson` to use the CommonJS module, "bson.cjs". - `require('bson')` instead of using `import`.