This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Learn how to use environment variables in builds, updates, hosting, and workflow jobs with Expo Services.

The following sections cover how to use environment variables in builds, updates, and workflow jobs with Expo Services.

Using environment variables with Expo Build

To have 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.

{
  "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.

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

• production when distribution is set to store
• development when developmentClient is true
• preview for everything else

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

Using environment variables with Expo Update

In SDK 55 or later, the --environment flag is required when running eas update. The environment variables from the specified Expo Services environment will be used during the update process. For projects using SDK 54 or earlier, eas update falls back to local .env files when the --environment flag is omitted.

To use Expo Services environment variables with Expo Update, run the eas update command with the --environment flag:

When the --environment flag is used, only the environment variables from the specified Expo Services environment will be used during the update process and won't use the .env files present in your project. This ensures the same environment variables are used for both your updates and 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 Expo 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 Expo Services environment whether that is your local machine or your CI/CD server.

The --environment flag ensures the same environment variables are used for both your update and build jobs.

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

Using environment variables with Expo Hosting

An Expo Router web project can include environment variables that are used on both the client and the server. Client-side values are inlined in the JavaScript bundle when you run npx expo export, while server-side values are stored on the server and are deployed with your API routes when you run eas deploy.

With Expo Hosting, only plain text and sensitive environment variables can be used. Secrets cannot be deployed with Expo Hosting.

Storing environment variables

When deploying a project with Expo Services environment variables, note that the environment variables for the client-side and server-side code are included at different steps:

• Running npx expo export --platform web will inline the EXPO_PUBLIC_ variables in the frontend code. So ensure that your .env.local file includes the correct environment variables before running the npx expo export command.
• eas deploy --environment production will include all variables for the given environment (in this case, production) in the API routes. Expo Services environment variables loaded with the --environment flag will take precedence over ones defined in .env and .env.local files.

Environment variables are per deployment, and deployments are immutable. This means that after changing an environment variable, you will need to re-export your project, and re-deploy in order for them to be updated.

For local development

For local development, both client- and server-side environment variables are loaded from local .env files, which should be gitignored. If you are using Expo Services environment variables, use eas env:pull to retrieve the environment variables for development, preview, or production.

Using environment variables for other commands

One way to supply non-secret Expo Services environment variables to other EAS CLI 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 variable after an update bundle is created.

Using environment variables in Expo Workflows

Setting Expo Services environment for workflow jobs

When you omit jobs.<job_id>.environment, the default depends on the job type:

• Build jobs: The environment comes from the build profile in eas.json (build.<profile>.environment). If that field is missing, the automatic defaults described above apply. Using environment variables with Expo Build.
• Submit jobs: The environment is inherited from the submitted build.
• Maestro jobs (maestro and maestro-cloud): The environment defaults to preview.
• Other jobs (for example, update, fingerprint, deploy, and custom jobs): The environment defaults to production.

Set environment explicitly on a job to override its default and keep it in sync with the build profile you used earlier in the workflow. For a full explanation, see The job environment.

In the following example, a build job is configured to use the preview profile, then an update job is configured to use the same Expo Services environment.

name: Publish preview build and update

jobs:
  build_preview:
    type: build
    params:
      platform: ios
      profile: preview # uses environment from eas.json's build.preview.environment

  publish_preview_update:
    needs: [build_preview]
    type: update
    environment: preview # pulls variables from the preview environment
    params:
      branch: preview

In the following example, a fingerprint job is configured to use the production environment, then a build job is configured to use the same Expo Services environment.

name: Fingerprint and build

jobs:
  fingerprint:
    type: fingerprint
    environment: production # defaults to production, but set explicitly to match the build
  build_ios:
    needs: [fingerprint]
    type: build
    params:
      platform: ios
      profile: production # uses environment from eas.json's build.production.environment

Keep the job environment value in sync with the build profile to avoid mismatched secrets. For example, fingerprint/update jobs should usually match the build's profile environment.

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 Expo 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 Expo Build 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 Expo Build jobs with process.env.VARIABLE_NAME from Node.js or in shell scripts as $VARIABLE_NAME.