Support ESM `react-native.config` files

[kraenhansen]

Describe the Feature

I'd love to use modern ESM code in my React Native apps and libraries. The CLI's config package currently blocks having "type": "module" in a React Native app or library package, because the config command loads config files synchronous, with a ~ 5 year old version of cosmiconfig.

Setting "type": "module" in a package.json of an app or dependency yields the following error:

error Failed to load configuration of your project. Error [ERR_REQUIRE_ESM]: require() of ES Module {...}/rnc-cli-bug/react-native.config.js from {...}/node_modules/cosmiconfig/node_modules/import-fresh/index.js not supported. react-native.config.js is treated as an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" which declares all .js files in that package scope as ES modules. Instead rename react-native.config.js to end in .cjs, change the requiring code to use dynamic import() which is available in all CommonJS modules, or change "type": "module" to "type": "commonjs" in {...}/rnc-cli-bug/package.json to treat all .js files as CommonJS (using .mjs for all ES modules instead).

Users cannot rename react-native.config.js to react-native.config.cjs because it's not in the list of files being searched for, even when patching that list, yields this error:

Error: No loader specified for extension ".cjs", so searchPlaces item "react-native.config.cjs" is invalid

So, there doesn't seem to exist any workaround for this.

Possible Implementations

I believe the best solution is to upgrade cosmicconfig to a more recent version and use their async API to load the config file. This entails that the following methods would become async:

• readConfigFromDisk
• readDependencyConfigFromDisk
• loadConfig

Which would in practice break the API of both the @react-native-community/cli and @react-native-community/cli-config packages and probably require a major version bump.

A less intrusive alternative, would be to upgrade but only support CommonJS configs and simply add react-native.config.cjs and fix the issue loading it.

Note: Upgrading cosmicconfig would have the added benefit of packages being able to declare their React Native configs in their package.json files too. But that should either be disabled or named differently to avoid conflicts with the react-native main field already relied upon by Metro.

I'd be willing to contribute a PR to fix this, if there's a good chance it'll be considered for review.

Related Issues

I'm surprised, but I can't seem to find existing issues mentioning this limitation.

[robhogan]

FWIW, we intend to update cosmiconfig in Metro to support metro.config.mjs (and type: module) as soon as possible - one thing that's holding us back is that we ran into https://github.com/nodejs/node/issues/35889 - use of await import is liable to segfault Node VMs - and we were seeing this intermittently in Jest (integration tests that involved using cosmiconfig) as soon as we tried to update. I'll be trying again as soon as we've moved our CI to Node 20.

Related: https://github.com/facebook/metro/issues/916

[thymikee]

@robhogan so it looks like we're blocked on Metro? Please keep us updated, we'd happily implement this

[robhogan]

I wouldn't say blocked - I can't think of any technical reason this couldn't go into the CLI before Metro, although it might be less surprising if we were consistent.

I just wanted to share the experience we had with this upgrade - it might be that you're similarly blocked by Jest under Node<20, if you have integration tests that don't mock out cosmiconfig.

[szymonrybczak]

I just wanted to share the experience we had with this upgrade - it might be that you're similarly blocked by Jest under Node<20, if you have integration tests that don't mock out cosmiconfig.

Yes, we have - and I tried updating cosmiconfig and tests are failing because of this reason.

[karlhorky]

one thing that's holding us back is that we ran into nodejs/node#35889 - use of await import is liable to segfault Node VMs

@robhogan seems like that issue is now resolved - in case this should be noted anywhere as this blocker being removed.

[robhogan]

one thing that's holding us back is that we ran into nodejs/node#35889 - use of await import is liable to segfault Node VMs

@robhogan seems like that issue is now resolved - in case this should be noted anywhere as this blocker being removed.

Unfortunately it's only resolved for Node 20, and won't be backported, so it'll need to wait until we're on Node 20 (for CI, at least - there's probably no risk in prod as long as we don't use this in a Node VM).

[karlhorky]

Ok, thanks for the answer! So I guess it's waiting until facebook/react-native and facebook/metro are on Node.js version 20?

Taking a quick look in those repos, maybe that is tracked here?

1. facebook/react-native CI config: https://github.com/facebook/react-native/blob/575507dd61298be2f3071e0fc01ed9715cbd7a66/.circleci/config.yml#L52
2. facebook/react-native package.json -> engines: https://github.com/facebook/react-native/blob/575507dd61298be2f3071e0fc01ed9715cbd7a66/packages/react-native/package.json#L23-L25
3. facebook/metro CI config: https://github.com/facebook/metro/blob/84956bd11ab0ded6f06a867120980f8524e9cab6/.circleci/config.yml#L12-L15
4. facebook/metro package.json -> engines: https://github.com/facebook/metro/blob/84956bd11ab0ded6f06a867120980f8524e9cab6/package.json#L93-L95

Or does this also have to do with the react-native-community/cli repo? I see a couple of references to Node.js version numbers here, which still include v18:

https://github.com/react-native-community/cli/blob/61b6be6b86152fa9b6036968a15d7189de04ace8/.github/workflows/test.yml#L30

https://github.com/react-native-community/cli/blob/61b6be6b86152fa9b6036968a15d7189de04ace8/.github/workflows/test.yml#L47

[github-actions[bot]]

There hasn't been any activity on this issue in the past 3 months, so it has been marked as stale and it will be closed automatically if no further activity occurs in the next 7 days.

[karlhorky]

not stale

[szymonrybczak]

So is there any way we can move this forward without waiting for React Native making Node.js 20 as a default version? I checked and EOL for Node.js 18 is set for 30 Apr 2025.

[szymonrybczak]

hey! I've created a PR which adds support for ESM: https://github.com/react-native-community/cli/pull/2453 👍

[c100k]

Thanks @szymonrybczak for the PR. Hope it will get merged soon.

In the meantime, this was the last issue we had while migrating our monorepo to ESM so we had to find a solution (see below).

WARNING : this is a pretty ugly workaround and might not work for your use case. But in our case it does the job and unlocks us.

# Rename to .js so it can be found and switch temporarily to commonjs
mv react-native.config.cjs react-native.config.js && sed -i '' 's/"type": "module"/"type": "commonjs"/g' package.json

# Launch the build
yarn react-native run-android

# When the Gradle tasks have started, revert the temporary changes
mv react-native.config.js react-native.config.cjs && git checkout -- package.json

[szymonrybczak]

@c100k ah, I see 😅 I hope that you'll be able to remove this workaround soon! 👍

[karlhorky]

Copying my comment from the PR, since the issue is probably more visible 🤔

---

Nice, thanks to all of the contributors and reviewers here, great to have ESM in react-native.config.js files!

I'm not super aware of the upstreaming / integration process here in React Native projects - will this work right away out of the box with @react-native-community/[email protected]?

Eg:

1. I guess new React Native projects which start without a framework will receive this feature right away now?
2. Does this affect Expo projects at all? (I guess not)