Jotai incompatibility issue with Expo 53+ / React Native 0.79+

[byCedric]

Bug Description

I noticed Jotai is a dual-published package with both CJS and ESM code. But, the ESM contains Vite-specific code, like import.meta.env.MODE.

React Native 0.79 uses Metro 0.82.x which enables package.json:exports by default, meaning that if you use these imports, Metro now would resolve the following:

• require('jotai') -> CJS version of Jotai
• import { .. } from 'jotai' -> ESM version of Jotai
• await import('jotai') -> ESM version of Jotai

Combine this with the Vite-only features in the ESM builds, Jotai will break Metro with the following error:

Uncaught SyntaxError: Cannot use 'import.meta' outside a module

Ideally, Jotai should just work out of the box with React Native. One way could be adding a react-native specific resolution to package.json:exports - pointing to the CJS code - which should be picked up by Metro.

The other way is a little bit harder, but definitely something that should be on the table. Adding support to Vite-specific code patterns in Metro, through an RFC.

---

Already using Expo 53+ and need a workaround?

We can tell Metro to resolve jotai(/*) differently, without package.json:exports support. Configuring metro.config.js for Expo with this should help:

// Learn more https://docs.expo.io/guides/customizing-metro
const { getDefaultConfig } = require('expo/metro-config');

/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname);

config.resolver.resolveRequest = (context, moduleName, platform) => {
  switch (moduleName) {
    case 'jotai':
      return context.resolveRequest(
        // This forces `package.json:exports` resolution to just the "default" code
        { ...context, unstable_conditionNames: ["default"] },
        moduleName,
        platform,
      );

    default:
      return context.resolveRequest(context, moduleName, platform);
  }
};

module.exports = config;

Reproduction Link

https://github.com/byCedric/jotai-expo-53-issue

• Install dependencies with bun/npm/yarn
• npm run start
• Open the device, or web URL listed in the terminal

[byCedric]

FWIW: Because this will be an issue with more packages in the React Native community, there will be a 2nd workaround: expo/expo#36074

[dai-shi]

Hi @byCedric !

pmndrs/zustand#1967 is a related discussion.

I do think import.meta.env.MODE is vite specific, but import.meta is not. Metro should support it if they say supporting ESM.

Having that said, I think the situation hasn't changed for a very long time, so I think I can consider adding 'react-native' in exports. I was a bit afraid of breaking with old RN, but let's try.

[sukminkang12]

I still think it's a non-ideal solution, because as you said now RN with JSC would never be able to pick ESM from Jotai.

I think this issue is irrelevant because JSC supports both ESM and CJS

Hmmm, but if that's the case, Metro or RN shouldn't allow using Hermes as it doesn't support ESM yet. Maybe it's somehow separated as you implied

I agree with you. However, since I'm not a developer of Metro or React Native, I'm not sure about their intentions.

Additionally, while both Hermes and JSC are JavaScript engines for React Native, Hermes has a performance advantage and is considered the de facto standard engine.

Could you modify zustand in the same way as jotai?

Thank you

[dai-shi]

I opened PRs in zustand and valtio too.

[byCedric]

Sorry for not replying earlier! I agree with @sukminkang12, Metro uses all kinds of internal transformations to get it back to CJS for Hermes. I also agree there is more work to be done for Metro to fully "support"/emulate ESM support like import.meta.* statements. Will forward this thread to Meta and ask if they can chime in on this.

For now, I think it's the path of least resistance to force CJS on React Native regardless of the target platform. Metro mostly compiles to CJS, even on web - while not optimal, it shouldn't result in any bigger issues.

[peterpme]

Hello! I think the CJS on React Native approach is right. Even if temporary. We've previously been forcing packages to use CJS in metro anyway so that functionality won't change. Ideally we won't have to do that if the library does it for us :)

Thanks!

[robhogan]

I do think import.meta.env.MODE is vite specific, but import.meta is not. Metro should support it if they say supporting ESM.

Yes, agreed - lack of import.meta is a spec gap (working on it: facebook/metro#1494). At least until that's solved, CJS versions are mostly/likely more compatible, though it must be said Metro has never fully supported CJS either - there's no require.resolve, for example.

Hmmm, but if that's the case, Metro or RN shouldn't allow using Hermes as it doesn't support ESM yet. Maybe it's somehow separated as you implied.

The bundled code is neither CJS nor ESM, it's a ES script that does it's best to emulate the behaviour of a module graph. In this context, Hermes doesn't (need to) support CJS or ESM. Effectively the bundler implements the module system.

Recently, Metro has moved in (IMO) a spec-compliant/forward-looking direction by asserting the 'import' condition when the source code uses import X from, and 'require' when the source code uses require(), simultaneously with preferring exports field resolution over main fields - in practice that's led to resolving more ESM, which has exposed/made more urgent gaps like import.meta.

The exports spec (unfortunately?) doesn't allow for a bundler/engine/resolver to prefer one or the other - explicitly that's the choice of package authors via exports field ordering. And not asserting 'import' even when the source is ESM, aside from being a spec divergence, would be increasingly impractical as packages increasingly only ship ESM.

[ochanje210]

import.meta issue on RN should be fixed from https://github.com/pmndrs/jotai/releases/tag/v2.12.4

[jenseralmeida]

The v2.12.4 did not fix it for me. Am I the only one still having issues with the latest patch?

cc @ochanje210

[Malachite40]

Upgrading Zustand to 5.0.3 seemed to fix my issue

[jenseralmeida]

Upgrading Zustand to 5.0.3 seemed to fix my issue

I did not check if Zustand is working for me, but the Zustand 5.0.3 fix mentioned by @Malachite40 was a migration of the Jotai fix, even though, the Jotai change did not fix the issue, at least not for me.

[jenseralmeida]

Following expo/expo#36375 I was able to make it work by:

• I have disabled unstable_enablePackageExports based on [SDK 53] "... attempted to import the Node standard library module ..." and other package.json:exports related issues expo/expo#36375 (comment)
• And then, npm install @supabase/realtime-js @supabase/supabase-js --save as mentioned on [SDK 53] "... attempted to import the Node standard library module ..." and other package.json:exports related issues expo/expo#36375 (comment). There is no need to use the next versions as they were released already.

Doing both, Jotai worked with Expo 53, but it should have just worked, instead of several configuration steps.

• metro.config.js

// Learn more https://docs.expo.io/guides/customizing-metro
const { getDefaultConfig } = require('expo/metro-config');

/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname);
config.resolver.unstable_enablePackageExports = false

module.exports = config;

• package.json

{
  "name": "jotai-bug",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "start": "expo start",
    "android": "expo start --android",
    "ios": "expo start --ios",
    "web": "expo start --web"
  },
  "dependencies": {
    "@supabase/realtime-js": "^2.11.8",
    "@supabase/supabase-js": "^2.49.8",
    "expo": "~53.0.9",
    "expo-status-bar": "~2.2.3",
    "jotai": "^2.12.4",
    "react": "19.0.0",
    "react-dom": "19.0.0",
    "react-native": "0.79.2",
    "react-native-web": "^0.20.0"
  },
  "overrides": {
    "react": "19.0.0"
  },
  "devDependencies": {
    "@babel/core": "^7.20.0",
    "@expo/metro-runtime": "~5.0.1"
  },
  "private": true
}

[jenseralmeida]

🛠️ Calling for a commitment to resolve this critical issue

As an external developer using Jotai, I've been affected by this issue for some time. Fortunately, I was able to uncover the workaround buried in this, and related threads — but realistically, many developers won't have the time or context to find it.

This issue has now lingered for over 3 months and continues to break core functionality for users out of the box. That’s likely turning people away from the project altogether.

🎯 I’d like to respectfully ask for a commitment from the maintainers to:

• Make the current workaround official and clearly documented (preferably on the homepage or README)
• Prioritize this issue for a proper fix
• Consider treating this as a blocker for an upcoming release

Without clear guidance or visibility, this bug damages confidence and hampers adoption. I genuinely appreciate the effort that goes into maintaining Jotai, and I’m raising this to help the project grow stronger.

If others are encountering the same issue, please add your 👍 or insights.

Let’s make Jotai more accessible for everyone. 💬

[dai-shi]

This is not only with Jotai. The same things can happen with Zustand and Valtio. We asked helps in various discussion threads, but none has given a good context yet. So, I have no idea about the current status and what to do.
Q1: Is it only Expo issue (many reported it works with RN)?
Q2: Does the Expo team aware of the limitation?
Q3: What could be a proper fix?
Q3: What's the recommended workaround at this point?

Basically, we need a contributor who is very familiar with this problem. I think @byCedric should be the right person.

[dai-shi]

See also: pmndrs/zustand#1967 (reply in thread)