Environment variables in EAS

Edit this page

Learn how to use and manage environment variables in EAS with examples.

Environment variables in Expo describe how to use environment variables with the Expo framework and .env files to set environment variables that can be inlined in your JavaScript code. Expo CLI will substitute prefixed variables in your code (for example, process.env.EXPO_PUBLIC_VARNAME) with the corresponding environment variable values in .env files on your development machine.

Since EAS Build and Workflows jobs run on a remote server, .env files may not be available. For instance, if .env files are excluded from your project, it is because they are listed in .gitignore or not committed to your local version control system.

Additionally, you may want to use environment variables outside of your project code to customize your app binary at build time, like setting a bundle identifier or a private key for an error reporting service. To accommodate for those needs we have a separate (but compatible) mechanism for managing environment variables in EAS, which is focused on storing and managing environment variables on EAS servers and synchronizing them for local development.

This guide describes how to use and manage environment variables in EAS with key practical examples.

Key concepts

Environments in EAS

Currently, EAS supports three environments for environment variables: development, preview and production. Environments are independent sets of environment variables that can be used to customize your app in different contexts. For example, you might want to use different API keys for development and production, or different bundle identifiers for different App Store releases. Environments allows you to do so. Every EAS Build and Workflows job runs using environment variables from one of the available environments. You can also use environments for updates, allowing you to use the same set of environment variables for your build jobs. You can do this when publishing an update by providing the --environment flag.

Environment variables can be assigned to multiple environments and have the same value across all of them, or be created for a single environment, so that you can set a specific value for a single environment.

Project-wide environment variables

Project-wide environment variables are specific to a single EAS project. You can view and manage them by navigating to the Environment Variables page on your project.

These environment variables are available in any jobs that run on EAS servers and updates for this project. They can also be pulled locally for development if their visibility setting allows it.

Account-wide environment variables

Account-wide environment variables are available across all of your projects in your EAS account. You can view and manage them by navigating to Environment Variables page on your account.

They are available in jobs that run on EAS servers and updates, together with project-wide variables for a project. You can pull them locally or read outside of EAS servers if their visibility setting allows it.

Visibility settings for environment variables

There are three different visibility settings:

Visibility	Description
Plain text	Visible on the website, in EAS CLI, and in logs.
Sensitive	Obfuscated in build and workflow jobs logs. You can use a toggle to make them visible on the website. They're also readable in EAS CLI.
Secret	Not readable outside of the EAS servers, including on the website and in EAS CLI. They are obfuscated in build and workflow jobs logs.

Always remember that anything that is included in your client side code should be considered public and readable to any individual that can run the application. Secret type environment variables are intended to be used to provide values to an EAS Build or Workflows job so that they may be used to alter how a job runs. For example, a good use case is setting an NPM_TOKEN to install private packages from npm, or a setting a Sentry API key to create a release and upload your source maps. Secrets do not provide any additional security for values that you end up embedding in your application itself.

Creating and using environment variables

The sections below use the following common environment variables as examples:

EXPO_PUBLIC_API_URL: a plain text EXPO_PUBLIC_ variable that holds the URL of the API server
APP_VARIANT: a plain text variable to select an app variant
GOOGLE_SERVICES_JSON: a secret file variable to supply your git ignored google-services.json file to the build job
SENTRY_AUTH_TOKEN: a sensitive variable that holds the authentication token for Sentry used to upload source maps after builds and updates

Use environment variables in your code

The environment variables with the EXPO_PUBLIC_ prefix are available as process.env variables in your app's code. This means you can use them to dynamically configure your app behavior based on the values from environment variables.

import { Button } from 'react-native';

function Post() {
  const apiUrl = process.env.EXPO_PUBLIC_API_URL;

  async function onPress() {
    await fetch(apiUrl, { ... })
  }

  return <Button onPress={onPress} title="Post" />;
}

In above example, EXPO_PUBLIC_API_URL is used to dynamically set the API URL for the fetch request.

Do not store sensitive information in EXPO_PUBLIC_ variables, such as private keys. These variables will be visible in plain-text in your compiled app.

Other variables, without the EXPO_PUBLIC_ prefix, can be used during app config resolution. An example of this is the APP_VARIANT variable used to determine the app name and package name or bundle identifier based on the selected app variant.

app.config.js

const IS_DEV = process.env.APP_VARIANT === 'development';
const IS_PREVIEW = process.env.APP_VARIANT === 'preview';

const getUniqueIdentifier = () => {
  if (IS_DEV) {
    return 'com.yourname.stickersmash.dev';
  }

  if (IS_PREVIEW) {
    return 'com.yourname.stickersmash.preview';
  }

  return 'com.yourname.stickersmash';
};

const getAppName = () => {
  if (IS_DEV) {
    return 'StickerSmash (Dev)';
  }

  if (IS_PREVIEW) {
    return 'StickerSmash (Preview)';
  }

  return 'StickerSmash: Emoji Stickers';
};

export default {
  name: getAppName(),
  %%placeholder-start%%... %%placeholder-end%%
  ios: {
    bundleIdentifier: getUniqueIdentifier(),
    %%placeholder-start%%... %%placeholder-end%%
  },
  android: {
    package: getUniqueIdentifier(),
    %%placeholder-start%%... %%placeholder-end%%
  },
};

The GOOGLE_SERVICES_JSON is a secret file variable that is not readable outside of EAS servers and is used to provide the git ignored google-services.json file to the build job. To use it in the app config, you can use the process.env variable and provide a fallback value in case the variable is not set (for local development when you usually have it inside your project's repository).

app.config.js

export default {
  %%placeholder-start%%...%%placeholder-end%%
  android: {
    googleServicesFile: process.env.GOOGLE_SERVICES_JSON ?? '/local/path/to/google-services.json',
    %%placeholder-start%%...%%placeholder-end%%
  },
};

Create environment variables

To create environment variables on EAS servers, you can use the environment variables creation form page or eas env:create command.

In the form, you can specify the name, value, environment(s) and visibility for the variable.

Created environment variables will be available in the list on the Environment Variables page on the Expo website.

Based on the environment variables in this example, the list will look like this:

List of successfully created environment variables

In above example, the SENTRY_AUTH_TOKEN can be treated as a sensitive environment variable. It is used to authenticate Sentry to upload source maps after builds and updates, so it has to be accessible outside of EAS servers.

Pull environment variables for your local development

The easiest way to use the EAS environment variables for local development is to pull them into a .env file using the eas env:pull --environment environment command. You can also use the Export option on the EAS dashboard to download the file and store it inside your project.

Run the following command to create a .env file in the root of your project:

Terminal

- eas env:pull --environment development

The created .env file will look like this:

.env.local

# Environment: development

APP_VARIANT=development
EXPO_PUBLIC_API_URL=https://staging.my-api-url.mycompany.com
# GOOGLE_SERVICES_JSON=***** (secret variables are not available for reading)
SENTRY_AUTH_TOKEN=token

The downloaded EXPO_PUBLIC_ variables are available for local development when using the npx expo start command. The GOOGLE_SERVICES_JSON variable is not available to be pulled to the local environment since it is a secret variable.

It is best to add all of the .env files to .gitignore to avoid committing them to your repository and exposing sensitive information. Committing a .env file may additionally lead to environment variables resolution conflicts.

Use environment variables with EAS Build

To have a full control over the environments used for your builds, you can specify the environment field in the build profiles settings in the eas.json file.

eas.json

{
  "build": {
    "development": {
      "environment": "development"
      %%placeholder-start%%... %%placeholder-end%%
    },
    "preview": {
      "environment": "preview"
      %%placeholder-start%%... %%placeholder-end%%
    },
    "production": {
      "environment": "production"
      %%placeholder-start%%... %%placeholder-end%%
    },
    "my-profile": {
      "environment": "production"
      %%placeholder-start%%... %%placeholder-end%%
    }
  }
}

All of the environment variables from the selected environment will be used during the build process. Plain text and sensitive variables will be available when resolving build configuration based on the dynamic app config in EAS CLI as well.

The environment variables of secret type are not available during build configuration resolution in EAS CLI as they are not readable outside of the EAS servers.

In this example app, all of the environment variables except GOOGLE_SERVICES_JSON (which is secret) will be available during build configuration resolution in EAS CLI.

It's especially important in this context to have the correct visibility set for the APP_VARIANT variable so that the variable available in EAS CLI and is able to generate credentials for the correct package name and bundle identifier.

Use environment variables with EAS Update

The most convenient way to use EAS environment variables with EAS Update is to run the eas update command with the --environment flag specified:

Terminal

- eas update --environment production

When the --environment flag is used, only the environment variables from the specified EAS environment will be used during the update process and won't use the .env files present in your project. This flag allows you to use the same environment variables while creating updates as with creating builds.

Expo CLI will substitute prefixed variables in your code (for example,process.env.EXPO_PUBLIC_VARNAME) with the corresponding plain text and sensitive environment variable values set on EAS servers for the environment specified with the --environment flag. Any EXPO_PUBLIC_ variables in your application code will be replaced inline with the corresponding values from your EAS environment whether that is your local machine or your CI/CD server.

We recommend using the --environment flag to ensure the same environment variables are used both for your update and build jobs.

The secret variables will not be available during the update process as they are not readable outside of EAS servers.

Using .env files with EAS Update

When the --environment flag is not provided, eas update will use the .env files present in your project directory for the update job and won't use the environment variables set on the EAS servers.

Environment variables in Expo describes how to use .env files to set and use environment variables within your JavaScript code. Expo CLI will substitute prefixed variables in your code (for example,process.env.EXPO_PUBLIC_VARNAME) with the corresponding environment variable values in .env files present on your development machine.

When you run eas update, all .env files will be evaluated when your JavaScript is bundled. Any EXPO_PUBLIC_ variables in your application code will be replaced inline with the corresponding values from your .env files that are present on the machine from which the update is published, whether that is your local machine or your CI/CD server.

When using .env files with EAS Update, EXPO_PUBLIC_ variables in these files will only be used when bundling your app's JavaScript. They will not be available when evaluating app.config.js.

Use environment variables for other commands

One way to supply non-secret EAS environment variables to other EAS commands is to use the eas env:exec command.

Terminal

- eas env:exec --environment production 'echo $APP_VARIANT'

For example, it can be useful when uploading source maps to Sentry using a SENTRY_AUTH_TOKEN variable after an update bundle is created.

Terminal

- eas env:exec --environment production 'npx sentry-expo-upload-sourcemaps dist'

EAS Build and Workflows job runs

Setting the environment for your builds

To set the environment for your EAS Build jobs, you can use the environment option in eas.json and set it to one of the available environments: development, preview or production.

eas.json

{
  "build": {
    "development": {
      "environment": "development"
    },
    "preview": {
      "environment": "preview"
    },
    "production": {
      "environment": "production"
    },
    "my-profile": {
      "environment": "production"
  }
}

If you don't set the environment option, we will set the environment automatically based on your build's configuration:

development: for development client build
preview: for other configurations
production: for app store build

This resolution logic is only available for EAS CLI in version 13.3.0 and higher. For older CLI versions, we always assume the production environment for all builds.

Built-in environment variables

The following environment variables are additional system environment variables exposed to each job and can be used within any build step. They are not a part of any project environment and are not available when evaluating app.config.js locally:

CI=1: indicates this is a CI environment
EAS_BUILD=true: indicates this is an EAS Build environment
EAS_BUILD_PLATFORM: either android or ios
EAS_BUILD_RUNNER: either eas-build for EAS Build cloud builds or local-build-plugin for local builds
EAS_BUILD_ID: the build ID, for example, f51831f0-ea30-406a-8c5f-f8e1cc57d39c
EAS_BUILD_PROFILE: the name of the build profile from eas.json, for example, production
EAS_BUILD_GIT_COMMIT_HASH: the hash of the Git commit, for example, 88f28ab5ea39108ade978de2d0d1adeedf0ece76
EAS_BUILD_NPM_CACHE_URL: the URL of npm cache (learn more)
EAS_BUILD_MAVEN_CACHE_URL: the URL of Maven cache (learn more)
EAS_BUILD_COCOAPODS_CACHE_URL: the URL of CocoaPods cache (learn more)
EAS_BUILD_USERNAME: the username of the user initiating the build (it's undefined for bot users)
EAS_BUILD_WORKINGDIR: the remote directory path with your project

Dynamically setting environment variables during the job execution

You can also set environment variables dynamically during the job execution using the set-env command. The set-env executable is available in the PATH on EAS Build workers, and can be used to set environment variables that will be visible in the next build phases.

For example, you can add the following in one of the EAS Build hooks and the environment variable EXAMPLE_ENV will be available until the end of the build job.

Terminal

- set-env EXAMPLE_ENV "example value"

Accessing environment variables

After creating an environment variable, you can read it on subsequent EAS Build jobs with process.env.VARIABLE_NAME from Node.js or in shell scripts as $VARIABLE_NAME.

Managing environment variables

Managing environment variables using EAS dashboard

The easiest way to create, read, update, export and delete environment variables is to use the Expo website. Navigate to the Environment variables page on your project or Environment variables page on your account to manage your environment variables.

Managing environment variables using EAS CLI

To manage environment variables using EAS CLI, you can use the eas env:create, eas env:update, eas env:list, and eas env:delete commands.

You can additionally use eas env:pull command to pull environment variables from EAS servers to your local .env file for development.

See the EAS CLI command reference for more information about these commands.

Common questions

What is the recommended workflow for using environment variables in my EAS project?

One possible way to efficiently work with environment variables in your EAS projects is to:

Use correct visibility settings

Make sure to set the visibility of your environment variables to the appropriate level. Avoid setting excessive secret visibility to EXPO_PUBLIC_ variables that are used in your app's JavaScript code or are used to resolve your app's configuration. Be aware that environment variables with secret visibility are not readable outside of EAS servers, and can't be pulled locally for development or to bundle your app's JavaScript code for updates.

Add .env files to .gitignore

To avoid confusing overrides during cloud jobs and leaking sensitive information, add .env files to your .gitignore file.

Use the `--environment` flag with `eas update`

When publishing updates, use the --environment flag with the eas update command to ensure that the same environment variables are used for your updates as your build jobs.

When the --environment flag is provided, eas update will use the environment variables on EAS servers for the update job and won't use the .env files present in your project often used for local development.

Sync the environment variables for local development using `eas env:pull`

You can use the eas env:pull command to pull environment variables from EAS servers to your local .env file for development. The ideal environment that can be used for this purpose is the development environment, as it's the default environment used for development builds.

Explicitly specify the environment for your builds

Explicitly set the environment value in eas.json for your build profiles to ensure that the correct environment variables are always used for your build jobs and you have full control over this process.

Can I set my environment variables on a CI provider when triggering the build using eas build command?

Environment variables must be defined on EAS servers to be made available to EAS Build builders. If you are triggering builds from CI the same rule applies, and you should be careful to not confuse setting environment variables on GitHub Actions (or the provider of your choice) with setting environment variables and secrets on EAS servers.

How do environment variables work for my development builds?

Environment variables set in your build profile that impact app.config.js will be used for configuring the development build.

When you run npx expo start to load your app inside of your development build, only environment variables that are available on your development machine will be used.

Can I use file environment variables in my EAS project?

In addition to setting strings as values, you can also upload files as the value of an environment variable.

One common use case of using file environment variable is passing a git ignored google-services.json configuration file to a build job. During the job run, the file will be created in a location outside of the project directory and the path to the file will be assigned to the environment variable (GOOGLE_SERVICES_JSON=/path/to/google-services.json). For example, you can then set android.googleServicesFile in your app config to the value of the GOOGLE_SERVICES_JSON environment variable to use this file when executing the build or workflow job.

app.config.js

export default {
  %%placeholder-start%%...%%placeholder-end%%
  android: {
    googleServicesFile: process.env.GOOGLE_SERVICES_JSON ?? '/local/path/to/google-services.json',
    %%placeholder-start%%...%%placeholder-end%%
  },
};

Differences between handling environment variables in EAS CLI and Expo CLI

One of the differences between using environment variables with the Expo framework and EAS is that EAS CLI itself does not support loading .env files to set environment variables when resolving the app config. Instead, it's recommended to use the EAS environment variables management system with EAS CLI commands to set environment variables for your build jobs and updates to avoid confusion, and ensure that exactly the same environment variables are used both for:

Local app config resolution, done by EAS CLI when preparing the app config
Remote jobs happening on EAS servers, which often don't have access to your local .env files that are git ignored

Using eas update is the one exception to this rule. By default, for backward compatibility reasons, it uses .env files present in your project directory to set environment variables for the update job, the same way Expo CLI does (it executes the npx expo export command under the hood).

To ensure that you can use the same environment variables in your updates as your build jobs, you can use the --environment flag with the eas update command to force it to use only the environment variables set on the EAS servers instead of the .env files present in your project directory. It will ignore environment variables from .env.

Are there any limitations to using environment variables in EAS?

Environment variable value size is limited to 32 KiB for environment variables with secret visibility and 4 KiB for other visibility types.
You can create up to 100 account-wide environment variables for each Expo account and 100 project-specific environment variables for each app.

Environment variables in EAS

Key concepts

Creating and using environment variables

Use environment variables in your code

Create environment variables

Pull environment variables for your local development

Use environment variables with EAS Build

Use environment variables with EAS Update

Use environment variables for other commands

EAS Build and Workflows job runs

Setting the environment for your builds

Dynamically setting environment variables during the job execution

Accessing environment variables

Managing environment variables

Common questions

Use correct visibility settings

Add .env files to .gitignore

Use the --environment flag with eas update

Sync the environment variables for local development using eas env:pull

Explicitly specify the environment for your builds

Use the `--environment` flag with `eas update`

Sync the environment variables for local development using `eas env:pull`