eas/environment-variables

94 notes in this subject, read out of this brain and free to use. This is page 1 of 2.

Environment variable value size limits

Environment variable value size is limited to 32 KiB for environment variables with secret visibility and 4 KiB for other visibility types.

Custom environment name requirements

When creating a custom environment, an environment name can contain letters, digits, underscores and hyphens, and must be between 3-100 characters.

Custom environments limit

Custom environments are limited to 10 per project.

Set correct visibility for environment variables

Avoid setting excessive secret visibility to EXPO_PUBLIC_ variables that are used in your app's JavaScript code or to resolve your app's configuration. Environment variables with secret visibility are not readable outside of EAS servers and cannot be pulled locally for development or to bundle your app's JavaScript code for updates.

Add .env files to .gitignore

Add .env files to your .gitignore file to avoid confusing overrides during cloud jobs and to prevent leaking sensitive information.

File environment variables in EAS

In addition to setting strings as values, you can upload files as the value of an environment variable. A common use case is passing a git ignored google-services.json configuration file to a build job. During the job run, the file is created in a location outside of the project directory and the path to the file is assigned to the environment variable (for example, GOOGLE_SERVICES_JSON=/path/to/google-services.json). You can then set android.googleServicesFile in your app config to the value of the GOOGLE_SERVICES_JSON environment variable.

Environment variable count limits

You can create up to 150 account-wide environment variables for each Expo account and 200 project-specific environment variables for each app.

Manage workflow environment variables

Environment variables used in workflows can be created in the EAS dashboard. Navigate to the account settings at https://expo.dev/accounts/[account]/settings/environment-variables and create variables for the specified environment before running the workflow.

Remote step: NPM_TOKEN and .npmrc creation

If NPM_TOKEN is set, EAS Build creates a .npmrc file during the remote build process to support private npm packages.

EAS_LOCAL_BUILD_ARTIFACTS_DIR environment variable

Use `EAS_LOCAL_BUILD_ARTIFACTS_DIR` to specify the directory where artifacts are copied after a successful build. By default, artifacts are copied to the current directory.

EAS_LOCAL_BUILD_SKIP_CLEANUP environment variable

Set `EAS_LOCAL_BUILD_SKIP_CLEANUP=1` to disable cleaning up the working directory after the build process is finished, which allows inspection of build artifacts for debugging.

EAS_LOCAL_BUILD_WORKINGDIR environment variable

Use `EAS_LOCAL_BUILD_WORKINGDIR` to specify a custom working directory for the build process. By default, the working directory is located in the /tmp directory (platform dependent).

Environment variables in eas.json not available for eas update

Environment variables set on the env field in build profiles are not available when running eas update. Environment variables must be configured separately for EAS Update usage.

Environment variables in development builds

Environment variables set in build profile that impact app.config.js will be used for configuring the development build. When running npx expo start to load the app inside development build, only environment variables available on the development machine will be used.

Use eas env:pull for local development environment variables

The eas env:pull command can be used to pull environment variables from EAS servers to the local .env file for development. The development environment is recommended for this purpose, as it is the default environment used for development builds.

Use --environment flag with eas update for consistency

When publishing updates with eas update, the --environment flag is required. This ensures the same environment variables are used for updates as build jobs. When --environment flag is provided, eas update uses environment variables on EAS servers and ignores .env files present in the project.

Environment variable limitations in EAS

Environment variable limitations in EAS: environment variable value size is limited to 32 KiB for environment variables with secret visibility and 4 KiB for other visibility types; up to 150 account-wide environment variables can be created for each Expo account; up to 200 project-specific environment variables can be created for each app; custom environments are limited to 10 per project; environment names can contain letters, digits, underscores and hyphens, and must be between 3-100 characters.

Environment variable handling differences between SDK versions

In SDK 54 and earlier, eas update was an exception to the rule about .env files. It used .env files present in the project directory by default to set environment variables for the update job, the same way Expo CLI does. In SDK 55 or later, the --environment flag is required with eas update, and it uses only environment variables set on EAS servers. For projects on SDK 54 or earlier, the --environment flag can be used with eas update command to opt into this behavior.

EAS CLI does not load .env files for app config resolution

EAS CLI does not support loading .env files to set environment variables when resolving the app config. Instead, the EAS environment variables management system should be used with EAS CLI commands to set environment variables for build jobs and updates. This ensures the same environment variables are used both for local app config resolution done by EAS CLI and for remote jobs on EAS servers.

Environment variables with file values example

Example of using a file environment variable in app.config.js: ```js export default { android: { googleServicesFile: process.env.GOOGLE_SERVICES_JSON ?? '/local/path/to/google-services.json', }, }; ``` This example shows how to reference the GOOGLE_SERVICES_JSON environment variable with a fallback to a local path.

File environment variables in EAS

Environment variables can have files as values, not just strings. During a job run, the file is created in a location outside the project directory and the path is assigned to the environment variable (for example, GOOGLE_SERVICES_JSON=/path/to/google-services.json). A common use case is passing a git-ignored google-services.json configuration file to a build job. The app config can reference this environment variable to use the file when executing the build or workflow job.

Environment variables must be defined on EAS servers for EAS Build

Environment variables must be defined on EAS servers to be made available to EAS Build builders. If triggering builds from a CI provider like GitHub Actions, environment variables must still be set on EAS servers, not on the CI provider itself. Setting environment variables on CI providers will not make them available to EAS Build.

Recommended workflow for environment variables in EAS

The recommended workflow for using environment variables in EAS projects includes: use correct visibility settings to avoid setting excessive secret visibility to EXPO_PUBLIC_ variables; add .env files to .gitignore to avoid confusing overrides and leaking sensitive information; use the --environment flag with eas update command to ensure the same environment variables are used for updates as build jobs; use eas env:pull command to pull environment variables from EAS servers to local .env file for development; explicitly specify the environment value in eas.json for build profiles to ensure correct environment variables are always used for build jobs.

Plain text visibility setting

Plain text is a visibility setting for environment variables that makes them visible on the website, in EAS CLI, and in logs.

Client-side environment variables in EAS

Anything included in client-side code should be considered public and readable to any individual that can run the app. For EAS Hosting, client-side environment variables must be plain text or sensitive visibility, not secret.

Pull environment variables for local development

Environment variables can be pulled locally for development using the EAS CLI command: eas env:pull --environment production. This makes EAS environment variables available on your local machine for development when their visibility setting allows it.

Local .env files not available in remote EAS jobs

During local development, environment variables are loaded from .env or .env.local files. However, these files are generally excluded from version control and are not available for jobs that run on remote servers, such as EAS Build and EAS Workflows. EAS environment variables solve this by allowing variables to be configured in EAS and accessed by remote jobs.

Use environment variables with EAS Hosting

To use environment variables with EAS Hosting, run the commands in order: eas env:pull --environment production, npx expo export --platform web, eas deploy --environment production. The --environment flag specifies which environment's variables to use during deployment. For hosting, client-side variables must be plain text or sensitive, not secret.

EAS environment variable types: Strings and Files

EAS supports two types of environment variables: Strings (standard key/value pairs usable across builds, updates, workflows, and hosting) and Files (values uploaded as files, such as google-services.json or certificates, made available to jobs as file paths on the build runner).

Account-wide environment variable scope

Account-wide environment variables are available across all projects in an EAS account. They can be created, viewed, and managed on the Environment variables page in the account's dashboard settings on expo.dev. These variables are available in jobs that run on EAS servers and updates, together with project-wide variables. They can be pulled locally or read outside EAS servers if their visibility setting allows it.

Verify environment variable creation on expo.dev

After creating an environment variable with the EAS CLI, verify it was created successfully by checking the Environment variables page in your project settings on expo.dev. The variable should appear with a badge indicating its assigned environment.

EAS environment variable creation command

To create a new environment variable, use the EAS CLI command: eas env:set --name EXPO_PUBLIC_API_URL --value https://api.example.com --environment production --visibility plaintext. This creates an environment variable with a specified name, value, environment (development, preview, or production), and visibility level.

Project-wide environment variable scope

Project-wide environment variables are specific to a single EAS project. They can be created, viewed, and managed on the Environment variables page in the project's dashboard on expo.dev. These variables are available in any jobs that run on EAS servers and updates for that project, and can be pulled locally for development if their visibility setting allows it.

Environment variables in EAS Build and Workflows jobs

Every EAS Build and Workflows job runs using environment variables from one of the available environments. You can specify which environment's variables to use by setting the environment field in the build profile or using the --environment flag with commands.

Secret visibility setting

Secret is a visibility setting for environment variables that makes them not readable outside of EAS servers, including on the website and in EAS CLI. They are obfuscated in EAS Build and Workflows job logs. Secret environment variables are intended to provide values to EAS Build or Workflows jobs to alter how a job runs, such as setting NPM_TOKEN to install private packages. They do not provide additional security for values embedded in the application itself.

Sensitive visibility setting

Sensitive is a visibility setting for environment variables that obfuscates them in EAS Build and Workflows job logs. They can be made visible on the website using a toggle, and are readable in EAS CLI.

Use dotenv or Doppler for non-EAS environment variable management

If you want to manage environment variables without EAS, you can use tools like dotenv (Node-based loaders) or services such as Doppler that inject environment variables. These utilities allow you to create a .env file to store your environment variables.

EXPO_PUBLIC_ prefix behavior with EAS Hosting

When using .env files with EAS Hosting, environment variables prefixed with EXPO_PUBLIC_ are available in both client-side code and server-side code. Variables not prefixed with EXPO_PUBLIC_ are only available in server-side code.

.env file requirements for EAS commands to pick up variables

After creating the .env file, ensure that the file is not listed inside your .gitignore or .easignore files. Then it can be picked up by EAS commands like eas build, eas update, and so on.

Do not commit secrets to .env files when managing without EAS

When managing environment variables without EAS, avoid committing secrets to .env files.

Prepare .env files before running npx expo export for EAS Hosting

When using .env files with EAS Hosting, ensure that your local .env files include the correct environment variables before running the npx expo export command. The steps for including client-side and server-side environment variables are the same as when using EAS environment variables.

.env file loading and process.env.EXPO_PUBLIC_ replacement

The .env files load according to standard .env file resolution. All references in your code to process.env.EXPO_PUBLIC_[VARIABLE_NAME] are replaced with the corresponding value set in the .env files. Code inside node_modules directory is not affected for security purposes.

EAS is the recommended way to manage environment variables for cloud builds

EAS Environment Variables is the recommended approach for managing environment variables for cloud builds and updates. However, you can still work locally or with other tooling if needed.

Non-prefixed environment variables for build-time and app config

Variables without the EXPO_PUBLIC_ prefix can be used during app config resolution to configure app behavior. Keep visibility at least sensitive if you need to resolve config locally, as secrets stay on the server.

EAS CLI command to list environment variables

Use the command: eas env:list --environment ENVIRONMENT_NAME to verify what is set.

Default environments available in EAS

EAS provides three default environments: development, preview, and production. Environment variables can be reused across them or customized per environment.

Environment variable scope options

Project-wide variables apply to one project. Account-wide variables can be reused across projects and are merged with project variables at build time.

Environment variable visibility settings

Three visibility settings are available: secret for values that should never leave EAS servers, sensitive for values that may be revealed locally, and plain text for non-sensitive values.

Create environment variable via EAS dashboard

Navigate to Project settings > Environment variables and click the Add Variables button. Use the creation form to set the name, value, environment(s), visibility, and optional description.

EAS CLI command to create environment variables

Use the command: eas env:set --name VARIABLE_NAME --value VALUE --environment ENVIRONMENT --visibility VISIBILITY_TYPE

EXPO_PUBLIC_ prefix for client-side environment variables

Environment variables with the EXPO_PUBLIC_ prefix are available as process.env variables in the app's code and can be used dynamically to configure app behavior. Do not put secrets in EXPO_PUBLIC_ variables because everything in client bundles is readable by end users.

Example: Using EXPO_PUBLIC_API_URL in client code

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" />; }

Example: Using APP_VARIANT for dynamic app configuration

Using secret file variables in app config

For secret file variables like GOOGLE_SERVICES_JSON, use process.env variable with a fallback value for local development: googleServicesFile: process.env.GOOGLE_SERVICES_JSON ?? '/local/path/to/google-services.json'

EAS CLI command to delete environment variable

Use the command: eas env:delete to remove an existing environment variable.

EAS CLI command to pull environment variables

Use the command: eas env:pull --environment ENVIRONMENT_NAME to pull environment variables into a .env file for local development.

.env file structure after pulling from EAS

The pulled .env file contains the environment name as a comment, followed by plain text and sensitive variables. Secret variables are not included and are marked with a comment. The file should be kept in .gitignore to avoid leaks and precedence conflicts.

Export environment variables from EAS dashboard

Use the Export option in the EAS dashboard to download environment variables as a .env file and store it inside your project.

Custom environments availability and limitations

Creating custom environments is available only for Enterprise and production plans. Custom environments can be created when complex workflows require more flexibility beyond the three default environments.

Create custom environment in EAS dashboard

Navigate to Project settings > Environment variables, click Add Variables button. Under Environments, click the plus (+) icon to enter a name for a custom environment. The custom environment will be pre-selected and will show up as a selectable option for all environment variables as long as there is at least one environment variable linked to it.

Give your agent this brain