feat: add ESM support for generated project (#583)

This adds ESM support to the generated project. To do this:

- Use `.cjs` and `.mjs` file extensions for the generated files
- Add file extensions to imports in the compiled code
- Add the `exports` field in `package.json`
- Update the `moduleResolution` config to `Bundler` in `tsconfig.json`

In addition:

- Enable the new JSX runtime option for React
- Recommend removing the `react-native` field from `package.json`

This is a breaking change for library authors. After upgrading, it's
necessary to update the configuration by running the following command:

```sh
yarn bob init
```

Alternatively, they can follow the [manual configuration
guide](https://callstack.github.io/react-native-builder-bob/build#manual-configuration).

In addition, typescript consumers would need to change the following
fields in `tsconfig.json`:

```json
"jsx": "react-jsx",
"moduleResolution": "Bundler",
```

If using ESLint, it may also be necessary to disable the
"react/react-in-jsx-scope" rule:

```json
"react/react-in-jsx-scope": "off"
```

Author: satya164

docs/pages/build.md

@@ -42,8 +42,8 @@ yarn add --dev react-native-builder-bob
      "source": "src",
      "output": "lib",
      "targets": [
-       "commonjs",
-       "module",
+       ["commonjs", { "esm" : true }],
+       ["module", { "esm" : true }],
        "typescript",
      ]
    }
@@ -73,10 +73,17 @@ yarn add --dev react-native-builder-bob
 1. Configure the appropriate entry points:
 
    ```json
-   "main": "lib/commonjs/index.js",
-   "module": "lib/module/index.js",
-   "types": "lib/typescript/src/index.d.ts",
-   "source": "src/index.ts",
+   "source": "./src/index.tsx",
+   "main": "./lib/commonjs/index.cjs",
+   "module": "./lib/module/index.mjs",
+   "types": "./lib/typescript/src/index.d.ts",
+   "exports": {
+     ".": {
+       "types": "./typescript/src/index.d.ts",
+       "require": "./commonjs/index.cjs",
+       "import": "./module/index.mjs"
+     }
+   },
    "files": [
      "lib",
      "src"
@@ -85,15 +92,18 @@ yarn add --dev react-native-builder-bob
 
    Here is what each of these fields mean:
 
+   - `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 type check the code using your library.
-   - `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.
    - `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.
 
    Make sure to change specify correct files according to the targets you have enabled.
 
-   **NOTE**: 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).
+   > The `exports` field also requires the `esm` option to be enabled for the [`commonjs`](#commonjs) and [`module`](#module) targets. In addition, the file extensions of the generated files will be `.js` instead of `.cjs` and `.mjs` if the `esm` option is not 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).
 
 1. Add the output directory to `.gitignore` and `.eslintignore`
 
@@ -148,12 +158,14 @@ Various targets to build for. The available targets are:
 
 Enable compiling source files with Babel and use commonjs module system.
 
-This is useful for running the code in Node (SSR, tests etc.). The output file should be referenced in the `main` field of `package.json`.
+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`.
 
-By default, the code is compiled to support last 2 versions of modern browsers. It also strips TypeScript and Flow annotations, and 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. 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:
 
+- `esm` (`boolean`): Enabling this option will output ES modules compatible code for Node.js 12+, modern browsers and other tools that support `package.json`'s `exports` field. This mainly adds file extensions to the imports and exports. Note that file extensions are not added when importing a file that may have platform-specific extensions (e.g. `.android.ts`). In addition, the generated files will have `.cjs` (commonjs) and `.mjs` (modules) extensions instead of `.js` - this is necessary to disambiguate between the two formats.
+
 - `configFile` (`boolean` | `string`): To customize the babel config used, you can pass the [`configFile`](https://babeljs.io/docs/en/options#configfile) option as `true` if you have a `babel.config.js` or a path to a custom config file. This will override the default configuration. You can extend the default configuration by using the [`react-native-builder-bob/babel-preset`](https://github.com/callstack/react-native-builder-bob/blob/main/packages/react-native-builder-bob/babel-preset.js) preset.
 
 - `babelrc` (`boolean`): You can set the [`babelrc`](https://babeljs.io/docs/en/options#babelrc) option to `true` to enable using `.babelrc` files.
@@ -165,19 +177,19 @@ In addition, the following options are supported:
 Example:
 
 ```json
-["commonjs", { "configFile": true, "copyFlow": true }]
+["commonjs", { "esm": true, "copyFlow": true }]
 ```
 
 #### `module`
 
 Enable compiling source files with Babel and use ES module system. This is essentially same as the `commonjs` target and accepts the same options, but leaves the `import`/`export` statements in your code.
 
-This is useful for bundlers which understand ES modules and can tree-shake. The output file should be referenced in the `module` field of `package.json`.
+This is useful for bundlers which 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`.
 
 Example:
 
 ```json
-["module", { "configFile": true }]
+["module", { "esm": true, "sourceMaps": false }]
 ```
 
 #### `typescript`
@@ -196,6 +208,8 @@ Example:
 ["typescript", { "project": "tsconfig.build.json" }]
 ```
 
+The output file should be referenced in the `types` field or `exports['.'].types` field of `package.json`.
+
 ## Commands
 
 The `bob` CLI exposes the following commands:

packages/create-react-native-library/src/index.ts

@@ -14,7 +14,7 @@ import generateExampleApp, {
 import { spawn } from './utils/spawn';
 import { version } from '../package.json';
 
-const FALLBACK_BOB_VERSION = '0.20.0';
+const FALLBACK_BOB_VERSION = '0.25.0';
 
 const BINARIES = [
   /(gradlew|\.(jar|keystore|png|jpg|gif))$/,

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

@@ -2,10 +2,17 @@
   "name": "<%- project.slug -%>",
   "version": "0.1.0",
   "description": "<%- project.description %>",
-  "main": "lib/commonjs/index",
-  "module": "lib/module/index",
-  "types": "lib/typescript/src/index.d.ts",
-  "source": "src/index",
+  "source": "./src/index.tsx",
+  "main": "./lib/commonjs/index.cjs",
+  "module": "./lib/module/index.mjs",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/typescript/src/index.d.ts",
+      "import": "./lib/module/index.mjs",
+      "require": "./lib/commonjs/index.cjs"
+    }
+  },
   "files": [
     "src",
     "lib",
@@ -157,8 +164,17 @@
     "source": "src",
     "output": "lib",
     "targets": [
-      "commonjs",
-      "module",
+      [
+        "commonjs",
+        {
+          "esm": true
+        }
+      ],
+      ["module",
+        {
+          "esm": true
+        }
+      ],
       [
         "typescript",
         {

packages/create-react-native-library/templates/common/tsconfig.json

@@ -9,9 +9,9 @@
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "jsx": "react-jsx",
-    "lib": ["esnext"],
-    "module": "esnext",
-    "moduleResolution": "node",
+    "lib": ["ESNext"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
     "noFallthroughCasesInSwitch": true,
     "noImplicitReturns": true,
     "noImplicitUseStrict": false,
@@ -22,7 +22,7 @@
     "resolveJsonModule": true,
     "skipLibCheck": true,
     "strict": true,
-    "target": "esnext",
+    "target": "ESNext",
     "verbatimModuleSyntax": true
   }
 }

packages/react-native-builder-bob/babel-preset.js

@@ -2,7 +2,14 @@
 
 const browserslist = require('browserslist');
 
+/**
+ * Babel preset for React Native Builder Bob
+ * @param {'commonjs' | 'preserve'} options.modules - Whether to compile modules to CommonJS or preserve them
+ * @param {Boolean} options.esm - Whether to output ES module compatible code, e.g. by adding extension to import/export statements
+ */
 module.exports = function (api, options, cwd) {
+  const cjs = options.modules === 'commonjs';
+
   return {
     presets: [
       [
@@ -24,7 +31,7 @@ module.exports = function (api, options, cwd) {
             node: '18',
           },
           useBuiltIns: false,
-          modules: options.modules || false,
+          modules: cjs ? 'commonjs' : false,
         },
       ],
       [
@@ -36,5 +43,13 @@ module.exports = function (api, options, cwd) {
       require.resolve('@babel/preset-typescript'),
       require.resolve('@babel/preset-flow'),
     ],
+    plugins: [
+      [
+        require.resolve('./lib/babel'),
+        {
+          extension: options.esm ? (cjs ? 'cjs' : 'mjs') : undefined,
+        },
+      ],
+    ],
   };
 };

packages/react-native-builder-bob/src/__tests__/index.test.ts

@@ -3,7 +3,7 @@ import { transformFileAsync } from '@babel/core';
 import fs from 'node:fs';
 import path from 'node:path';
 
-it.each(['imports', 'exports'])(`adds .js extension to %s`, async (name) => {
+it.each(['imports', 'exports'])(`adds extension to %s`, async (name) => {
   const filepath = path.resolve(
     __dirname,
     `../__fixtures__/project/code/$${name}-input.ts`
@@ -25,36 +25,3 @@ it.each(['imports', 'exports'])(`adds .js extension to %s`, async (name) => {
 
   expect(result?.code).toEqual(expected.trim());
 });
-
-it('replaces alias imports', async () => {
-  const filepath = path.resolve(
-    __dirname,
-    `../__fixtures__/project/code/$alias-input.ts`
-  );
-
-  const result = await transformFileAsync(filepath, {
-    cwd: __dirname,
-    configFile: false,
-    babelrc: false,
-    plugins: [
-      '@babel/plugin-syntax-typescript',
-      [
-        require.resolve('../babel.ts'),
-        {
-          alias: {
-            '@': '../__fixtures__/project',
-            'file': '../__fixtures__/project/f',
-            'something': 'another',
-          },
-        },
-      ],
-    ],
-  });
-
-  const expected = await fs.promises.readFile(
-    path.resolve(__dirname, `../__fixtures__/project/code/$alias-output.ts`),
-    'utf8'
-  );
-
-  expect(result?.code).toEqual(expected.trim());
-});