Expo EAS Client

Common errors

• Error: Client Id property expoClientId must be defined to use Google auth on this platform.

  cause Missing or incorrectly configured `expoClientId` for Google OAuth in an Expo Go or development build environment.
  fix Follow the steps to generate a 'Web Application' OAuth Client ID on Google Cloud Platform, setting `Authorized JavaScript origins` to `https://auth.expo.io` and `Authorized redirect URIs` to `https://auth.expo.io/@{username}/{SLUG}`. Use this ID as `expoClientId`.

• Error: Unable to resolve module fs from /home/expo/workingdir/build/node_modules/dotenv/lib/main.js: fs could not be found within the project

  cause This error typically occurs during EAS builds when `package.json` specifies `"type": "module"`, leading to CommonJS modules (like `dotenv`) being treated as ESM and failing to resolve Node.js built-in modules like `fs`.
  fix Rename configuration files like `metro.config.js` and `babel.config.js` to `.cjs` extensions. If the project itself strictly uses ESM, ensure all dependencies are compatible or use a bundler configuration that correctly handles module interop.

• require() not supported, uses a dynamic import() which is available in all CommonJS modules

  cause Attempting to use `require()` syntax in a JavaScript file that is being treated as an ES Module (e.g., due to `"type": "module"` in `package.json` or a `.mjs` extension) in an environment that doesn't fully support mixed module types or where specific tools expect ESM.
  fix Convert `require()` calls to `import` statements (e.g., `import * as Module from 'module';` or `import { namedExport } from 'module';`). For files that must remain CommonJS, ensure they use a `.cjs` extension or remove `"type": "module"` from `package.json` if the project is predominantly CommonJS.

Warnings

• breaking Projects using `"type": "module"` in `package.json` may encounter issues with `metro.config.js` or `babel.config.js` files during EAS builds. Metro bundler's ES Module resolution can be strict, leading to build failures.
  Fix: Rename `metro.config.js` to `metro.config.cjs` and `babel.config.js` to `babel.config.cjs`. If issues persist, consider adding a symlink from `.js` to `.cjs` files for compatibility, or ensure your Metro config correctly handles ES Modules by referring to the latest Expo documentation on customizing Metro.
• breaking Expo SDK 50+ and related tools, including `eas-cli`, now explicitly require Node.js version 18 or higher. Using older Node.js versions will lead to build failures or unexpected behavior.
  Fix: Upgrade your Node.js environment to version 18 (LTS) or later. Use a Node Version Manager (e.g., `nvm use 18`) to manage multiple Node.js versions effectively across projects.
• deprecated The 'Classic Updates' system (using `expo publish`) has been deprecated since SDK 50. All new and existing projects are encouraged to migrate to EAS Update for over-the-air updates.
  Fix: Transition to EAS Update. Follow the official Expo documentation for migrating from Classic Updates to EAS Update, which involves configuring `eas.json` and using `eas update` commands.
• gotcha When implementing Google authentication (and potentially other OAuth providers) in an Expo Go or development build environment, a specific `expoClientId` is required in addition to `androidClientId` and `iosClientId`.
  Fix: Create a 'Web Application' OAuth Client ID in Google Cloud Platform, set `Authorized JavaScript origins` to `https://auth.expo.io`, and `Authorized redirect URIs` to `https://auth.expo.io/@{username}/{SLUG}`. Use the generated Client ID as your `expoClientId` in your authentication configuration.
• breaking For `eas update` commands with Expo SDK 55 and later, the `--environment` flag is now mandatory to explicitly specify the target environment (e.g., development, preview, production).
  Fix: Always include `--environment <environment_name>` (e.g., `eas update --branch main --environment production`) when running `eas update` commands for SDK 55+ projects.

Install

• npm install expo-eas-client npm
• yarn add expo-eas-client yarn
• pnpm add expo-eas-client pnpm

Imports

• getOrCreateUUIDAsync
  wrong:

  const { getOrCreateUUIDAsync } = require('expo-eas-client');

  correct:

  import { getOrCreateUUIDAsync } from 'expo-eas-client';

  This package is primarily designed for ES Module imports. While CommonJS might work in some older setups, ESM is the standard for modern Expo projects, especially with SDK 50+.
• EASClient

  import * as EASClient from 'expo-eas-client';

  Importing the entire module as a namespace is possible, though `getOrCreateUUIDAsync` is typically the only public API for application logic.
• ExpoEASClientError

  import { ExpoEASClientError } from 'expo-eas-client';

  For specific error handling related to this module, the `ExpoEASClientError` class might be exported, if applicable, allowing for more granular catch blocks.

Quickstart

Demonstrates how to retrieve the persistent client identifier managed by `expo-eas-client` and compares it with `expo-constants.installationId`.

import { getOrCreateUUIDAsync } from 'expo-eas-client';
import Constants from 'expo-constants';
import { Platform } from 'react-native';

async function displayClientInfo() {
  try {
    // The primary function of expo-eas-client is to manage a stable UUID.
    // Developers typically access a 'client ID' via expo-constants.installationId,
    // which is underlaid by expo-eas-client for persistence.
    const easClientId = await getOrCreateUUIDAsync();
    console.log(`EAS Client ID (from expo-eas-client): ${easClientId}`);

    const installationIdFromConstants = Constants.installationId;
    console.log(`Installation ID (from expo-constants): ${installationIdFromConstants}`);
    console.log(`These two IDs should typically be the same.`);

    if (!easClientId || !installationIdFromConstants) {
      console.warn('Could not retrieve a stable client identifier.');
      return;
    }

    console.log(`Platform: ${Platform.OS} ${Platform.Version}`);
    console.log('This ID is stable across app reinstalls and device restores for consistent EAS services.');

  } catch (error) {
    console.error('Failed to get EAS Client ID:', error);
    // Log detailed error for debugging
    if (error instanceof Error) {
      console.error('Error message:', error.message);
      console.error('Error stack:', error.stack);
    } else {
      console.error('Unknown error:', error);
    }
  }
}

displayClientInfo();