Skip to content

chore(docs): improve Expo CLI metro.config.js instructions #2758

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 11, 2025
Merged

chore(docs): improve Expo CLI metro.config.js instructions #2758

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 40 additions & 3 deletions docsite/docs/guides/installing-expo-modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,15 +69,46 @@ We recommend using Expo CLI and related tooling configurations to bundle your ap
+ presets: ['babel-preset-expo'],
```

#### Extend expo/metro-config in your metro.config.js
#### Extend expo/metro-config in your metro.config.js and resolve react-native-macos

```diff metro.config.js
-const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
+const { getDefaultConfig } = require('expo/metro-config');
+const { mergeConfig } = require('@react-native/metro-config');
+const {getDefaultConfig} = require('expo/metro-config');

/**
* Metro configuration

-const config = {};
+const config = getDefaultConfig(__dirname);

-module.exports = mergeConfig(getDefaultConfig(__dirname), config);
+config.resolver.resolveRequest = (context, moduleName, platform) => {
+ if (
+ platform === 'macos' &&
+ (moduleName === 'react-native' || moduleName.startsWith('react-native/'))
+ ) {
+ const newModuleName = moduleName.replace(
+ 'react-native',
+ 'react-native-macos',
+ );
+ return context.resolveRequest(context, newModuleName, platform);
+ }
+ return context.resolveRequest(context, moduleName, platform);
+};
+
+const originalGetModulesRunBeforeMainModule =
+ config.serializer.getModulesRunBeforeMainModule;
+config.serializer.getModulesRunBeforeMainModule = () => {
+ try {
+ return [
+ require.resolve('react-native/Libraries/Core/InitializeCore'),
+ require.resolve('react-native-macos/Libraries/Core/InitializeCore'),
+ ];
+ } catch {}
+ return originalGetModulesRunBeforeMainModule();
+};
+
+module.exports = config;
```

#### Configure macOS project to bundle with Expo CLI
Expand Down Expand Up @@ -127,6 +158,12 @@ And add support the `"main"` field in **package.json** by making the following c
#endif
```

Finally, to start the Metro bundler using Expo CLI, run: `npx expo start` or replace your existing `start` command in `package.json`:

```diff package.json
- "start": "react-native start",
+ "start": "expo start",
```

## Usage

Expand Down
Loading