fix: support Expo modules in React Native CLI apps

.changeset/bare-app-skip-expo-prebuild.md

@@ -0,0 +1,15 @@
+---
+'@callstack/brownfield-cli': patch
+'@callstack/react-native-brownfield': patch
+'@callstack/create-react-native-brownfield': patch
+---
+
+Support Expo modules in React Native CLI apps. `brownfield package:*` no longer runs `expo prebuild` on projects with committed `android/` and `ios/` directories, which used to delete the brownfield library module. Prebuild now runs only when the native directory is missing or gitignored. If you commit the generated directories of an Expo app, run `npx expo prebuild` yourself after changing `app.json` or config plugins. `create-react-native-brownfield` now detects Expo and sets up the iOS framework to use the Expo runtime. On a re-run after adding Expo, it also raises an existing framework target to iOS 16.4.
+
+`--use-prebuilt-expo` now also turns Expo's precompiled modules on or off for `pod install`, and turns on Swift explicit modules so packaging works in projects that still carry the old `SWIFT_ENABLE_EXPLICIT_MODULES = NO` workaround. It defaults to building Expo from source when the app's React Native version doesn't match the one Expo's precompiled modules were built for.
+
+`package:ios` now copies the expo-image dependency XCFrameworks (SDWebImage and libavif) as real files instead of symlinks into `node_modules`, so the package works when moved to another machine.
+
+Re-running `create-react-native-brownfield` after `pod install` no longer adds a second Sources build phase to the framework target, which made the next `pod install` fail.
+
+The `package:ios` script that `create-react-native-brownfield` adds now passes `--add-spm-package`, so the iOS app adds one local Swift package instead of every XCFramework. Existing scripts aren't changed.

docs/docs/docs/getting-started/ios.mdx

@@ -166,6 +166,7 @@ That command writes `Package.swift` into the same `ios/.brownfield/package/build
         - These are required with the PreCompiled Expo option enabled. If it's disabled, only `ExpoModulesJSI.xcframework` is required to be linked.
      - `libavif.xcframework` | `SDWebImage.xcframework` | `SDWebImageAVIFCoder.xcframework` | `SDWebImageSVGCoder.xcframework` and `SDWebImageWebPCoder.xcframework`
         - These are required to be linked for `ExpoImage` to work correctly.
+     - In a React Native CLI app that uses Expo modules, also see [Expo Modules in React Native CLI Apps](/docs/guides/expo-modules).
 
 ![Expo Frameworks in Xcode Sidebar](/images/expo-frameworks.png)
 
@@ -341,11 +342,9 @@ When using the `--use-prebuilt-rn-core` flag:
 
 ## Expo Prebuilts
 
-Starting Expo SDK 56, the prebuilts for expo modules are enabled by default. If you wish to opt out of prebuilt, pass the `--use-prebuilt-expo false` flag to the brownfield CLI.
+Starting with Expo SDK 56, Brownfield uses Expo's [precompiled modules](https://docs.expo.dev/guides/prebuilt-expo-modules/) by default. To build Expo modules from source instead, pass `--use-prebuilt-expo false`. The flag also sets `EXPO_USE_PRECOMPILED_MODULES` for `pod install`, so you don't need to change your `Podfile`. Without the flag, Brownfield also builds from source when you export `EXPO_USE_PRECOMPILED_MODULES=0` or when `ios/Podfile.properties.json` sets it to `"false"`. Expo's Podfile always honors that property, so remove it if you want precompiled modules.
 
-:::info
-The above only instructs the brownfield CLI whether to use prebuilt. You also need to disable prebuilt for Expo. See the [guide](https://docs.expo.dev/guides/prebuilt-expo-modules/)
-:::
+Expo builds its precompiled modules against the React Native version your Expo SDK targets. If your app uses a different React Native minor version, Brownfield builds Expo modules from source by default, because precompiled ones would crash at runtime.
 
 
 ## Next Steps

docs/docs/docs/getting-started/rnc-cli.mdx

@@ -66,7 +66,7 @@ After the setup command, install dependencies and run the packaging scripts it a
 
 <PackageManagerTabs command="run package:android" />
 
-`package:ios` writes the XCFramework to `ios/.brownfield/package/build/`; `package:android` builds the Fat-AAR. Both read their settings from `brownfield.config.json`, so no flags are needed. See [Configuration files](/docs/api-reference/configuration) to customize them.
+`package:ios` writes a local Swift package to `ios/.brownfield/package/build/`, which your iOS app adds in one step (see [Add as a Local Swift Package](/docs/getting-started/ios#optional-add-as-a-local-swift-package)). To get only the XCFrameworks, run `npx brownfield package:ios` instead. `package:android` builds the Fat-AAR. Both read their settings from `brownfield.config.json`, so no flags are needed. See [Configuration files](/docs/api-reference/configuration) to customize them.
 
 ## Integrate With Your Native App
 
@@ -77,6 +77,10 @@ Embedding the artifact in your native app is a manual step, and the guides below
 
 Both guides also describe the manual alternative in full, so you can use them to check the generated wiring or to customize it beyond what the command offers.
 
+:::tip Using Expo modules?
+If your app uses Expo modules such as `expo-image`, complete the extra steps in [Expo Modules in React Native CLI Apps](/docs/guides/expo-modules) before you package.
+:::
+
 ## Next Steps
 
 - [iOS API Reference](/docs/api-reference/react-native-brownfield/swift)

docs/docs/docs/guides/_meta.json

@@ -1,6 +1,7 @@
 [
   "guidelines",
   "minification",
+  "expo-modules",
   "performance-metrics",
   "troubleshooting",
   {

docs/docs/docs/guides/expo-modules.mdx

@@ -0,0 +1,53 @@
+import { PackageManagerTabs } from '@theme';
+
+# Expo Modules in React Native CLI Apps
+
+This guide is for React Native Community CLI apps that use Expo modules, such as `expo-image`, installed with `npx install-expo-modules`. Apps without Expo modules don't need any of these steps. Expo apps that use `expo prebuild` should follow [Expo Integration](/docs/getting-started/expo) instead.
+
+Complete [React Native CLI Integration](/docs/getting-started/rnc-cli) first. The Brownfield CLI then packages Expo modules with the rest of your app.
+
+## Android
+
+No extra setup is needed. If your app has product flavors, see [Troubleshooting](/docs/guides/troubleshooting) for setting `missingDimensionStrategy`.
+
+## iOS
+
+On iOS, Expo modules only work when React Native starts through Brownfield's Expo runtime. You set this up once in your React Native project, then update your native iOS app.
+
+### In your React Native project
+
+1. Install Expo modules with `npx install-expo-modules`, if you haven't already. It also raises the `platform :ios` line in `ios/Podfile` to iOS 16.4, which Expo SDK 56 and newer require.
+2. From the project root, run the command from [Automated Setup](/docs/getting-started/rnc-cli#automated-setup). If you ran it before you added Expo, run it again. It only changes what's missing.
+
+   <PackageManagerTabs command="create @callstack/react-native-brownfield@latest" />
+
+   Because your `package.json` depends on `expo`, the command:
+   - adds `ENV['REACT_NATIVE_BROWNFIELD_USE_EXPO_HOST'] = '1'` to the framework target in `ios/Podfile`
+   - adds `ensureExpoModulesProvider()` to `ios/<framework_target_name>/<framework_target_name>.swift`
+   - raises the framework target to iOS 16.4 if it uses an older version
+
+3. Package your app as a local Swift package:
+
+   <PackageManagerTabs command="run package:ios" />
+
+   The `package:ios` script from the setup command passes `--add-spm-package`. If your script was added before that, run `npx brownfield package:ios --add-spm-package` instead.
+
+   Expo's precompiled modules only work with the React Native version your Expo SDK targets. With a different version, Brownfield builds them from source. See [Expo Prebuilts](/docs/getting-started/ios#expo-prebuilts).
+
+### In your native iOS app
+
+1. Add the package. It includes your framework, React Native and every Expo framework, so you don't have to add XCFrameworks one by one:
+   1. In Xcode, choose **File > Add Package Dependencies...**, click **Add Local...** and select `ios/.brownfield/package/build`.
+   2. In your app target's **General** tab, add the `<framework_target_name>` product under **Frameworks, Libraries, and Embedded Content**.
+
+   If you'd rather add the XCFrameworks by hand, run `npx brownfield package:ios` without `--add-spm-package` and follow [Add the Framework to Your iOS App](/docs/getting-started/ios#7-add-the-framework-to-your-ios-app).
+
+2. Call `ensureExpoModulesProvider()` before you start React Native:
+
+```swift
+ReactNativeBrownfield.shared.bundle = ReactNativeBundle
+ReactNativeBrownfield.shared.ensureExpoModulesProvider()
+ReactNativeBrownfield.shared.startReactNative { _ in
+  print("React Native has been loaded")
+}
+```

packages/cli/src/brownfield/commands/__tests__/packageIos.action.test.ts

@@ -2,14 +2,26 @@ import * as appleHelpers from '@rock-js/platform-apple-helpers';
 import { packageIosAction } from '@rock-js/plugin-brownfield-ios';
 import * as rockTools from '@rock-js/tools';
 
-import { beforeEach, describe, expect, test, vi, type Mock } from 'vitest';
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  test,
+  vi,
+  type Mock,
+} from 'vitest';
 
 import { packageIosCommand } from '../packageIos.js';
 import { copyDebugBundleToSimulatorSlice } from '../../utils/copyDebugBundleToSimulatorSlice.js';
 import { createLocalSpmPackage } from '../../utils/createLocalSpmPackage.js';
 import { emitExpoSupportXcframeworks } from '../../utils/emitExpoSupportXcframeworks.js';
 import { resolvePackagedFrameworkName } from '../../utils/resolvePackagedFrameworkName.js';
-import { supportsPrebuiltExpo } from '../../utils/supportsPrebuiltExpo.js';
+import { isExpoProject } from '../../utils/project.js';
+import {
+  isPrecompiledExpoDisabledByPodfile,
+  supportsPrebuiltExpo,
+} from '../../utils/supportsPrebuiltExpo.js';
 
 vi.mock('@rock-js/platform-apple-helpers', async (importOriginal) => {
   const actual = await importOriginal<typeof appleHelpers>();
@@ -24,6 +36,11 @@ vi.mock('@rock-js/platform-apple-helpers', async (importOriginal) => {
         name: '--scheme <scheme>',
         description: 'test scheme option',
       },
+      {
+        name: '--extra-params <string>',
+        description: 'test extra params option',
+        parse: (value: string) => value.split(' '),
+      },
     ]),
     mergeFrameworks: vi.fn(),
   };
@@ -64,6 +81,7 @@ vi.mock('../../utils/paths.js', () => ({
 }));
 
 vi.mock('../../utils/project.js', () => ({
+  isExpoProject: vi.fn(() => false),
   getProjectInfo: vi.fn(() => ({
     projectRoot: '/repo',
     platformConfig: {},
@@ -84,12 +102,13 @@ vi.mock('../../utils/project.js', () => ({
 vi.mock('../../utils/supportsPrebuiltRNCore.js', () => ({
   supportsPrebuiltRNCore: vi.fn(() => ({
     supported: true,
-    enabledByDefault: false,
+    enabledByDefault: true,
     reason: '',
   })),
 }));
 
 vi.mock('../../utils/supportsPrebuiltExpo.js', () => ({
+  isPrecompiledExpoDisabledByPodfile: vi.fn(() => false),
   supportsPrebuiltExpo: vi.fn(() => ({
     supported: true,
     enabledByDefault: true,
@@ -167,9 +186,17 @@ const mockEmitExpoSupportXcframeworks = emitExpoSupportXcframeworks as Mock;
 const mockResolvePackagedFrameworkName = resolvePackagedFrameworkName as Mock;
 const mockSupportsPrebuiltExpo = supportsPrebuiltExpo as Mock;
 
+const originalPrecompiledModules = process.env.EXPO_USE_PRECOMPILED_MODULES;
+
 describe('package:ios action --add-spm-package', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    delete process.env.EXPO_USE_PRECOMPILED_MODULES;
+    (isExpoProject as Mock).mockReturnValue(false);
+    (isPrecompiledExpoDisabledByPodfile as Mock).mockReturnValue(false);
+    for (const option of ['usePrebuiltExpo', 'extraParams']) {
+      packageIosCommand.setOptionValue(option, undefined);
+    }
 
     mockResolvePackagedFrameworkName.mockReturnValue({
       frameworkName: 'BrownfieldLib',
@@ -187,6 +214,14 @@ describe('package:ios action --add-spm-package', () => {
     mockEmitExpoSupportXcframeworks.mockReturnValue(false);
   });
 
+  afterEach(() => {
+    if (originalPrecompiledModules === undefined) {
+      delete process.env.EXPO_USE_PRECOMPILED_MODULES;
+    } else {
+      process.env.EXPO_USE_PRECOMPILED_MODULES = originalPrecompiledModules;
+    }
+  });
+
   test('calls createLocalSpmPackage with the resolved framework name', async () => {
     await invokePackageIosAction([
       '--add-spm-package',
@@ -294,4 +329,136 @@ describe('package:ios action --add-spm-package', () => {
       mockEmitExpoSupportXcframeworks.mock.invocationCallOrder[0]
     ).toBeLessThan(mockCreateLocalSpmPackage.mock.invocationCallOrder[0] ?? 0);
   });
+
+  test('turns on precompiled Expo modules and explicit modules when using prebuilt Expo', async () => {
+    (isExpoProject as Mock).mockReturnValue(true);
+
+    await invokePackageIosAction([
+      '--use-prebuilt-expo',
+      'true',
+      '--configuration',
+      'Release',
+    ]);
+
+    expect(process.env.EXPO_USE_PRECOMPILED_MODULES).toBe('1');
+    expect(packageIosAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        extraParams: expect.arrayContaining([
+          'SWIFT_ENABLE_EXPLICIT_MODULES=YES',
+        ]),
+      }),
+      expect.anything(),
+      expect.anything()
+    );
+  });
+
+  test('turns off precompiled Expo modules when building Expo from source', async () => {
+    (isExpoProject as Mock).mockReturnValue(true);
+
+    await invokePackageIosAction([
+      '--use-prebuilt-expo',
+      'false',
+      '--configuration',
+      'Release',
+    ]);
+
+    expect(process.env.EXPO_USE_PRECOMPILED_MODULES).toBe('0');
+  });
+  test('builds Expo from source by default when the React Native version does not match', async () => {
+    (isExpoProject as Mock).mockReturnValue(true);
+    mockSupportsPrebuiltExpo.mockReturnValue({
+      supported: true,
+      enabledByDefault: false,
+      defaultDisabledReason: 'Version mismatch.',
+    });
+
+    await invokePackageIosAction(['--configuration', 'Release']);
+
+    expect(process.env.EXPO_USE_PRECOMPILED_MODULES).toBe('0');
+    expect(mockLoggerInfo).toHaveBeenCalledWith(
+      'Version mismatch. Building Expo modules from source.'
+    );
+    expect(mockLoggerWarn).not.toHaveBeenCalled();
+  });
+
+  test('warns when prebuilt Expo is forced despite a React Native version mismatch', async () => {
+    (isExpoProject as Mock).mockReturnValue(true);
+    mockSupportsPrebuiltExpo.mockReturnValue({
+      supported: true,
+      enabledByDefault: false,
+      defaultDisabledReason: 'Version mismatch.',
+    });
+
+    await invokePackageIosAction([
+      '--use-prebuilt-expo',
+      'true',
+      '--configuration',
+      'Release',
+    ]);
+
+    expect(process.env.EXPO_USE_PRECOMPILED_MODULES).toBe('1');
+    expect(mockLoggerWarn).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'Version mismatch. The packaged app will likely crash'
+      )
+    );
+  });
+
+  test('builds Expo from source when Podfile.properties.json turns precompiled modules off', async () => {
+    (isExpoProject as Mock).mockReturnValue(true);
+    (isPrecompiledExpoDisabledByPodfile as Mock).mockReturnValue(true);
+
+    await invokePackageIosAction(['--configuration', 'Release']);
+
+    expect(process.env.EXPO_USE_PRECOMPILED_MODULES).toBe('0');
+    expect(mockEmitExpoSupportXcframeworks).toHaveBeenCalledWith(
+      expect.objectContaining({ usePrebuiltExpo: false })
+    );
+  });
+
+  test('warns when prebuilt Expo is forced but Podfile.properties.json turns it off', async () => {
+    (isExpoProject as Mock).mockReturnValue(true);
+    (isPrecompiledExpoDisabledByPodfile as Mock).mockReturnValue(true);
+
+    await invokePackageIosAction([
+      '--use-prebuilt-expo',
+      'true',
+      '--configuration',
+      'Release',
+    ]);
+
+    expect(mockLoggerWarn).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'ios/Podfile.properties.json sets EXPO_USE_PRECOMPILED_MODULES'
+      )
+    );
+  });
+
+  test('respects an exported EXPO_USE_PRECOMPILED_MODULES=0 when the flag is omitted', async () => {
+    (isExpoProject as Mock).mockReturnValue(true);
+    process.env.EXPO_USE_PRECOMPILED_MODULES = '0';
+
+    await invokePackageIosAction(['--configuration', 'Release']);
+
+    expect(process.env.EXPO_USE_PRECOMPILED_MODULES).toBe('0');
+    expect(mockEmitExpoSupportXcframeworks).toHaveBeenCalledWith(
+      expect.objectContaining({ usePrebuiltExpo: false })
+    );
+  });
+
+  test('keeps a user-provided SWIFT_ENABLE_EXPLICIT_MODULES value', async () => {
+    (isExpoProject as Mock).mockReturnValue(true);
+
+    await invokePackageIosAction([
+      '--use-prebuilt-expo',
+      'true',
+      '--extra-params',
+      'SWIFT_ENABLE_EXPLICIT_MODULES=NO',
+      '--configuration',
+      'Release',
+    ]);
+
+    const [options] = (packageIosAction as Mock).mock.calls[0];
+    expect(options.extraParams).toEqual(['SWIFT_ENABLE_EXPLICIT_MODULES=NO']);
+  });
 });