@callstack/brownfield-cli 3.8.1 → 3.10.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @callstack/brownfield-cli
 
+## 3.10.0
+
+### Minor Changes
+
+- [#323](https://github.com/callstack/react-native-brownfield/pull/323) [`3456d3a`](https://github.com/callstack/react-native-brownfield/commit/3456d3aded18002475def4b79889979e76e1db5e) Thanks [@artus9033](https://github.com/artus9033)! - Support RN prebuilts in Brownfield, by default enabled in RN >= 0.84, opt-in in RN 0.83; or in Expo 55+ (Expo 54 is not supported).
+
+  Add `--use-prebuilt-rn-core` to `brownfield package:ios` so callers can opt into or out of React Native Apple prebuilt binaries; omitting the flag defers to version-aware defaults handled by Rock. The CLI rejects `--use-prebuilt-rn-core` when React Native is older than 0.81 or when the project is Expo SDK older than 55.
+
+  Fix brownfield framework dylib install names to use @rpath instead of hardcoded paths.
+
+## 3.9.0
+
+### Minor Changes
+
+- [#326](https://github.com/callstack/react-native-brownfield/pull/326) [`80e6364`](https://github.com/callstack/react-native-brownfield/commit/80e6364d405d216b3e84a6297dfe346d2f01444b) Thanks [@artus9033](https://github.com/artus9033)! - feat: strip SO files by default, deprecate experimental option in favor of useStrippedSoFiles
+
 ## 3.8.1
 
 ### Patch Changes

package/dist/brownfield/commands/packageIos.d.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import { ExampleUsage } from '../../shared/index.js';
+export declare function parseUsePrebuiltRnCoreArgument(value: string | boolean): boolean;
 export declare const packageIosCommand: Command;
 export declare const packageIosExample: ExampleUsage;
 //# sourceMappingURL=packageIos.d.ts.map

package/dist/brownfield/commands/packageIos.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"packageIos.d.ts","sourceRoot":"","sources":["../../../src/brownfield/commands/packageIos.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAGL,YAAY,EACb,MAAM,uBAAuB,CAAC;AAK/B,eAAO,MAAM,iBAAiB,SAgJ7B,CAAC;AAEF,eAAO,MAAM,iBAAiB,cAG7B,CAAC"}
+{"version":3,"file":"packageIos.d.ts","sourceRoot":"","sources":["../../../src/brownfield/commands/packageIos.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAK5C,OAAO,EAGL,YAAY,EACb,MAAM,uBAAuB,CAAC;AAY/B,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,MAAM,GAAG,OAAO,GACtB,OAAO,CAcT;AAOD,eAAO,MAAM,iBAAiB,SA6L3B,CAAC;AAEJ,eAAO,MAAM,iBAAiB,cAG7B,CAAC"}

package/dist/brownfield/commands/packageIos.js

@@ -2,22 +2,60 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { getBuildOptions, mergeFrameworks, } from '@rock-js/platform-apple-helpers';
 import { packageIosAction } from '@rock-js/plugin-brownfield-ios';
-import { colorLink, getReactNativeVersion, logger, relativeToCwd, } from '@rock-js/tools';
-import { Command } from 'commander';
+import { RockError, colorLink, getReactNativeVersion, logger, relativeToCwd, } from '@rock-js/tools';
+import { Command, Option } from 'commander';
 import { runExpoPrebuildIfNeeded } from '../utils/expo.js';
 import { getProjectInfo } from '../utils/project.js';
+import { supportsPrebuiltRNCore } from '../utils/supportsPrebuiltRNCore.js';
 import { actionRunner, curryOptions, ExampleUsage, } from '../../shared/index.js';
 import { runBrownieCodegenIfApplicable } from '../../brownie/helpers/runBrownieCodegenIfApplicable.js';
 import { runNavigationCodegenIfApplicable } from '../../navigation/helpers/runNavigationCodegenIfApplicable.js';
 import { stripFrameworkBinary } from '../utils/stripFrameworkBinary.js';
+/** Help text for `--use-prebuilt-rn-core` (keep in sync with docs/docs/docs/getting-started/ios.mdx, "React Native Prebuilts" section). */
+const USE_PREBUILT_RN_CORE_HELP = 'Whether the Xcode build for packaging should use React Native Apple prebuilt binaries (via CocoaPods). ' +
+    'If you omit this flag, Brownfield follows version-aware defaults: for React Native 0.84 and newer, prebuilts are enabled by default; for RN 0.83, they are disabled unless you opt in. ' +
+    'Pass true or false to force either behavior. Use the flag without a value as shorthand for true (same as `--use-prebuilt-rn-core true`). ' +
+    'See the Brownfield iOS guide for details: https://oss.callstack.com/react-native-brownfield/docs/getting-started/ios#react-native-prebuilts';
+export function parseUsePrebuiltRnCoreArgument(value) {
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true' || normalized === '1') {
+        return true;
+    }
+    if (normalized === 'false' || normalized === '0') {
+        return false;
+    }
+    throw new RockError(`Invalid value for --use-prebuilt-rn-core: expected true or false, received "${value}"`);
+}
 export const packageIosCommand = curryOptions(new Command('package:ios').description('Build iOS XCFramework'), getBuildOptions({ platformName: 'ios' }).map((option) => option.name.startsWith('--build-folder')
     ? {
         ...option,
         description: option.description +
             " By default, the '.brownfield/build' path will be used.",
     }
-    : option)).action(actionRunner(async (options) => {
+    : option))
+    .addOption(new Option('--use-prebuilt-rn-core [bool]', USE_PREBUILT_RN_CORE_HELP)
+    .preset(true)
+    .argParser(parseUsePrebuiltRnCoreArgument))
+    .action(actionRunner(async (options) => {
     const { projectRoot, platformConfig, userConfig } = getProjectInfo('ios');
+    const prebuiltRNCoreSupport = supportsPrebuiltRNCore({ projectRoot });
+    // version-aware default when the flag is omitted (see ios.mdx "React Native Prebuilts")
+    options.usePrebuiltRnCore ??= prebuiltRNCoreSupport.supported
+        ? prebuiltRNCoreSupport.enabledByDefault
+        : false;
+    if (prebuiltRNCoreSupport) {
+        logger.info(`${options.usePrebuiltRnCore ? 'Using' : 'Not using'} prebuilt RN core`);
+        if (!prebuiltRNCoreSupport.enabledByDefault &&
+            !options.usePrebuiltRnCore) {
+            logger.info('Your environment supports prebuilt RN Core as an opt-in feature, but it is disabled by default. Pass --use-prebuilt-rn-core to enable it.');
+        }
+    }
+    if (options.usePrebuiltRnCore && !prebuiltRNCoreSupport.supported) {
+        throw new RockError(prebuiltRNCoreSupport.reason);
+    }
     await runExpoPrebuildIfNeeded({ projectRoot, platform: 'ios' });
     if (!userConfig.project.ios) {
         throw new Error('iOS project not found.');
@@ -35,6 +73,7 @@ export const packageIosCommand = curryOptions(new Command('package:ios').descrip
         dotBrownfieldDir = path.join(projectRoot, dotBrownfieldDir);
     }
     options.buildFolder ??= path.join(dotBrownfieldDir, 'build');
+    options.verbose ??= logger.isVerbose();
     // The new_architecture.rb script scans Info.plist and fails on binary plist files,
     // which is the case for our XCFrameworks.
     // We're reusing the "build" directory which is excluded from the scan.
@@ -50,9 +89,9 @@ export const packageIosCommand = curryOptions(new Command('package:ios').descrip
         // e.g. '0.82' (note the missing patch component),
         // therefore we resolve it manually from RN's package.json using Rock's utils
         reactNativeVersion: getReactNativeVersion(projectRoot),
-        usePrebuiltRNCore: false, // for brownfield, it is required to build RN from source
         packageDir, // the output directory for artifacts
         skipCache: true, // cache is dependent on existence of Rock config file
+        usePrebuiltRNCore: options.usePrebuiltRnCore,
     }, platformConfig);
     const reactBrownfieldXcframeworkPath = path.join(packageDir, 'ReactBrownfield.xcframework');
     if (fs.existsSync(reactBrownfieldXcframeworkPath)) {

package/dist/brownfield/utils/project.d.ts

@@ -14,6 +14,7 @@ export declare function getExpoConfigIfIsExpo(projectRoot: string): ExpoProjectC
  * @returns Whether the project is an Expo project
  */
 export declare function isExpoProject(projectRoot: string): boolean;
+export declare function getExpoSdkMajor(projectRoot: string): number | null;
 /**
  * Fills the RNC CLI project config from the Expo config by mutating the passed in `options.projectConfig` object in place
  */

package/dist/brownfield/utils/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../../src/brownfield/utils/project.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,UAAU,EACX,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAKjE,OAAO,EAEL,KAAK,aAAa,IAAI,iBAAiB,EACxC,MAAM,cAAc,CAAC;AAQtB;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,4BAMxD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAc1D;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAAC,EAC9C,aAAa,EACb,UAAU,EAAE,EAAE,GAAG,EAAE,EACnB,WAAW,GACZ,EAAE;IACD,8CAA8C;IAC9C,aAAa,EAAE,aAAa,CAAC;IAE7B,8BAA8B;IAC9B,UAAU,EAAE,iBAAiB,CAAC;IAE9B,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB,QAuBA;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,SAAS,KAAK,GAAG,SAAS,EAC/D,QAAQ,EAAE,QAAQ,GACjB;IACD,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB,cAAc,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CACzC,CAeA;AAED,wBAAgB,aAAa,CAAC,EAC5B,WAAW,EACX,QAAQ,GACT,EAAE;IACD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,KAAK,GAAG,SAAS,CAAC;CAC7B,GAAG,UAAU,CAuBb;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,eAAe,EACrB,aAAa,EAAE,oBAAoB;;;EAQpC"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../../src/brownfield/utils/project.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,UAAU,EACX,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAKjE,OAAO,EAEL,KAAK,aAAa,IAAI,iBAAiB,EACxC,MAAM,cAAc,CAAC;AAQtB;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,4BAMxD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAc1D;AAED,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOlE;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAAC,EAC9C,aAAa,EACb,UAAU,EAAE,EAAE,GAAG,EAAE,EACnB,WAAW,GACZ,EAAE;IACD,8CAA8C;IAC9C,aAAa,EAAE,aAAa,CAAC;IAE7B,8BAA8B;IAC9B,UAAU,EAAE,iBAAiB,CAAC;IAE9B,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB,QAuBA;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,SAAS,KAAK,GAAG,SAAS,EAC/D,QAAQ,EAAE,QAAQ,GACjB;IACD,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB,cAAc,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CACzC,CAeA;AAED,wBAAgB,aAAa,CAAC,EAC5B,WAAW,EACX,QAAQ,GACT,EAAE;IACD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,KAAK,GAAG,SAAS,CAAC;CAC7B,GAAG,UAAU,CAuBb;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,eAAe,EACrB,aAAa,EAAE,oBAAoB;;;EAQpC"}

package/dist/brownfield/utils/project.js

@@ -36,6 +36,14 @@ export function isExpoProject(projectRoot) {
         ['dependencies', 'peerDependencies', 'devDependencies'].some((key) => JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))[key]?.expo);
     return hasExpoConfig && dependsOnExpo;
 }
+export function getExpoSdkMajor(projectRoot) {
+    const rawExpoVersion = getExpoConfigIfIsExpo(projectRoot)?.exp.sdkVersion;
+    if (!rawExpoVersion) {
+        return null;
+    }
+    const expoSdkMajor = parseInt(rawExpoVersion.split('.')[0], 10);
+    return Number.isFinite(expoSdkMajor) ? expoSdkMajor : null;
+}
 /**
  * Fills the RNC CLI project config from the Expo config by mutating the passed in `options.projectConfig` object in place
  */

package/dist/brownfield/utils/supportsPrebuiltRNCore.d.ts

@@ -0,0 +1,18 @@
+/** Minimum RN version that can opt in to prebuilts via `--use-prebuilt-rn-core`. */
+export declare const MIN_REACT_NATIVE_VERSION_FOR_OPT_IN_PREBUILT_RN_CORE = "0.81.0";
+/** Minimum RN version where Brownfield enables prebuilts by default (vanilla projects). */
+export declare const MIN_REACT_NATIVE_VERSION_FOR_PREBUILT_RN_CORE_BY_DEFAULT = "0.84.0";
+export declare const MIN_EXPO_SDK_MAJOR_FOR_PREBUILT_RN_CORE_BY_DEFAULT = 55;
+export type PrebuiltRNCoreSupportResult = {
+    supported: true;
+    enabledByDefault: boolean;
+    reason?: never;
+} | {
+    supported: false;
+    enabledByDefault?: never;
+    reason: string;
+};
+export declare function supportsPrebuiltRNCore({ projectRoot, }: {
+    projectRoot: string;
+}): PrebuiltRNCoreSupportResult;
+//# sourceMappingURL=supportsPrebuiltRNCore.d.ts.map

package/dist/brownfield/utils/supportsPrebuiltRNCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supportsPrebuiltRNCore.d.ts","sourceRoot":"","sources":["../../../src/brownfield/utils/supportsPrebuiltRNCore.ts"],"names":[],"mappings":"AAIA,oFAAoF;AACpF,eAAO,MAAM,oDAAoD,WAAW,CAAC;AAC7E,2FAA2F;AAC3F,eAAO,MAAM,wDAAwD,WAC3D,CAAC;AACX,eAAO,MAAM,kDAAkD,KAAK,CAAC;AAErE,MAAM,MAAM,2BAA2B,GACnC;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,gBAAgB,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,GAC9D;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,gBAAgB,CAAC,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,wBAAgB,sBAAsB,CAAC,EACrC,WAAW,GACZ,EAAE;IACD,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,2BAA2B,CA+C9B"}

package/dist/brownfield/utils/supportsPrebuiltRNCore.js

@@ -0,0 +1,36 @@
+import { getReactNativeVersion, versionCompare } from '@rock-js/tools';
+import { getExpoSdkMajor, isExpoProject } from './project.js';
+/** Minimum RN version that can opt in to prebuilts via `--use-prebuilt-rn-core`. */
+export const MIN_REACT_NATIVE_VERSION_FOR_OPT_IN_PREBUILT_RN_CORE = '0.81.0';
+/** Minimum RN version where Brownfield enables prebuilts by default (vanilla projects). */
+export const MIN_REACT_NATIVE_VERSION_FOR_PREBUILT_RN_CORE_BY_DEFAULT = '0.84.0';
+export const MIN_EXPO_SDK_MAJOR_FOR_PREBUILT_RN_CORE_BY_DEFAULT = 55;
+export function supportsPrebuiltRNCore({ projectRoot, }) {
+    const reactNativeVersion = getReactNativeVersion(projectRoot);
+    if (reactNativeVersion === 'unknown') {
+        return {
+            supported: false,
+            reason: 'Cannot use --use-prebuilt-rn-core: unable to resolve the installed react-native version.',
+        };
+    }
+    if (versionCompare(reactNativeVersion, MIN_REACT_NATIVE_VERSION_FOR_OPT_IN_PREBUILT_RN_CORE) < 0) {
+        return {
+            supported: false,
+            reason: `--use-prebuilt-rn-core requires React Native ${MIN_REACT_NATIVE_VERSION_FOR_OPT_IN_PREBUILT_RN_CORE} or newer (found ${reactNativeVersion}).`,
+        };
+    }
+    if (isExpoProject(projectRoot)) {
+        const expoSdkMajor = getExpoSdkMajor(projectRoot);
+        if (expoSdkMajor === null ||
+            expoSdkMajor < MIN_EXPO_SDK_MAJOR_FOR_PREBUILT_RN_CORE_BY_DEFAULT) {
+            const sdkLabel = expoSdkMajor === null ? 'unknown' : String(expoSdkMajor);
+            return {
+                supported: false,
+                reason: `--use-prebuilt-rn-core is unsupported in Expo SDK ${sdkLabel}: packaging brownfield with prebuilts requires Expo SDK ${MIN_EXPO_SDK_MAJOR_FOR_PREBUILT_RN_CORE_BY_DEFAULT} or newer.`,
+            };
+        }
+        return { supported: true, enabledByDefault: true };
+    }
+    const enabledByDefault = versionCompare(reactNativeVersion, MIN_REACT_NATIVE_VERSION_FOR_PREBUILT_RN_CORE_BY_DEFAULT) >= 0;
+    return { supported: true, enabledByDefault };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@callstack/brownfield-cli",
-  "version": "3.8.1",
+  "version": "3.10.0",
   "license": "MIT",
   "author": "Artur Morys-Magiera <artus9033@gmail.com>",
   "bin": {
@@ -76,11 +76,11 @@
     "@expo/config": "^12.0.13",
     "@react-native-community/cli-config": "^20.0.0",
     "@react-native-community/cli-config-android": "^20.0.0",
-    "@rock-js/platform-android": "^0.12.12",
-    "@rock-js/platform-apple-helpers": "^0.12.12",
-    "@rock-js/plugin-brownfield-android": "^0.12.12",
-    "@rock-js/plugin-brownfield-ios": "^0.12.12",
-    "@rock-js/tools": "^0.12.12",
+    "@rock-js/platform-android": "^0.13.3",
+    "@rock-js/platform-apple-helpers": "^0.13.3",
+    "@rock-js/plugin-brownfield-android": "^0.13.3",
+    "@rock-js/plugin-brownfield-ios": "^0.13.3",
+    "@rock-js/tools": "^0.13.3",
     "commander": "^14.0.3",
     "quicktype-core": "^23.2.6",
     "quicktype-typescript-input": "^23.2.6",

package/src/brownfield/commands/packageIos.ts

@@ -8,16 +8,18 @@ import {
 } from '@rock-js/platform-apple-helpers';
 import { packageIosAction } from '@rock-js/plugin-brownfield-ios';
 import {
+  RockError,
   colorLink,
   getReactNativeVersion,
   logger,
   relativeToCwd,
 } from '@rock-js/tools';
 
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 
 import { runExpoPrebuildIfNeeded } from '../utils/expo.js';
 import { getProjectInfo } from '../utils/project.js';
+import { supportsPrebuiltRNCore } from '../utils/supportsPrebuiltRNCore.js';
 import {
   actionRunner,
   curryOptions,
@@ -27,6 +29,36 @@ import { runBrownieCodegenIfApplicable } from '../../brownie/helpers/runBrownieC
 import { runNavigationCodegenIfApplicable } from '../../navigation/helpers/runNavigationCodegenIfApplicable.js';
 import { stripFrameworkBinary } from '../utils/stripFrameworkBinary.js';
 
+/** Help text for `--use-prebuilt-rn-core` (keep in sync with docs/docs/docs/getting-started/ios.mdx, "React Native Prebuilts" section). */
+const USE_PREBUILT_RN_CORE_HELP =
+  'Whether the Xcode build for packaging should use React Native Apple prebuilt binaries (via CocoaPods). ' +
+  'If you omit this flag, Brownfield follows version-aware defaults: for React Native 0.84 and newer, prebuilts are enabled by default; for RN 0.83, they are disabled unless you opt in. ' +
+  'Pass true or false to force either behavior. Use the flag without a value as shorthand for true (same as `--use-prebuilt-rn-core true`). ' +
+  'See the Brownfield iOS guide for details: https://oss.callstack.com/react-native-brownfield/docs/getting-started/ios#react-native-prebuilts';
+
+export function parseUsePrebuiltRnCoreArgument(
+  value: string | boolean
+): boolean {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === 'true' || normalized === '1') {
+    return true;
+  }
+  if (normalized === 'false' || normalized === '0') {
+    return false;
+  }
+  throw new RockError(
+    `Invalid value for --use-prebuilt-rn-core: expected true or false, received "${value}"`
+  );
+}
+
+type PackageIosCliFlags = AppleBuildFlags & {
+  /** Set when `--use-prebuilt-rn-core` is passed; omitted when the flag is absent (Rock applies RN version defaults). */
+  usePrebuiltRnCore?: boolean;
+};
+
 export const packageIosCommand = curryOptions(
   new Command('package:ios').description('Build iOS XCFramework'),
   getBuildOptions({ platformName: 'ios' }).map((option) =>
@@ -39,139 +71,184 @@ export const packageIosCommand = curryOptions(
         }
       : option
   )
-).action(
-  actionRunner(async (options: AppleBuildFlags) => {
-    const { projectRoot, platformConfig, userConfig } = getProjectInfo('ios');
-    await runExpoPrebuildIfNeeded({ projectRoot, platform: 'ios' });
-
-    if (!userConfig.project.ios) {
-      throw new Error('iOS project not found.');
-    }
-
-    if (!userConfig.project.ios.xcodeProject) {
-      throw new Error('iOS Xcode project not found in the configuration.');
-    }
-
-    let dotBrownfieldDir = path.join(
-      // for Expo projects, platformConfig?.sourceDir == "", but for non-Expo projects, it's "ios"
-      ...(userConfig.project.ios.sourceDir.trim().length > 0
-        ? [userConfig.project.ios.sourceDir]
-        : [projectRoot, 'ios']),
-      '.brownfield'
-    );
-
-    // non-Expo projects have a relative sourceDir path, so we need to make it absolute
-    if (!path.isAbsolute(dotBrownfieldDir)) {
-      dotBrownfieldDir = path.join(projectRoot, dotBrownfieldDir);
-    }
-
-    options.buildFolder ??= path.join(dotBrownfieldDir, 'build');
-
-    // The new_architecture.rb script scans Info.plist and fails on binary plist files,
-    // which is the case for our XCFrameworks.
-    // We're reusing the "build" directory which is excluded from the scan.
-    // Reference: https://github.com/facebook/react-native/blob/490c5e8dcc6cdb19c334cc39e93a39a48ba71e96/packages/react-native/scripts/cocoapods/new_architecture.rb#L171
-    const packageDir = path.join(dotBrownfieldDir, 'package', 'build');
-    const configuration = options.configuration ?? 'Debug';
-
-    const { hasBrownie } = await runBrownieCodegenIfApplicable(
-      projectRoot,
-      'swift'
-    );
-    const { hasNavigation } = await runNavigationCodegenIfApplicable(projectRoot);
-
-    await packageIosAction(
-      options,
-      {
+)
+  .addOption(
+    new Option('--use-prebuilt-rn-core [bool]', USE_PREBUILT_RN_CORE_HELP)
+      .preset(true)
+      .argParser(parseUsePrebuiltRnCoreArgument)
+  )
+  .action(
+    actionRunner(async (options: PackageIosCliFlags) => {
+      const { projectRoot, platformConfig, userConfig } = getProjectInfo('ios');
+
+      const prebuiltRNCoreSupport = supportsPrebuiltRNCore({ projectRoot });
+
+      // version-aware default when the flag is omitted (see ios.mdx "React Native Prebuilts")
+      options.usePrebuiltRnCore ??= prebuiltRNCoreSupport.supported
+        ? prebuiltRNCoreSupport.enabledByDefault
+        : false;
+
+      if (prebuiltRNCoreSupport) {
+        logger.info(
+          `${options.usePrebuiltRnCore ? 'Using' : 'Not using'} prebuilt RN core`
+        );
+
+        if (
+          !prebuiltRNCoreSupport.enabledByDefault &&
+          !options.usePrebuiltRnCore
+        ) {
+          logger.info(
+            'Your environment supports prebuilt RN Core as an opt-in feature, but it is disabled by default. Pass --use-prebuilt-rn-core to enable it.'
+          );
+        }
+      }
+
+      if (options.usePrebuiltRnCore && !prebuiltRNCoreSupport.supported) {
+        throw new RockError(prebuiltRNCoreSupport.reason);
+      }
+
+      await runExpoPrebuildIfNeeded({ projectRoot, platform: 'ios' });
+
+      if (!userConfig.project.ios) {
+        throw new Error('iOS project not found.');
+      }
+
+      if (!userConfig.project.ios.xcodeProject) {
+        throw new Error('iOS Xcode project not found in the configuration.');
+      }
+
+      let dotBrownfieldDir = path.join(
+        // for Expo projects, platformConfig?.sourceDir == "", but for non-Expo projects, it's "ios"
+        ...(userConfig.project.ios.sourceDir.trim().length > 0
+          ? [userConfig.project.ios.sourceDir]
+          : [projectRoot, 'ios']),
+        '.brownfield'
+      );
+
+      // non-Expo projects have a relative sourceDir path, so we need to make it absolute
+      if (!path.isAbsolute(dotBrownfieldDir)) {
+        dotBrownfieldDir = path.join(projectRoot, dotBrownfieldDir);
+      }
+
+      options.buildFolder ??= path.join(dotBrownfieldDir, 'build');
+      options.verbose ??= logger.isVerbose();
+
+      // The new_architecture.rb script scans Info.plist and fails on binary plist files,
+      // which is the case for our XCFrameworks.
+      // We're reusing the "build" directory which is excluded from the scan.
+      // Reference: https://github.com/facebook/react-native/blob/490c5e8dcc6cdb19c334cc39e93a39a48ba71e96/packages/react-native/scripts/cocoapods/new_architecture.rb#L171
+      const packageDir = path.join(dotBrownfieldDir, 'package', 'build');
+      const configuration = options.configuration ?? 'Debug';
+
+      const { hasBrownie } = await runBrownieCodegenIfApplicable(
         projectRoot,
-        reactNativePath: userConfig.reactNativePath,
-        // below: the userConfig.reactNativeVersion may be a non-semver-format string,
-        // e.g. '0.82' (note the missing patch component),
-        // therefore we resolve it manually from RN's package.json using Rock's utils
-        reactNativeVersion: getReactNativeVersion(projectRoot),
-        usePrebuiltRNCore: false, // for brownfield, it is required to build RN from source
-        packageDir, // the output directory for artifacts
-        skipCache: true, // cache is dependent on existence of Rock config file
-      },
-      platformConfig
-    );
-
-    const reactBrownfieldXcframeworkPath = path.join(
-      packageDir,
-      'ReactBrownfield.xcframework'
-    );
-    if (fs.existsSync(reactBrownfieldXcframeworkPath)) {
-      // Strip the binary from ReactBrownfield.xcframework to make it interface-only.
-      // This avoids duplicate symbols when consumer apps embed both BrownfieldLib
-      // (which contains ReactBrownfield symbols) and ReactBrownfield.xcframework.
-      stripFrameworkBinary(reactBrownfieldXcframeworkPath);
-    }
-
-    if (hasBrownie) {
-      const productsPath = path.join(options.buildFolder, 'Build', 'Products');
-      const brownieOutputPath = path.join(packageDir, 'Brownie.xcframework');
-
-      await mergeFrameworks({
-        sourceDir: userConfig.project.ios.sourceDir,
-        frameworkPaths: [
-          path.join(
-            productsPath,
-            `${configuration}-iphoneos`,
-            'Brownie',
-            'Brownie.framework'
-          ),
-          path.join(
-            productsPath,
-            `${configuration}-iphonesimulator`,
-            'Brownie',
-            'Brownie.framework'
-          ),
-        ],
-        outputPath: brownieOutputPath,
-      });
-
-      // Strip the binary from Brownie.xcframework to make it interface-only.
-      // This avoids duplicate symbols when consumer apps embed both BrownfieldLib
-      // (which contains Brownie symbols) and Brownie.xcframework.
-      stripFrameworkBinary(brownieOutputPath);
-
-      logger.success(
-        `Brownie.xcframework created at ${colorLink(relativeToCwd(brownieOutputPath))}`
+        'swift'
+      );
+      const { hasNavigation } =
+        await runNavigationCodegenIfApplicable(projectRoot);
+
+      await packageIosAction(
+        options,
+        {
+          projectRoot,
+          reactNativePath: userConfig.reactNativePath,
+          // below: the userConfig.reactNativeVersion may be a non-semver-format string,
+          // e.g. '0.82' (note the missing patch component),
+          // therefore we resolve it manually from RN's package.json using Rock's utils
+          reactNativeVersion: getReactNativeVersion(projectRoot),
+          packageDir, // the output directory for artifacts
+          skipCache: true, // cache is dependent on existence of Rock config file
+          usePrebuiltRNCore: options.usePrebuiltRnCore,
+        },
+        platformConfig
       );
-    }
-
-    if (hasNavigation) {
-      const productsPath = path.join(options.buildFolder, 'Build', 'Products');
-      const brownfieldNavigationOutputPath = path.join(packageDir, 'BrownfieldNavigation.xcframework');
-  
-      await mergeFrameworks({
-        sourceDir: userConfig.project.ios.sourceDir,
-        frameworkPaths: [
-          path.join(
-            productsPath,
-            `${configuration}-iphoneos`,
-            'BrownfieldNavigation',
-            'BrownfieldNavigation.framework'
-          ),
-          path.join(
-            productsPath,
-            `${configuration}-iphonesimulator`,
-            'BrownfieldNavigation',
-            'BrownfieldNavigation.framework'
-          ),
-        ],
-        outputPath: brownfieldNavigationOutputPath,
-      });
-  
-  
-      stripFrameworkBinary(brownfieldNavigationOutputPath);
-  
-      logger.success(
-        `BrownfieldNavigation.xcframework created at ${colorLink(relativeToCwd(brownfieldNavigationOutputPath))}`
+
+      const reactBrownfieldXcframeworkPath = path.join(
+        packageDir,
+        'ReactBrownfield.xcframework'
       );
-    }
-  })
-);
+      if (fs.existsSync(reactBrownfieldXcframeworkPath)) {
+        // Strip the binary from ReactBrownfield.xcframework to make it interface-only.
+        // This avoids duplicate symbols when consumer apps embed both BrownfieldLib
+        // (which contains ReactBrownfield symbols) and ReactBrownfield.xcframework.
+        stripFrameworkBinary(reactBrownfieldXcframeworkPath);
+      }
+
+      if (hasBrownie) {
+        const productsPath = path.join(
+          options.buildFolder,
+          'Build',
+          'Products'
+        );
+        const brownieOutputPath = path.join(packageDir, 'Brownie.xcframework');
+
+        await mergeFrameworks({
+          sourceDir: userConfig.project.ios.sourceDir,
+          frameworkPaths: [
+            path.join(
+              productsPath,
+              `${configuration}-iphoneos`,
+              'Brownie',
+              'Brownie.framework'
+            ),
+            path.join(
+              productsPath,
+              `${configuration}-iphonesimulator`,
+              'Brownie',
+              'Brownie.framework'
+            ),
+          ],
+          outputPath: brownieOutputPath,
+        });
+
+        // Strip the binary from Brownie.xcframework to make it interface-only.
+        // This avoids duplicate symbols when consumer apps embed both BrownfieldLib
+        // (which contains Brownie symbols) and Brownie.xcframework.
+        stripFrameworkBinary(brownieOutputPath);
+
+        logger.success(
+          `Brownie.xcframework created at ${colorLink(relativeToCwd(brownieOutputPath))}`
+        );
+      }
+
+      if (hasNavigation) {
+        const productsPath = path.join(
+          options.buildFolder,
+          'Build',
+          'Products'
+        );
+        const brownfieldNavigationOutputPath = path.join(
+          packageDir,
+          'BrownfieldNavigation.xcframework'
+        );
+
+        await mergeFrameworks({
+          sourceDir: userConfig.project.ios.sourceDir,
+          frameworkPaths: [
+            path.join(
+              productsPath,
+              `${configuration}-iphoneos`,
+              'BrownfieldNavigation',
+              'BrownfieldNavigation.framework'
+            ),
+            path.join(
+              productsPath,
+              `${configuration}-iphonesimulator`,
+              'BrownfieldNavigation',
+              'BrownfieldNavigation.framework'
+            ),
+          ],
+          outputPath: brownfieldNavigationOutputPath,
+        });
+
+        stripFrameworkBinary(brownfieldNavigationOutputPath);
+
+        logger.success(
+          `BrownfieldNavigation.xcframework created at ${colorLink(relativeToCwd(brownfieldNavigationOutputPath))}`
+        );
+      }
+    })
+  );
 
 export const packageIosExample = new ExampleUsage(
   'package:ios --scheme BrownfieldLib --configuration Release',

package/src/brownfield/utils/project.ts

@@ -56,6 +56,15 @@ export function isExpoProject(projectRoot: string): boolean {
   return hasExpoConfig && dependsOnExpo;
 }
 
+export function getExpoSdkMajor(projectRoot: string): number | null {
+  const rawExpoVersion = getExpoConfigIfIsExpo(projectRoot)?.exp.sdkVersion;
+  if (!rawExpoVersion) {
+    return null;
+  }
+  const expoSdkMajor = parseInt(rawExpoVersion.split('.')[0], 10);
+  return Number.isFinite(expoSdkMajor) ? expoSdkMajor : null;
+}
+
 /**
  * Fills the RNC CLI project config from the Expo config by mutating the passed in `options.projectConfig` object in place
  */

package/src/brownfield/utils/supportsPrebuiltRNCore.ts

@@ -0,0 +1,67 @@
+import { getReactNativeVersion, versionCompare } from '@rock-js/tools';
+
+import { getExpoSdkMajor, isExpoProject } from './project.js';
+
+/** Minimum RN version that can opt in to prebuilts via `--use-prebuilt-rn-core`. */
+export const MIN_REACT_NATIVE_VERSION_FOR_OPT_IN_PREBUILT_RN_CORE = '0.81.0';
+/** Minimum RN version where Brownfield enables prebuilts by default (vanilla projects). */
+export const MIN_REACT_NATIVE_VERSION_FOR_PREBUILT_RN_CORE_BY_DEFAULT =
+  '0.84.0';
+export const MIN_EXPO_SDK_MAJOR_FOR_PREBUILT_RN_CORE_BY_DEFAULT = 55;
+
+export type PrebuiltRNCoreSupportResult =
+  | { supported: true; enabledByDefault: boolean; reason?: never }
+  | { supported: false; enabledByDefault?: never; reason: string };
+
+export function supportsPrebuiltRNCore({
+  projectRoot,
+}: {
+  projectRoot: string;
+}): PrebuiltRNCoreSupportResult {
+  const reactNativeVersion = getReactNativeVersion(projectRoot);
+
+  if (reactNativeVersion === 'unknown') {
+    return {
+      supported: false,
+      reason:
+        'Cannot use --use-prebuilt-rn-core: unable to resolve the installed react-native version.',
+    };
+  }
+
+  if (
+    versionCompare(
+      reactNativeVersion,
+      MIN_REACT_NATIVE_VERSION_FOR_OPT_IN_PREBUILT_RN_CORE
+    ) < 0
+  ) {
+    return {
+      supported: false,
+      reason: `--use-prebuilt-rn-core requires React Native ${MIN_REACT_NATIVE_VERSION_FOR_OPT_IN_PREBUILT_RN_CORE} or newer (found ${reactNativeVersion}).`,
+    };
+  }
+
+  if (isExpoProject(projectRoot)) {
+    const expoSdkMajor = getExpoSdkMajor(projectRoot);
+
+    if (
+      expoSdkMajor === null ||
+      expoSdkMajor < MIN_EXPO_SDK_MAJOR_FOR_PREBUILT_RN_CORE_BY_DEFAULT
+    ) {
+      const sdkLabel = expoSdkMajor === null ? 'unknown' : String(expoSdkMajor);
+      return {
+        supported: false,
+        reason: `--use-prebuilt-rn-core is unsupported in Expo SDK ${sdkLabel}: packaging brownfield with prebuilts requires Expo SDK ${MIN_EXPO_SDK_MAJOR_FOR_PREBUILT_RN_CORE_BY_DEFAULT} or newer.`,
+      };
+    }
+
+    return { supported: true, enabledByDefault: true };
+  }
+
+  const enabledByDefault =
+    versionCompare(
+      reactNativeVersion,
+      MIN_REACT_NATIVE_VERSION_FOR_PREBUILT_RN_CORE_BY_DEFAULT
+    ) >= 0;
+
+  return { supported: true, enabledByDefault };
+}