Managing environment variables in Expo and EAS has always been a balancing act between flexibility, security, and simplicity. Earlier methods followed standardized approaches for environment variables but introduced trade-offs that made developing and maintaining build pipelines cumbersome. Whether you were configuring builds, managing secrets, or working locally, you likely encountered challenges with duplication, limited compatibility, or unclear setups.

Recently, Expo announced changes to the way environment variables will work in EAS. In this post, we’ll explore the old approaches, the issues they created, and how Expo’s latest updates simplify the process.

How environment variables used to work with Expo and EAS

The earlier approaches to variables in Expo and EAS had multiple options for configuration. EAS Build and EAS Update picked up any variables prefixed with EXPO_PUBLIC_, which gave a variety of ways to define and manage variables, which unfortunately came with their own trade-offs.

Feel free to skip the contrasting options below. However, they can be useful in understanding why some of the new EAS changes were implemented.

EAS Secrets

Variables could be defined as secrets via the EAS or the CLI.

Advantages

  • Provided a safe and centralized way to define secrets.
  • Worked seamlessly with both EAS Build and EAS Update.

Disadvantages

  • Not compatible with local preview/production builds.
  • Developers needed alternative methods for accessing secrets during local development.
  • Often convenient for non-secret values, but they had to be treated as secrets.

Dotenv files

Variables could be set up in .env files, following specific conventions., primarily used for the local development environment.

Advantages

  • Easy to tweak during development without affecting team-wide settings.
  • Compatible with any build method as long as variables were prefixed with EXPO_PUBLIC_.

Disadvantages

  • Sharing settings was cumbersome. Teams often relied on an env.template file for reference, which could lead to bad practices.
  • Not suitable for secrets.

eas.json per profile variables

Each profile defined within eas.json could define its own variables. These would only be used when building using EAS Build.

Advantages

  • Clear visibility of variable differences across build profiles.

Disadvantages

  • Not compatible with EAS Updates.
  • Not compatible with local preview/production builds.
  • Required alternative methods for accessing secrets during local development.
  • Not suitable for secrets.

CI/CD workflow yaml

Advantages

  • Compatible with EAS Updates in addition to EAS Builds.

Disadvantages

  • Restricted to CI/CD builds, making it unsuitable for developer-local preview/production builds.
  • Required alternative methods for accessing secrets during local development.
  • Not suitable for secrets.

CI/CD pipelines (GitHub Actions, Azure DevOps, etc.)

Advantages

  • Compatible with EAS Updates in addition to EAS Builds.
  • Flexible for adjusting variables at build time.
  • Secure handling of secrets through managed pipelines.

Disadvantages

  • Limited to managed CI/CD builds, excluding EAS CLI-triggered ones, as well as developer-local preview/production builds.
  • Maintaining consistency across environments could be challenging.
  • Required alternative methods for accessing secrets during local development.

Problems the old approach created

If your project required flexibility in how builds and updates were produced, you often had to duplicate variables across multiple locations and keep them in sync. This duplication added complexity and increased the risk of errors.

Builds for physical devices

Obviously, each developer needs to define variables locally for development. However, testing on physical devices often required generating a preview build. To avoid quickly exhausting the allotted EAS builds in your subscription, it was common to generate these builds locally. This means managing variables between CI/CD and local machines.

EAS config variables weren’t designed for app configuration

While the env section in eas.json profiles allowed you to define variables, they were mainly intended to configure the EAS server build environment. These variables couldn’t be used during local builds or EAS updates, making them impractical for app-level configuration.

The secrecy of EAS Secrets

EAS Secrets were intentionally restricted from external build servers to maintain security. However, this restriction reduced their practical value since you had to redefine secrets elsewhere for non-EAS builds.

This limitation also introduced troubleshooting headaches. Developers unfamiliar with the restriction could spend hours diagnosing missing secret values in builds that didn’t go through EAS Build. Personally, I lost considerable time resolving broken EAS updates before understanding this limitation.

What exactly did they add?

For all details, refer to Expo’s announcement:
Environment variables in EAS: new changes to simplify setup

Here are the key highlights:

  • Variables can now be defined in EAS as Plain text, Sensitive, or Secret.
  • All preview/production builds on EAS servers can access these variables.
  • You can configure environments in EAS and link them to profiles in eas.json.
  • The EAS CLI lets you generate .env.local files, streamlining local development.
  • Note the limitation: some variables are inaccessible outside EAS servers. Details here.

Implications for local development and development builds

Simplified local setup with EAS CLI

You can now define common, non-secret configurations in EAS and use npx eas-cli env:pull to create an env.local file. The Expo CLI will load this file when running a local development server.

No access to secret variables

Secrets from EAS will not be leaked into local environments. While the env.local file will include placeholders for secrets, these entries will be commented out, allowing developers to add values manually or ignore them as needed.

Seamless configuration for simulator and device builds

Local builds will rely on your .env.local file or system environment, but the EAS CLI ensures you can pull updated configurations quickly.

Using EAS Build with external CI/CD systems

Seamless integration of variables

Variables defined in EAS are fully compatible with builds, and you can organize them into environments [Expo’s overloaded term] for profile-specific use.

Building outside EAS servers

No access to secret variables

When using external infrastructure, secret variables defined in EAS aren’t accessible to prevent leaks. This does mean some duplication of variables between EAS and CI/CD configurations may be required. However, your CI/CD system likely offers secure handling of variables for builds.

EAS Update compatibility

Pipeline configuration required

When bundling an update, include the --environment flag for compatibility. Otherwise, the CLI will default to the local environment as before. Learn more here.

Access restrictions for updates

Like builds outside EAS servers, EAS Updates on non-EAS servers only include plain text and sensitive variables, excluding secrets. This aligns with past behavior (please correct me if I’m wrong). If you require access to secret variables, the introduction of Workflows appears to provide the ability to execute your update bundling workflow on EAS servers.

Conclusion

Expo’s new approach to managing environment variables tackles many of the pain points developers previously faced. By expanding EAS to act as a centralized storage for configurations and other variable-driven values, the new system simplifies workflows for most use cases. However, it’s not without its limitations.

Managing secrets remains a challenge for Expo developers, largely due to the constraints of native apps. Secrets are still inaccessible outside EAS environments, requiring developers to find alternative solutions. While Expo’s Workflows promise improvements for EAS Updates, there are still gaps for teams that don’t use EAS for their entire build process.

On the positive side, handling the differences between release and development builds has significantly improved. Variable management is more streamlined, and the EAS CLI simplifies identifying and pulling in differences. This feature is a welcome addition and will likely become an essential tool for many teams.

If you’re still navigating the transition or have unique use cases, it’s worth diving deeper into Expo’s announcement blog post, as well as their
docs on Environment variables in EAS.