Skip to content

Commit 892ba78

Browse files
committed
docs: add a note about dual module hazard
1 parent 52a04c3 commit 892ba78

File tree

1 file changed

+2
-0
lines changed

1 file changed

+2
-0
lines changed

docs/pages/esm.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,8 @@ To set up a dual module setup, you can follow these steps:
126126

127127
The `default` field is the fallback entry point for both conditions. It's used for the actual JS code when the library is imported or required.
128128

129+
> **Important:** With this approach, the ESM and CommonJS versions of the package are treated as separate modules by Node.js as they are different files, leading to [potential issues](https://nodejs.org/docs/latest-v19.x/api/packages.html#dual-package-hazard) if the package is both imported and required in the same runtime environment. If the package relies on any state that can cause issues if 2 separate instances are loaded, it's necessary to isolate the state into a separate CommonJS module that can be shared between the ESM and CommonJS builds.
130+
129131
## Guidelines
130132

131133
There are still a few things to keep in mind if you want your library to be ESM-compatible:

0 commit comments

Comments
 (0)