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
242
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`.
243
+
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`.
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.
48
+
The `main` field is for tools that don't support the `exports` field (e.g. [Metro](https://metrobundler.dev/)).
57
49
58
50
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')`).
59
51
60
52
Here, we specify 2 conditions:
61
53
62
-
-`import`: Used when the library is imported with an `import` statement or a dynamic `import()`. It should point to the ESM build.
63
-
-`require`: Used when the library is required with a `require` call. It should point to the CommonJS build.
64
-
65
-
Each condition has 2 fields:
66
-
67
54
-`types`: Used for the TypeScript definitions.
68
55
-`default`: Used for the actual JS code when the library is imported or required.
69
56
70
57
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.
71
58
72
59
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)).
73
60
61
+
## Dual module setup
62
+
63
+
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.
64
+
65
+
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.
66
+
67
+
To set up a dual module setup, you can follow these steps:
68
+
69
+
1. Add the `commonjs` target to the `react-native-builder-bob` field in your `package.json` or `bob.config.js`:
70
+
71
+
```diff
72
+
"react-native-builder-bob": {
73
+
"source": "src",
74
+
"output": "lib",
75
+
"targets": [
76
+
["module", { "esm": true }],
77
+
+ ["commonjs", { "esm": true }]
78
+
"typescript",
79
+
]
80
+
}
81
+
```
82
+
83
+
2. Change the `main` field in your `package.json` to point to the CommonJS build:
84
+
85
+
```diff
86
+
- "main": "./lib/module/index.js",
87
+
+ "main": "./lib/commonjs/index.js",
88
+
```
89
+
90
+
3. Optionally add a `module` field in your `package.json` to point to the ESM build:
91
+
92
+
```diff
93
+
"main": "./lib/commonjs/index.js",
94
+
+ "module": "./lib/module/index.js",
95
+
```
96
+
97
+
The `module` field is a non-standard field that some tools use to determine the ESM entry point.
98
+
99
+
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.
121
+
-`require`: Used when the library is required with a `require` call. It will point to the CommonJS build.
122
+
123
+
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.
124
+
125
+
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.
126
+
74
127
## Guidelines
75
128
76
129
There are still a few things to keep in mind if you want your library to be ESM-compatible:
@@ -99,7 +152,19 @@ There are still a few things to keep in mind if you want your library to be ESM-
99
152
100
153
- 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.
101
154
- 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.
102
-
- 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:
155
+
- 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