docs: improve docs regarding modules

Author: satya164

docs/pages/build.md

@@ -45,10 +45,10 @@ To configure your project manually, follow these steps:
      "source": "src",
      "output": "lib",
      "targets": [
-       ["commonjs", { "esm": true }],
        ["module", { "esm": true }],
+       ["commonjs", { "esm": true }],
        "typescript",
-       "codegen",
+       "codegen"
      ]
    }
    ```
@@ -80,7 +80,6 @@ To configure your project manually, follow these steps:
    "source": "./src/index.tsx",
    "main": "./lib/commonjs/index.js",
    "module": "./lib/module/index.js",
-   "types": "./lib/typescript/commonjs/src/index.d.ts",
    "exports": {
      ".": {
        "import": {
@@ -91,7 +90,8 @@ To configure your project manually, follow these steps:
          "types": "./lib/typescript/commonjs/src/index.d.ts",
          "default": "./lib/commonjs/index.js"
        }
-     }
+     },
+     "./package.json": "./package.json"
    },
    "files": [
      "lib",
@@ -103,15 +103,11 @@ To configure your project manually, follow these steps:
 
    - `source`: The path to the source code. It is used by `react-native-builder-bob` to detect the correct output files and provide better error messages.
    - `main`: The entry point for the CommonJS build. This is used by Node - such as tests, SSR etc.
-   - `module`: The entry point for the ES module build. This is used by bundlers such as webpack.
-   - `types`: The entry point for the TypeScript definitions. This is used by TypeScript to typecheck the code using your library.
    - `files`: The files to include in the package when publishing with `npm`.
-   - `exports`: The entry points for tools that support the `exports` field in `package.json` - such as Node.js 12+ & modern browsers. See [the ESM support guide](./esm.md) for more details.
+   - `exports`: The entry points for tools that support the `exports` field in `package.json` - such as Node.js 12+, modern browsers and tools. See [the ESM support guide](./esm.md) for more details.
 
    Make sure to change specify correct files according to the targets you have enabled.
 
-   > If you're building TypeScript definition files, also make sure that the `types` field points to a correct path. Depending on the project configuration, the path can be different for you than the example snippet (e.g. `lib/typescript/index.d.ts` if you have only the `src` directory and `rootDir` is not set).
-
 5. Add the output directory to `.gitignore` and `.eslintignore`
 
    ```gitignore
@@ -173,13 +169,15 @@ Example:
 
 Various targets to build for. The available targets are:
 
-#### `commonjs`
+#### `module`
+
+Enable compiling source files with Babel and use ES module system (`import`/`export`).
 
-Enable compiling source files with Babel and use CommonJS module system.
+This is useful for modern bundlers that understand ES modules. Bundlers such as [webpack](https://webpack.js.org) can also tree-shake code using ES modules.
 
-This is useful for running the code in Node (SSR, tests etc.). The output file should be referenced in the `main` field and `exports['.'].require` (when `esm: true`) field of `package.json`.
+The output file should be referenced in the `module` field and `exports['.'].import` (when `esm: true`) field of `package.json`.
 
-By default, the code is compiled to support the last 2 versions of modern browsers. It also strips TypeScript and Flow annotations as well as compiles JSX. You can customize the environments to compile for by using a [browserslist config](https://github.com/browserslist/browserslist#config-file).
+By default, the code is compiled to support the last 2 versions of modern browsers. It also strips TypeScript and Flow annotations as well as compiles JSX code. You can customize the environments to compile for by using a [browserslist config](https://github.com/browserslist/browserslist#config-file).
 
 In addition, the following options are supported:
 
@@ -243,19 +241,19 @@ Sourcemaps are generated by default alongside the compiled files. You can disabl
 Example:
 
 ```json
-["commonjs", { "esm": true, "copyFlow": true }]
+["module", { "esm": true }]
 ```
 
-#### `module`
+#### `commonjs`
 
-Enable compiling source files with Babel and use ES module system. This is essentially the same as the `commonjs` target and accepts the same options, but leaves the `import`/`export` statements in your code.
+Enable compiling source files with Babel and use CommonJS module system. This is essentially the same as the `module` target and accepts the same options, but transforms the `import`/`export` statements in your code to `require`/`module.exports`.
 
-This is useful for bundlers that understand ES modules and can tree-shake. The output file should be referenced in the `module` field and `exports['.'].import` (when `esm: true`) field of `package.json`.
+This is useful for supporting usage of this module with `require` in Node versions older than 20 (it can still be used with `import` for Node.js 12+ if `module` target with `esm` is enabled), and some tools such a [Jest](https://jestjs.io). The output file should be referenced in the `main` field. If you have a dual module setup with both ESM and CommonJS builds, it needs to be specified in `exports['.'].require` field of `package.json`.
 
 Example:
 
 ```json
-["module", { "esm": true, "sourceMaps": false }]
+["commonjs", { "sourceMaps": false, "copyFlow": true }]
 ```
 
 #### `typescript`
@@ -282,12 +280,6 @@ Example:
 
 The output file should be referenced in the `types` field or `exports['.'].types` field of `package.json`.
 
-##### `esm`
-
-Setting this option to `true` will output 2 sets of type definitions: one for the CommonJS build and one for the ES module build.
-
-See the [ESM support](./esm.md) guide for more details.
-
 #### `codegen`
 
 Enable generating the [React Native Codegen](https://reactnative.dev/docs/the-new-architecture/what-is-codegen) scaffold code, which is used with the New React Native Architecture.

docs/pages/esm.md

@@ -9,14 +9,16 @@ You can verify whether ESM support is enabled by checking the configuration for
   "source": "src",
   "output": "lib",
   "targets": [
-    ["commonjs", { "esm": true }],
     ["module", { "esm": true }],
+    ["commonjs", { "esm": true }],
     "typescript"
   ]
 }
 ```
 
-The `"esm": true` option enables ESM-compatible output by adding the `.js` extension to the import statements in the generated files. For TypeScript, it also generates 2 sets of type definitions: one for the CommonJS build and one for the ES module build.
+The `"esm": true` option enables ESM-compatible output by adding the `.js` extension to the import statements in the generated files. This is necessary if you want to be able to import the library on Node.js or in a bundler that supports ESM, with some caveats. See the [Guidelines](#guidelines) section for more information.
+
+For TypeScript, it also generates 2 sets of type definitions if the [`commonjs`](build.md#commonjs) target is also enabled: one for the CommonJS build and one for the ES module build.
 
 It's recommended to specify `"moduleResolution": "bundler"` and `"resolvePackageJsonImports": false` in your `tsconfig.json` file to match [Metro's behavior](https://reactnative.dev/blog/2023/06/21/package-exports-support#enabling-package-exports-beta):
 
@@ -36,7 +38,6 @@ To make use of the output files, ensure that your `package.json` file contains t
 ```json
 "main": "./lib/commonjs/index.js",
 "module": "./lib/module/index.js",
-"types": "./lib/typescript/commonjs/src/index.d.ts",
 "exports": {
   ".": {
     "import": {
@@ -47,23 +48,29 @@ To make use of the output files, ensure that your `package.json` file contains t
       "types": "./lib/typescript/commonjs/src/index.d.ts",
       "default": "./lib/commonjs/index.js"
     }
-  }
+  },
+  "./package.json": "./package.json"
 },
 ```
 
-The `main`, `module` and `types` fields are for legacy setups that don't support the `exports` field. See the [Manual configuration](build.md#manual-configuration) guide for more information about those fields.
+The `main` field is for tools that don't support the `exports` field (e.g. [Metro](https://metrobundler.dev/)). The `module` field is a non-standard field that some tools use to determine the ESM entry point.
 
-The `exports` field is used by modern tools and bundlers to determine the correct entry point. Here, we specify 2 conditions:
+The `exports` field is used by Node.js 12+, modern browsers and tools to determine the correct entry point. The entrypoint is specified in the `.` key and will be used when the library is imported or required directly (e.g. `import 'my-library'` or `require('my-library')`).
+
+Here, we specify 2 conditions:
 
 - `import`: Used when the library is imported with an `import` statement or a dynamic `import()`. It should point to the ESM build.
 - `require`: Used when the library is required with a `require` call. It should point to the CommonJS build.
 
-Each condition has a `types` field - necessary for TypeScript to provide the appropriate definitions for the module system. The type definitions have slightly different semantics for CommonJS and ESM, so it's important to specify them separately.
+Each condition has 2 fields:
 
-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.
+- `types`: Used for the TypeScript definitions.
+- `default`: Used for the actual JS code when the library is imported or required.
 
 You can also specify additional conditions for different scenarios, such as `react-native`, `browser`, `production`, `development` etc. Note that support for these conditions depends on the tooling you're using.
 
+The `./package.json` field is used to point to the library's `package.json` file. It's necessary for tools that may need to read the `package.json` file directly (e.g. [React Native Codegen](https://reactnative.dev/docs/the-new-architecture/what-is-codegen)).
+
 ## Guidelines
 
 There are still a few things to keep in mind if you want your library to be ESM-compatible:
@@ -79,6 +86,17 @@ There are still a few things to keep in mind if you want your library to be ESM-
   const { foo } = require('my-library');
   ```
 
+  Alternatively, if you want to be able to use the library in Node.js with `import` syntax, you can use `require` to import code with platform-specific extensions in your library:
+
+  ```js
+  // will import `foo.native.js`, `foo.ios.js`, `foo.js` etc.
+  const { foo } = require('./foo');
+  ```
+
+  Make sure to have a file without any platform-specific extensions that will be loaded by Node.js.
+
+  Also note that if your module (e.g. `foo.js` in this case) contains ESM syntax, it will only work on Node.js 20 or newer.
+
 - Avoid using `.cjs`, `.mjs`, `.cts` or `.mts` extensions. Metro always requires file extensions in import statements when using `.cjs` or `.mjs` which breaks platform-specific extension resolution.
 - Avoid using `"moduleResolution": "node16"` or `"moduleResolution": "nodenext"` in your `tsconfig.json` file. They require file extensions in import statements which breaks platform-specific extension resolution.
 - If you specify a `react-native` condition in `exports`, make sure that it comes before `import` or `require`. The conditions should be ordered from the most specific to the least specific:
@@ -96,6 +114,7 @@ There are still a few things to keep in mind if you want your library to be ESM-
         "react-native": "./lib/commonjs/index.native.js",
         "default": "./lib/commonjs/index.js"
       }
-    }
+    },
+    "./package.json": "./package.json"
   }
   ```

docs/pages/faq.md

@@ -135,7 +135,8 @@ If you have a reason to not ship Codegen generated scaffold code with your libra
    ```diff
    "codegenConfig": {
      // …
-   +   "includesGeneratedCode": false
+   - "includesGeneratedCode": true
+   + "includesGeneratedCode": false
    }
    ```
 
@@ -146,16 +147,18 @@ If you have a reason to not ship Codegen generated scaffold code with your libra
     "output": "lib",
     "targets": [
       // …
-   -   "codegen"
+   -  "codegen"
     ]
    ```
 
 3. If you have an `exports` field in your `package.json`, ensure that it contains `./package.json`:
 
    ```diff
    "exports": {
-     // …
-   +   "./package.json": "./package.json"
+     ".": {
+       // …
+     },
+   + "./package.json": "./package.json"
    },
    ```
 

packages/create-react-native-library/templates/common/$package.json

@@ -205,12 +205,13 @@
       "codegen",
 <% } -%>
       [
-        "commonjs",
+        "module",
         {
           "esm": true
         }
       ],
-      ["module",
+      [
+        "commonjs",
         {
           "esm": true
         }