You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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`.
250
243
251
-
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`.
244
+
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 as[Jest](https://jestjs.io). The output file should be referenced in the `main` field. If you have a [dual module setup](esm.md#dual-module-setup) with both ESM and CommonJS builds, it needs to be specified in `exports['.'].require` field of `package.json`.
Copy file name to clipboardExpand all lines: docs/pages/esm.md
+91-18Lines changed: 91 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,8 +16,17 @@ You can verify whether ESM support is enabled by checking the configuration for
16
16
}
17
17
```
18
18
19
+
<<<<<<< HEAD
20
+
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.
21
+
||||||| parent of 0330463 (refactor: drop commonjs build from default setup)
22
+
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
23
+
=======
24
+
19
25
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.
20
26
27
+
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.
28
+
>>>>>>> 0330463 (refactor: drop commonjs build from default setup)
29
+
21
30
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.
22
31
23
32
It's recommended to specify `"moduleResolution": "bundler"` in your `tsconfig.json` file to match Metro's behavior:
@@ -35,42 +44,94 @@ Specifying `"moduleResolution": "bundler"` means that you don't need to use file
35
44
To make use of the output files, ensure that your `package.json` file contains the following fields:
The `main` field is for tools that don't support the `exports` field (e.g. [Jest](https://jestjs.io)). The `module` field is a non-standard field that some tools use to determine the ESM entry point.
57
+
The `main` field is for tools that don't support the `exports` field (e.g. [Metro](https://metrobundler.dev/)).
56
58
57
59
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')`).
58
60
59
61
Here, we specify 2 conditions:
60
62
61
-
-`import`: Used when the library is imported with an `import` statement or a dynamic `import()`. It should point to the ESM build.
62
-
-`require`: Used when the library is required with a `require` call. It should point to the CommonJS build.
63
-
64
-
Each condition has 2 fields:
65
-
66
63
-`types`: Used for the TypeScript definitions.
67
64
-`default`: Used for the actual JS code when the library is imported or required.
68
65
69
66
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.
70
67
71
68
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)).
72
69
73
-
> 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.
70
+
## Dual module setup
71
+
72
+
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 module setup.
73
+
74
+
A dual module 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.
75
+
76
+
To set up a dual module setup, you can follow these steps:
77
+
78
+
1. Add the `commonjs` target to the `react-native-builder-bob` field in your `package.json` or `bob.config.js`:
79
+
80
+
```diff
81
+
"react-native-builder-bob": {
82
+
"source": "src",
83
+
"output": "lib",
84
+
"targets": [
85
+
["module", { "esm": true }],
86
+
+ ["commonjs", { "esm": true }]
87
+
"typescript",
88
+
]
89
+
}
90
+
```
91
+
92
+
2. Change the `main` field in your `package.json` to point to the CommonJS build:
93
+
94
+
```diff
95
+
- "main": "./lib/module/index.js",
96
+
+ "main": "./lib/commonjs/index.js",
97
+
```
98
+
99
+
3. Optionally add a `module` field in your `package.json` to point to the ESM build:
100
+
101
+
```diff
102
+
"main": "./lib/commonjs/index.js",
103
+
+ "module": "./lib/module/index.js",
104
+
```
105
+
106
+
The `module` field is a non-standard field that some tools use to determine the ESM entry point.
107
+
108
+
4. Change the `exports` field in your `package.json` to include 2 conditions:
-`import`: Used when the library is imported with an `import` statement or a dynamic `import()`. It will point to the ESM build.
130
+
-`require`: Used when the library is required with a `require` call. It will point to the CommonJS build.
131
+
132
+
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.
133
+
134
+
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.
74
135
75
136
## Guidelines
76
137
@@ -100,7 +161,19 @@ There are still a few things to keep in mind if you want your library to be ESM-
100
161
101
162
- 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.
102
163
- 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.
103
-
- If you specify a `react-native` condition in `exports`, make sure that it comes before the `default` condition. The conditions should be ordered from the most specific to the least specific:
164
+
- If you specify a `react-native` condition in `exports`, make sure that it comes before other conditions. The conditions should be ordered from the most specific to the least specific:
0 commit comments