Expo Docs MCP Server

--- title: Environment variables in EAS sidebar_title: Environment variables description: Learn how to use and manage environment variables in EAS with examples. searchRank: 8 --- [Environment variables in Expo](/guides/environment-variables) 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 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 are specific to a single EAS project. You can view and manage them by navigating to the [Environment Variables](https://expo.dev/accounts/[account]/projects/[project]/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 are available across all of your projects in your EAS account. You can view and manage them by navigating to [Environment Variables](https://expo.dev/accounts/[account]/settings/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. 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. | > **warning** 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_`](/guides/environment-variables/) variable that holds the URL of the API server - `APP_VARIANT`: a plain text variable to select an [app variant](/tutorial/eas/multiple-app-variants/) - `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_`](/guides/environment-variables) 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. ```tsx function Post() { const apiUrl = process.env.EXPO_PUBLIC_API_URL; async function onPress() { await fetch(apiUrl, { ... }) } return ; } ``` In above example, `EXPO_PUBLIC_API_URL` is used to dynamically set the API URL for the fetch request. > **warning** 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. ```js 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'; }; /* @info Using getAppName() for "name" property */ name: getAppName(), /* @end */ /* @hide ... */ /* @end */ ios: { /* @info Using getUniqueIdentifier() for "bundleIdentifier" property */ bundleIdentifier: getUniqueIdentifier(), /* @end */ /* @hide ... */ /* @end */ }, android: { /* @info Using getUniqueIdentifier() for "package" property */ package: getUniqueIdentifier(), /* @end */ /* @hide ... */ /* @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). ```js app.config.js /* @hide ...*/ /* @end */ android: { googleServicesFile: process.env.GOOGLE_SERVICES_JSON ?? '/local/path/to/google-services.json', /* @hide ...*/ /* @end */ }, }; ``` ### Create environment variables To create environment variables on EAS servers, you can use the [environment variables creation form](https://expo.dev/accounts/[account]/projects/[project]/environment-variables/new) 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](https://expo.dev/accounts/[account]/projects/[project]/environment-variables) page on the Expo website. Based on the environment variables in this example, the list will look like this: 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](https://expo.dev/accounts/[account]/projects/[project]/environment-variables) 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: The created **.env** file will look like this: ```bash .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. > **warning** 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`](/eas/json#environment) field in the build profiles settings in the **eas.json** file. ```json eas.json { "build": { "development": { /* @info Using development environment */ "environment": "development" /* @end */ /* @hide ... */ /* @end */ }, "preview": { /* @info Using preview environment */ "environment": "preview" /* @end */ /* @hide ... */ /* @end */ }, "production": { /* @info Using production environment */ "environment": "production" /* @end */ /* @hide ... */ /* @end */ }, "my-profile": { /* @info Using production environment */ "environment": "production" /* @end */ /* @hide ... */ /* @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. > **info** 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: 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. > **info** The secret variables will not be available during the update process as they are not readable outside of EAS servers. 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](/guides/environment-variables) 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. > **info** 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. For example, it can be useful when uploading source maps to Sentry using a [`SENTRY_AUTH_TOKEN`](/guides/using-sentry) variable after an update bundle is created. ### 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`. ```json 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 > **info** 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. 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](/build-reference/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](/build-reference/private-npm-packages)) - `EAS_BUILD_MAVEN_CACHE_URL`: the URL of Maven cache ([learn more](/build-reference/caching/#android-dependencies)) - `EAS_BUILD_COCOAPODS_CACHE_URL`: the URL of CocoaPods cache ([learn more](/build-reference/caching/#ios-dependencies)) - `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](/build-reference/npm-hooks/) and the environment variable `EXAMPLE_ENV` will be available until the end of the build job. #### 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 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](https://expo.dev/accounts/[account]/projects/[project]/environment-variables) or [**Environment variables** page on your account](https://expo.dev/accounts/[account]/settings/environment-variables) to manage your environment variables. 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](https://github.com/expo/eas-cli/blob/main/packages/eas-cli/README.md) for more information about these commands. ## Common questions 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`](/eas/json#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. {/* vale off */} Can I set my environment variables on a CI provider when triggering the build using <CODE>eas build</CODE> 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. {/* vale on */} 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. 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. ```js app.config.js /* @hide ...*/ /* @end */ android: { googleServicesFile: process.env.GOOGLE_SERVICES_JSON ?? '/local/path/to/google-services.json', /* @hide ...*/ /* @end */ }, }; ``` 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](/guides/environment-variables) 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**. - 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.