@react-native/core-cli-utils 0.87.0-nightly-20260519-58cd1bf58 → 0.87.0-nightly-20260528-eaf770433

package/.eslintrc.json

@@ -0,0 +1,6 @@
+{
+    "ignorePatterns": ["dist/**"],
+    "rules": {
+        "sort-keys": 2
+    }
+}

package/README.md

@@ -1,55 +1,18 @@
 # @react-native/core-cli-utils
 
-![npm package](https://img.shields.io/npm/v/@react-native/core-cli-utils?color=brightgreen&label=npm%20package)
+A reference implementation of React Native CLI tooling. This package provides composable, ordered `Task` objects for common CLI operations including Android Gradle builds, iOS Xcode/CocoaPods workflows, Metro bundling with Hermes support, and cache cleaning.
 
-A collection of utilites to help Frameworks build their React Native CLI tooling. This is not intended to be used directly use users of React Native.
+This is not published to npm. Framework authors can use this code as a starting point for their own CLI tooling, but should not depend on it as a versioned API.
 
-## Usage
+## Modules
 
-```js
-import { Command } from 'commander';
-import cli from '@react-native/core-cli-utils';
-import debug from 'debug';
+- **`android`** — Gradle-based Android build tasks (assemble, build, install)
+- **`apple`** — Xcode/CocoaPods-based iOS tasks (bootstrap, build, install)
+- **`app`** — Metro bundler tasks (watch mode, bundle mode, Hermes bytecode compilation)
+- **`clean`** — Cache-cleaning tasks (Android/Gradle, Metro, npm, Watchman, Yarn, CocoaPods)
+- **`version`** — Semver version requirements for platform toolchains (Android NDK/SDK, Xcode, Node, etc.)
 
-const android = new Command('android');
+## Consumers
 
-const frameworkFindsAndroidSrcDir = "...";
-const tasks = cli.clean.android(frameworkFindsAndroidSrcDir);
-const log = debug('fancy-framework:android');
-
-android
-    .command('clean')
-    .description(cli.clean.android)
-    .action(async () => {
-        const log = debug('fancy-framework:android:clean');
-        log(`🧹 let me clean your Android caches`);
-        // Add other caches your framework needs besides the normal React Native caches
-        // here.
-        for (const task of tasks) {
-            try {
-                log(`\t ${task.label}`);
-                // See: https://github.com/sindresorhus/execa#lines
-                const {stdout} = await task.action({ lines: true })
-                log(stdout.join('\n\tGradle: '));
-            } catch (e) {
-                log(`\t ⚠️ whoops: ${e.message}`);
-            }
-        }
-    });
-```
-
-And you'd be using it like this:
-
-```bash
-$ ./fancy-framework android clean
-🧹 let me clean your Android caches
-    Gradle: // a bunch of gradle output
-    Gradle: ....
-```
-
-## Features
-- `"@react-native/core-cli-utils/version.js"` contains the platform and tooling version requirements for react-native.
-
-## Contributing
-
-Changes to this package can be made locally and linked against your app. Please see the [Contributing guide](https://reactnative.dev/contributing/overview#contributing-code).
+- [`private/helloworld/`](../helloworld/) — the primary consumer, using Android, iOS, and Metro modules
+- [`packages/rn-tester/`](../../packages/rn-tester/) — uses iOS bootstrap for CocoaPods setup

package/package.json

@@ -1,34 +1,19 @@
 {
   "name": "@react-native/core-cli-utils",
-  "version": "0.87.0-nightly-20260519-58cd1bf58",
-  "description": "React Native CLI library for Frameworks to build on",
+  "version": "0.87.0-nightly-20260528-eaf770433",
+  "description": "Reference implementation of React Native CLI tooling",
   "license": "MIT",
-  "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": "./dist/index.js",
+  "main": "./src/index.js",
   "exports": {
-    ".": "./dist/index.js",
+    ".": "./src/index.js",
     "./package.json": "./package.json",
-    "./version.js": "./dist/public/version.js"
+    "./version.js": "./src/public/version.js"
   },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "prepack": "node ../../scripts/build/prepack.js"
+  "dependencies": {
+    "metro-babel-register": "^0.84.3"
   },
-  "dependencies": {},
   "devDependencies": {},
   "engines": {
-    "node": "^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0"
+    "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
   }
 }

package/src/index.js

@@ -0,0 +1,21 @@
+/**
+ * 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 strict-local
+ * @format
+ */
+
+/*::
+export type {Task} from './private/types';
+*/
+
+const {tasks: android} = require('./private/android.js');
+const {tasks: app} = require('./private/app.js');
+const {tasks: apple} = require('./private/apple.js');
+const {tasks: clean} = require('./private/clean.js');
+const version = require('./public/version.js');
+
+module.exports = {android, app, apple, clean, version};

package/src/private/android.js

@@ -0,0 +1,129 @@
+/**
+ * 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 strict-local
+ * @format
+ */
+
+/*::
+import type {Task} from './types';
+import type {ExecaPromise} from 'execa';
+*/
+
+const {isWindows, task} = require('./utils');
+const execa = require('execa');
+
+/*::
+type AndroidBuildMode = 'Debug' | 'Release';
+
+type Path = string;
+type Args = ReadonlyArray<string>;
+
+type Config = {
+  cwd: Path,
+  hermes?: boolean,
+  mode: AndroidBuildMode,
+  name: string,
+  newArchitecture?: boolean,
+  sdk?: Path,
+};
+*/
+
+function gradle(
+  taskName /*: string */,
+  args /*: Args */,
+  options /*: {cwd: string, env?: {[k: string]: string | void}} */,
+) /*: ExecaPromise */ {
+  const gradlew = isWindows ? 'gradlew.bat' : './gradlew';
+  return execa(gradlew, [taskName, ...args], {
+    cwd: options.cwd,
+    env: options.env,
+  });
+}
+
+function androidSdkPath(sdk /*: ?string */) /*: string */ {
+  return sdk ?? process.env.ANDROID_HOME ?? process.env.ANDROID_SDK ?? '';
+}
+
+function boolToStr(value /*: boolean */) /*: string */ {
+  return value ? 'true' : 'false';
+}
+
+const FIRST = 1;
+
+//
+// Android Tasks
+//
+/*::
+type AndroidTasks = {
+  assemble: (...gradleArgs: Args) => {
+    run: Task<ExecaPromise>,
+  },
+  build: (...gradleArgs: Args) => {
+    run: Task<ExecaPromise>,
+  },
+  install: (...gradleArgs: Args) => {
+    run: Task<ExecaPromise>,
+  },
+};
+*/
+
+const tasks = (config /*: Config */) /*: AndroidTasks */ => ({
+  assemble: (...gradleArgs /*: Args */) => ({
+    run: task(FIRST, 'Assemble Android App', () => {
+      const args = [];
+      if (config.hermes != null) {
+        args.push(`-PhermesEnabled=${boolToStr(config.hermes)}`);
+      }
+      if (config.newArchitecture != null) {
+        args.push(`-PnewArchEnabled=${boolToStr(config.newArchitecture)}`);
+      }
+      args.push(...gradleArgs);
+      return gradle(`${config.name}:assemble${config.mode}`, gradleArgs, {
+        cwd: config.cwd,
+        env: {ANDROID_HOME: androidSdkPath(config.sdk)},
+      });
+    }),
+  }),
+  build: (...gradleArgs /*: Args */) => ({
+    run: task(FIRST, 'Assembles and tests Android App', () => {
+      const args = [];
+      if (config.hermes != null) {
+        args.push(`-PhermesEnabled=${boolToStr(config.hermes)}`);
+      }
+      if (config.newArchitecture != null) {
+        args.push(`-PnewArchEnabled=${boolToStr(config.newArchitecture)}`);
+      }
+      args.push(...gradleArgs);
+      return gradle(`${config.name}:bundle${config.mode}`, args, {
+        cwd: config.cwd,
+        env: {ANDROID_HOME: androidSdkPath(config.sdk)},
+      });
+    }),
+  }),
+  /**
+   * Useful extra gradle arguments:
+   *
+   *
+   * -PreactNativeDevServerPort=8081 sets the port for the installed app to point towards a Metro
+   *                                 server on (for example) 8081.
+   */
+  install: (...gradleArgs /*: Args */) => ({
+    run: task(FIRST, 'Installs the assembled Android App', () =>
+      gradle(`${config.name}:install${config.mode}`, gradleArgs, {
+        cwd: config.cwd,
+        env: {ANDROID_HOME: androidSdkPath(config.sdk)},
+      }),
+    ),
+  }),
+
+  // We are not supporting launching the app and setting up the tunnel for metro <-> app, this is
+  // a framework concern. For an example of how one could do this, please look at the community
+  // CLI's code:
+  // https://github.com/react-native-community/cli/blob/54d48a4e08a1aef334ae6168788e0157a666b4f5/packages/cli-platform-android/src/commands/runAndroid/index.ts#L272C1-L290C2
+});
+
+module.exports = {tasks};

package/src/private/app.js

@@ -0,0 +1,247 @@
+/**
+ * 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 strict-local
+ * @format
+ */
+
+/*::
+import type {Task} from './types';
+import type {ExecaPromise} from 'execa';
+*/
+
+const {task} = require('./utils');
+const debug = require('debug');
+const execa = require('execa');
+const fs = require('fs');
+const path = require('path');
+
+const log = debug('core-cli-utils');
+
+/*::
+type BundlerOptions = {
+  // Metro's config: https://metrobundler.dev/docs/configuration/
+  config?: string,
+  // Typically index.{ios,android}.js
+  entryFile: string,
+  +platform: 'ios' | 'android' | string,
+  dev: boolean,
+  // Metro built main bundle
+  outputJsBundle: string,
+  minify: boolean,
+  optimize: boolean,
+  // Generate a source map file
+  outputSourceMap: string,
+  // Where to pass the final bundle. Typically this is the App's resource
+  // folder, however this is app specific. React Native will need to know where
+  // this is to bootstrap your application.  See:
+  // - Android: https://reactnative.dev/docs/integration-with-existing-apps?language=kotlin#creating-a-release-build-in-android-studio
+  // - iOS: https://reactnative.dev/docs/integration-with-existing-apps?language=swift#2-event-handler
+  outputBundle: string,
+  cwd: string,
+
+  jsvm: 'hermes' | 'jsc',
+  hermes?: HermesConfig,
+
+  ...Bundler,
+};
+
+type HermesConfig = {
+  // Path where hermes is is installed
+  // iOS: Pods/hermes-engine
+  path: string,
+  // iOS: <hermes.path>/destroot/bin/hermesc
+  hermesc: string,
+};
+
+type BundlerWatch = {
+  +mode: 'watch',
+  callback?: (metro: ExecaPromise) => void,
+};
+
+type BundlerBuild = {
+  +mode: 'bundle',
+};
+
+type Bundler = BundlerWatch | BundlerBuild;
+
+type Bundle = {
+  validate?: Task<void>,
+  javascript: Task<ExecaPromise>,
+  sourcemap?: Task<void>,
+  validateHermesc?: Task<ExecaPromise>,
+  convert?: Task<ExecaPromise>,
+  compose?: Task<ExecaPromise>,
+};
+*/
+
+const FIRST = 1,
+  SECOND = 2,
+  THIRD = 3,
+  FOURTH = 4;
+
+function getNodePackagePath(packageName /*: string */) /*: string */ {
+  // $FlowFixMe[prop-missing] type definition is incomplete
+  return require.resolve(packageName, {cwd: [process.cwd(), ...module.paths]});
+}
+
+function metro(...args /*: ReadonlyArray<string> */) /*: ExecaPromise */ {
+  log(`🚇 metro ${args.join(' ')} `);
+  return execa('npx', ['--offline', 'metro', ...args]);
+}
+
+const tasks = {
+  bundle: (
+    options /*: BundlerOptions */,
+    ...args /*: ReadonlyArray<string> */
+  ) /*: Bundle */ => {
+    const steps /*: Bundle */ = {
+      /* eslint-disable sort-keys */
+      validate: task(FIRST, 'Check if Metro is available', () => {
+        try {
+          require('metro');
+        } catch {
+          throw new Error('Metro is not available');
+        }
+      }),
+      javascript: task(SECOND, 'Metro watching for changes', () =>
+        metro('serve', ...args),
+      ),
+    };
+
+    return options.mode === 'bundle'
+      ? // $FlowFixMe[unsafe-object-assign]
+        Object.assign(steps, bundleApp(options, ...args))
+      : steps;
+  },
+};
+
+const bundleApp = (
+  options /*: BundlerOptions */,
+  ...metroArgs /*: ReadonlyArray<string> */
+) => {
+  if (options.outputJsBundle === options.outputBundle) {
+    throw new Error('outputJsBundle and outputBundle cannot be the same.');
+  }
+  let output =
+    options.jsvm === 'hermes' ? options.outputJsBundle : options.outputBundle;
+
+  if (output === options.outputJsBundle && !output.endsWith('.js')) {
+    log(
+      `Appending .js to outputBundle (because metro cli does it if it's missing): ${output}`,
+    );
+    output += '.js';
+  }
+
+  const isSourceMaps = options.outputSourceMap != null;
+  const bundle /*: Bundle */ = {
+    javascript: task(SECOND, 'Metro generating an .jsbundle', () => {
+      const args = [
+        '--platform',
+        options.platform,
+        '--dev',
+        options.dev ? 'true' : 'false',
+        '--reset-cache',
+        '--out',
+        output,
+      ];
+      if (options.jsvm === 'hermes' && !options.dev) {
+        args.push('--minify', 'false');
+      } else {
+        args.push('--minify', options.minify ? 'true' : 'false');
+      }
+      if (isSourceMaps) {
+        args.push('--source-map');
+      }
+      return metro('build', options.entryFile, ...args, ...metroArgs);
+    }),
+  };
+
+  if (options.jsvm === 'jsc') {
+    return bundle;
+  }
+
+  if (options.hermes?.path == null || options.hermes?.hermesc == null) {
+    throw new Error('If jsvm == "hermes", hermes config must be provided.');
+  }
+
+  const hermes /*: HermesConfig */ = options.hermes;
+
+  const isHermesInstalled /*: boolean */ = fs.existsSync(hermes.path);
+  if (!isHermesInstalled) {
+    throw new Error(
+      'Hermes Pod must be installed before bundling.\n' +
+        'Did you forget to bootstrap?',
+    );
+  }
+
+  const hermesc /*: string */ = path.join(hermes.path, hermes.hermesc);
+
+  let composeSourceMaps;
+  if (isSourceMaps) {
+    bundle.sourcemap = task(
+      FIRST,
+      'Check if SourceMap script available',
+      () => {
+        composeSourceMaps = getNodePackagePath(
+          'react-native/scripts/compose-source-maps.js',
+        );
+      },
+    );
+  }
+
+  bundle.validateHermesc = task(FIRST, 'Check if Hermesc is available', () =>
+    execa(hermesc, ['--version']),
+  );
+
+  bundle.convert = task(
+    THIRD,
+    'Hermesc converting .jsbundle → bytecode',
+    () => {
+      const args = [
+        '-emit-binary',
+        '-max-diagnostic-width=80',
+        options.dev === true ? '-Og' : '-O',
+      ];
+      if (isSourceMaps) {
+        args.push('-output-source-map');
+      }
+      args.push(`-out=${options.outputBundle}`, output);
+      return execa(hermesc, args, {cwd: options.cwd});
+    },
+  );
+
+  bundle.compose = task(FOURTH, 'Compose Hermes and Metro source maps', () => {
+    if (composeSourceMaps == null) {
+      throw new Error(
+        'Unable to find the compose-source-map.js script in react-native',
+      );
+    }
+    const metroSourceMap = output.replace(/(\.js)?$/, '.map');
+    const hermesSourceMap = options.outputBundle + '.map';
+    const compose = execa(
+      'node',
+      [
+        composeSourceMaps,
+        metroSourceMap,
+        hermesSourceMap,
+        `-o ${options.outputSourceMap}`,
+      ],
+      {
+        cwd: options.cwd,
+      },
+    );
+    compose.finally(() => {
+      fs.rmSync(metroSourceMap, {force: true});
+      fs.rmSync(hermesSourceMap, {force: true});
+    });
+    return compose;
+  });
+
+  return bundle;
+};
+
+module.exports = {tasks};