docs: add an alternative approach for ESM

Author: satya164

docs/pages/build.md

@@ -271,7 +271,9 @@ Example:
 ["typescript", { "project": "tsconfig.build.json" }]
 ```
 
-The output file should be referenced in the `types` field or `exports['.'].types` field of `package.json`.
+The output file should be referenced in the `exports['.'].types` field of `package.json`.
+
+If you need to support legacy setups that use `moduleResolution: node10` or `moduleResolution: node`, you can also add a `types` field to the `package.json` file that points to the output file.
 
 #### `codegen`
 

docs/pages/esm.md

@@ -60,9 +60,11 @@ The `./package.json` field is used to point to the library's `package.json` file
 
 > Note: Metro enables support for `package.json` exports by default from version [0.82.0](https://github.com/facebook/metro/releases/tag/v0.82.0). In previous versions, experimental support can be enabled by setting the `unstable_enablePackageExports` option to `true` in the [Metro configuration](https://metrobundler.dev/docs/configuration/). If this is not enabled, Metro will use the entrypoint specified in the `main` field.
 
-## Dual package setup
+## Legacy environments
 
-The previously mentioned setup only works with tools that support ES modules. If you want to support tools that don't support ESM and use the CommonJS module system, you can set up a dual package setup.
+The previously mentioned setup only works with tools that support ES modules. If you want to support tools that don't support ESM and use the CommonJS module system, there are a few approaches you can take.
+
+### Dual package setup
 
 A dual package setup means that you have 2 builds of your library: one for ESM and one for CommonJS. The ESM build is used by tools that support ES modules, while the CommonJS build is used by tools that don't support ES modules.
 
@@ -161,7 +163,70 @@ Putting it all together, the fields in your `package.json` file should look like
 }
 ```
 
-> **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.
+#### Dual package hazard
+
+With this approach, the ESM and CommonJS versions of the package are treated as separate modules by Node.js as they are different files. On Node.js, `import` will load the ESM package and `require` will load the CommonJS package, 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 library relies on any state that can cause issues if 2 separate instances are loaded (e.g. global state, react context etc.), it's necessary to isolate the state into a separate CommonJS module that can be shared between the ESM and CommonJS builds.
+
+### CommonJS-first setup
+
+The simplest way to avoid dual package hazard is to use a CommonJS-first setup.
+
+With this approach, Node.js will always use the CommonJS build - so two versions of the same package won't be loaded, while the ESM build can optionally be used by some tools such as bundlers (e.g. [Webpack](https://webpack.js.org/) and [Rollup](https://rollupjs.org/)) that use the ESM build for tree-shaking).
+
+To configure a CommonJS-first setup, you can follow these steps:
+
+1. Add the `commonjs` target to the `react-native-builder-bob` field in your `package.json` or `bob.config.js`:
+
+   ```diff
+   "react-native-builder-bob": {
+     "source": "src",
+     "output": "lib",
+     "targets": [
+       ["module", { "esm": true }],
+   +   "commonjs",
+       "typescript",
+     ]
+   }
+   ```
+
+   Optionally, remove the `module` target if you don't need the ESM build at all.
+
+2. Change the `main` and `default` fields to point the CommonJS build instead:
+
+   ```diff
+   - "main": "./lib/module/index.js",
+   + "main": "./lib/commonjs/index.js",
+     "exports": {
+       ".": {
+         "types": "./lib/typescript/src/index.d.ts",
+   -     "default": "./lib/module/index.js"
+   +     "default": "./lib/commonjs/index.js"
+       },
+       "./package.json": "./package.json"
+     },
+   ```
+
+   Here, tools that support the `exports` field will use the CommonJS build when importing or requiring the library, while tools that don't support the `exports` field will fall back to the `main` field.
+
+   Optionally, you can add a `module` field under `exports` to point to the ESM build for bundlers:
+
+   ```diff
+     "main": "./lib/commonjs/index.js",
+     "exports": {
+       ".": {
+         "types": "./lib/typescript/src/index.d.ts",
+   +     "module": "./lib/module/index.js"
+         "default": "./lib/commonjs/index.js"
+       },
+       "./package.json": "./package.json"
+     },
+   ```
+
+   Note that [Metro](https://metrobundler.dev) doesn't support the `module` field. So it will always use the CommonJS build.
+
+Alternatively, you can drop the `exports` field altogether and use the `main` field to point to the CommonJS build and `module` field to point to the ESM build. However, you will lose the benefits of the `exports` field, such as restricted access to the package's internals and [conditional exports](https://nodejs.org/api/packages.html#conditional-exports).
 
 ## Guidelines