Move JavaScript exports rewrites to publishConfig/prepack (#54857)

Summary:
### Motivation

Updates the shared JavaScript build setup to use the modern `publishConfig` convention.

This:

- Simplifies the build script.
- Makes the production values for `"exports"` more understandable in place (especially by separating from exports conditions).
- Prevents us from creating a dirty file state when running `yarn build`.

### Changes

- Add `publishConfig` to each `package.json` listing production `"exports"` targets.
- Add `scripts/build/prepack.js` script to action `publishConfig` (now on `npm pack`, `npm publish` exclusively).
- Remove `"exports"` rewriting (and un-rewriting safeguards) from build script.

**Note on `"prepack"`**

Slightly unfortunately, `publishConfig` doesn't work consistently between package managers currently, including npm — so this does not work implicitly (but may in future).

We're instead following `publishConfig` as a convention, and explicitly implementing a full copy (theoretically forking us towards pnpm and Yarn v4's approach).

However, I believe this is:

- Worthwhile, for the motivations above — and in particular being able to understand the final shape of `"exports"` (independent from the dimension of conditional exports, which may come into play later).
- Completely inspectable/maintainable as an explicit implementation (`scripts/build/prepack.js`).

Changelog: [Internal]

Pull Request resolved: #54857

Test Plan:
### CI

✅ GitHub Actions

### End-to-end release test script

(Note: Rebased on `0.83-stable` when tested)

```
yarn test-release-local -t "RNTestProject" -p "iOS" -c $GITHUB_TOKEN
```

{F1984106139}

✅ Test script runs `npm publish` on packages to a local proxy.

{F1984106146}

✅ Installed packages have `publishConfig` `"exports"` values applied

NOTE: ⬆️ This is **exactly** the same output as before.

 {F1984106148}

✅ `/tmp/RNTestProject` runs using built + proxy-published + proxy-installed packages

Reviewed By: cipolleschi

Differential Revision: D88963450

Pulled By: huntie

fbshipit-source-id: f328252cf93a1f1039b79d7f369d1e6e7e5b4b52

Author: huntie

packages/community-cli-plugin/package.json

@@ -18,9 +18,18 @@
     ".": "./src/index.js",
     "./package.json": "./package.json"
   },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./package.json": "./package.json"
+    }
+  },
   "files": [
     "dist"
   ],
+  "scripts": {
+    "prepack": "node ../../scripts/build/prepack.js"
+  },
   "dependencies": {
     "@react-native/dev-middleware": "0.84.0-main",
     "debug": "^4.4.0",

packages/core-cli-utils/package.json

@@ -3,29 +3,40 @@
   "version": "0.84.0-main",
   "description": "React Native CLI library for Frameworks to build on",
   "license": "MIT",
-  "main": "./src/index.flow.js",
+  "keywords": [
+    "cli-utils",
+    "react-native"
+  ],
+  "homepage": "https://github.com/facebook/react-native/tree/HEAD/packages/core-cli-utils#readme",
+  "bugs": "https://github.com/facebook/react-native/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/facebook/react-native.git",
     "directory": "packages/core-cli-utils"
   },
+  "main": "./src/index.flow.js",
   "exports": {
     ".": "./src/index.js",
     "./package.json": "./package.json",
     "./version.js": "./src/public/version.js"
   },
-  "homepage": "https://github.com/facebook/react-native/tree/HEAD/packages/core-cli-utils#readme",
-  "keywords": [
-    "cli-utils",
-    "react-native"
-  ],
-  "bugs": "https://github.com/facebook/react-native/issues",
-  "engines": {
-    "node": ">= 20.19.4"
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "exports": {
+      ".": "./dist/index.js",
+      "./package.json": "./package.json",
+      "./version.js": "./dist/public/version.js"
+    }
   },
   "files": [
     "dist"
   ],
+  "scripts": {
+    "prepack": "node ../../scripts/build/prepack.js"
+  },
   "dependencies": {},
-  "devDependencies": {}
+  "devDependencies": {},
+  "engines": {
+    "node": ">= 20.19.4"
+  }
 }

packages/debugger-shell/package.json

@@ -17,8 +17,19 @@
     },
     "./package.json": "./package.json"
   },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "exports": {
+      ".": {
+        "node": "./dist/node/index.js",
+        "electron": "./dist/electron/index.js"
+      },
+      "./package.json": "./package.json"
+    }
+  },
   "scripts": {
-    "dev": "electron src/electron"
+    "dev": "electron src/electron",
+    "prepack": "node ../../scripts/build/prepack.js"
   },
   "repository": {
     "type": "git",

packages/dev-middleware/package.json

@@ -18,9 +18,18 @@
     ".": "./src/index.js",
     "./package.json": "./package.json"
   },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./package.json": "./package.json"
+    }
+  },
   "files": [
     "dist"
   ],
+  "scripts": {
+    "prepack": "node ../../scripts/build/prepack.js"
+  },
   "dependencies": {
     "@isaacs/ttlcache": "^1.4.1",
     "@react-native/debugger-frontend": "0.84.0-main",
@@ -35,13 +44,13 @@
     "serve-static": "^1.16.2",
     "ws": "^7.5.10"
   },
-  "engines": {
-    "node": ">= 20.19.4"
-  },
   "devDependencies": {
     "@react-native/debugger-shell": "0.84.0-main",
     "selfsigned": "^4.0.0",
     "undici": "^5.29.0",
     "wait-for-expect": "^3.0.2"
+  },
+  "engines": {
+    "node": ">= 20.19.4"
   }
 }

packages/metro-config/package.json

@@ -22,9 +22,18 @@
     ".": "./src/index.js",
     "./package.json": "./package.json"
   },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./package.json": "./package.json"
+    }
+  },
   "files": [
     "dist"
   ],
+  "scripts": {
+    "prepack": "node ../../scripts/build/prepack.js"
+  },
   "dependencies": {
     "@react-native/js-polyfills": "0.84.0-main",
     "@react-native/metro-babel-transformer": "0.84.0-main",

packages/react-native-compatibility-check/package.json

@@ -25,9 +25,18 @@
     ".": "./src/index.js",
     "./package.json": "./package.json"
   },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./package.json": "./package.json"
+    }
+  },
   "files": [
     "dist"
   ],
+  "scripts": {
+    "prepack": "node ../../scripts/build/prepack.js"
+  },
   "dependencies": {
     "@react-native/codegen": "0.84.0-main"
   },

scripts/build/README.md

@@ -17,14 +17,6 @@ These scripts form the modern build setup for JavaScript ([Flow](https://flow.or
 - **When does the build run?**
   - Packages are built in CI workflows — both for integration/E2E tests, and before publishing to npm.
 
-#### Limitations/quirks
-
-> [!Note]
-> **🚧 Work in progress!** This is not the final state for our monorepo build tooling. Unfortunately, our solution options are narrow due to integration requirements with Meta's codebase.
-
-- Running `yarn build` will mutate `package.json` files in place, resulting in a dirty Git working copy.
-- We make use of "wrapper files" (`.js` → `.js.flow`) for each package entry point, to enable running from source with zero config. To validate these, package entry points must be explicitly defined via `"exports"`.
-
 ## Usage
 
 **💡 Reminder**: 99% of the time, there is no need to use `yarn build`, as all packages will run from source during development.
@@ -44,9 +36,6 @@ yarn clean
 
 Once built, developing in the monorepo should continue to work — now using the compiled version of each package.
 
-> [!Warning]
-> **Build changes should not be committed**. Currently, `yarn build` will make changes to each `package.json` file, which should not be committed. This is validated in CI.
-
 ## Configuration
 
 Monorepo packages must be opted in for build, configured in `config.js` (where build options are also documented).
@@ -77,6 +66,7 @@ packages/
 
 Notes:
 
+- We make use of "wrapper files" (`.js` → `.js.flow`) for each package entry point, to enable running from source with zero config. To validate these, package entry points must be explicitly defined via `"exports"`.
 - To minimize complexity, prefer only a single entry of `{".": "src/index.js"}` in `"exports"` for new packages.
 
 ## Build behavior
@@ -85,8 +75,7 @@ Running `yarn build` will compile each package following the below steps, depend
 
 - Create a `dist/` directory, replicating each source file under `src/`:
   - For every `@flow` file, strip Flow annotations using [flow-api-extractor](https://www.npmjs.com/package/flow-api-translator).
-  - For every entry point in `"exports"`, remove the `.js` wrapper file and compile from the `.flow.js` source.
-- Rewrite each package `"exports"` target to map to the `dist/` directory location.
+  - For each entry point in `"exports"`, remove the `.js` wrapper file and compile from the `.flow.js` source.
 - If configured, emit a Flow (`.js.flow`) or TypeScript (`.d.ts`) type definition file per source file, using [flow-api-extractor](https://www.npmjs.com/package/flow-api-translator).
 
 Together, this might look like the following:
@@ -99,7 +88,7 @@ packages/
       index.js.flow  # Flow definition file
       index.d.ts     # TypeScript definition file
       [other transformed files]
-    package.json     # "src/index.js" export rewritten to "dist/index.js"
+    package.json     # "publishConfig" will override exports to "dist/" on publish
 ```
 
 **Link**: [Example `dist/` output on npm](https://www.npmjs.com/package/@react-native/dev-middleware/v/0.76.5?activeTab=code).

scripts/build/build.js

@@ -136,9 +136,6 @@ async function buildPackage(packageName /*: string */) {
       validateTypeScriptDefs(packageName);
     }
 
-    // Rewrite package.json "exports" field (src -> dist)
-    await rewritePackageExports(packageName);
-
     process.stdout.write(
       styleText(['reset', 'inverse', 'bold', 'green'], ' DONE '),
     );
@@ -330,18 +327,15 @@ async function getEntryPoints(
         continue;
       }
 
-      // Normalize to original path if previously rewritten
-      const original = normalizeExportsTarget(target);
-
-      if (original.endsWith('.flow.js')) {
+      if (target.endsWith('.flow.js')) {
         throw new Error(
-          `Package ${packageName} defines exports["${subpath}"] = "${original}". ` +
+          `Package ${packageName} defines exports["${subpath}"] = "${target}". ` +
             'Expecting a .js wrapper file. See other monorepo packages for examples.',
         );
       }
 
       // Our special case for wrapper files that need to be stripped
-      const resolvedTarget = path.resolve(PACKAGES_DIR, packageName, original);
+      const resolvedTarget = path.resolve(PACKAGES_DIR, packageName, target);
       const resolvedFlowTarget = resolvedTarget.replace(/\.js$/, '.flow.js');
 
       try {
@@ -383,51 +377,6 @@ function getBuildPath(file /*: string */) /*: string */ {
   );
 }
 
-async function rewritePackageExports(packageName /*: string */) {
-  const packageJsonPath = path.join(PACKAGES_DIR, packageName, 'package.json');
-  const pkg = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
-
-  pkg.exports = rewriteExportsField(pkg.exports);
-
-  if (pkg.main != null) {
-    pkg.main = rewriteExportsTarget(pkg.main);
-  }
-
-  await fs.writeFile(packageJsonPath, JSON.stringify(pkg, null, 2) + '\n');
-}
-
-/*::
-type ExportsField = {
-  [subpath: string]: ExportsField | string,
-} | string;
-*/
-
-function rewriteExportsField(
-  exportsField /*: ExportsField */,
-) /*: ExportsField */ {
-  if (typeof exportsField === 'string') {
-    return rewriteExportsTarget(exportsField);
-  }
-
-  for (const key in exportsField) {
-    if (typeof exportsField[key] === 'string') {
-      exportsField[key] = rewriteExportsTarget(exportsField[key]);
-    } else if (typeof exportsField[key] === 'object') {
-      exportsField[key] = rewriteExportsField(exportsField[key]);
-    }
-  }
-
-  return exportsField;
-}
-
-function rewriteExportsTarget(target /*: string */) /*: string */ {
-  return target.replace('./' + SRC_DIR + '/', './' + BUILD_DIR + '/');
-}
-
-function normalizeExportsTarget(target /*: string */) /*: string */ {
-  return target.replace('./' + BUILD_DIR + '/', './' + SRC_DIR + '/');
-}
-
 function validateTypeScriptDefs(packageName /*: string */) {
   const files = globSync('**/*.d.ts', {
     cwd: path.resolve(PACKAGES_DIR, packageName, BUILD_DIR),

scripts/build/prepack.js

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ * @format
+ */
+
+require('../shared/babelRegister').registerForScript();
+
+const {promises: fs} = require('fs');
+const path = require('path');
+
+// "prepack" script to prepare JavaScript packages for publishing.
+//
+// We use this to copy over fields from "publishConfig" to the root of each
+// package.json, which is not supported in Yarn v1.
+
+async function prepack() {
+  const pkgJsonPath = path.join(process.cwd(), './package.json');
+  const contents = JSON.parse(await fs.readFile(pkgJsonPath, 'utf8'));
+
+  if (
+    path.dirname(pkgJsonPath).split(path.sep).slice(-2, -1)[0] !== 'packages'
+  ) {
+    console.error('Error: prepack.js must be run from a package directory');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (contents.publishConfig != null) {
+    for (const key of Object.keys(contents.publishConfig)) {
+      contents[key] = contents.publishConfig[key];
+    }
+  }
+  delete contents.publishConfig;
+
+  await fs.writeFile(pkgJsonPath, JSON.stringify(contents, null, 2) + '\n');
+}
+
+if (require.main === module) {
+  void prepack();
+}