Blaze
  1. Configuration
  2. /
  3. Environment Variables

Environment Variables

On this page
How They Work Edit Variables The KEY=value Format Read Them in Dart Dart Only Keep Values Safe Troubleshooting Next Steps

Environment variables are values your Dart code reads at build time, such as an API base URL or a feature switch.

How They Work

Each application has one set of variables. Every deployment of the app, on iOS and on Android and for every target, passes each variable to flutter build as --dart-define=KEY=value. Your Dart code reads them with String.fromEnvironment, bool.fromEnvironment or int.fromEnvironment.

Blaze stores the values encrypted and never puts them in the page. They are sent only to the build runner, when a deployment starts, so a change applies to the next deployment and not to one that is already running.

There is one set per app. Blaze has no per-platform, per-target or per-branch values, and no secret or platform flags on a variable.

Edit Variables

1

Open the Environment card

Open the application page. The Environment card, under Build infrastructure, shows how many variables are set. Click that number, or choose Edit variables… from the card's ··· menu.

2

Reveal the values

The editor loads the saved variables with their values hidden. Click Reveal values, or click the list, to edit them as text.

3

Edit and save

Change the lines and click Save. Save stays disabled until the saved variables have loaded, so a save can never replace variables the editor did not receive.

Only the person who created the app and the workspace's owners and admins can open or change its variables.

The KEY=value Format

# Lines starting with # are ignored
API_URL=https://api.example.com
FEATURE_NEW_CHECKOUT=true
RETRY_LIMIT=3
  • One KEY=value per line. Blank lines and lines starting with # are ignored.
  • A name uses letters, digits and underscores, and does not start with a digit. API_URL and _TOKEN work; 1KEY, MY-KEY and export API_URL are rejected with the line number.
  • The value is everything after the first =, with spaces at either end removed. Quotes are kept: API_URL="https://api.example.com" makes the quotes part of the value.
  • A value cannot span more than one line.
  • If a name appears twice, the last line wins.
  • The whole text can be up to 20,000 characters.

Read Them in Dart

class Env {
  static const apiUrl = String.fromEnvironment(
    'API_URL',
    defaultValue: 'https://staging.example.com',
  );

  static const newCheckout = bool.fromEnvironment('FEATURE_NEW_CHECKOUT');

  static const retryLimit = int.fromEnvironment('RETRY_LIMIT', defaultValue: 3);
}

Call these constructors with const, as above: Dart only guarantees fromEnvironment works in a constant. Names are case-sensitive, and a variable that is not set reads as the defaultValue (an empty string, false or 0 if you give none). Platform.environment does not see these values, because they are compiled in rather than set on the device.

To run your app locally with the same values, pass them yourself:

flutter run --dart-define=API_URL=https://api.example.com --dart-define=FEATURE_NEW_CHECKOUT=true

Dart Only

Blaze passes variables to Flutter as --dart-define and nowhere else. They are not Xcode build settings, Info.plist or .xcconfig substitutions, Gradle properties, AndroidManifest.xml placeholders or shell environment variables on the runner. A $(GOOGLE_MAPS_API_KEY) in Info.plist builds as an empty string, and a Gradle file that reads GOOGLE_MAPS_API_KEY as a property fails the Android build.

Native access to environment variables is not supported. For a value native code needs at build time, such as a Maps SDK key in Info.plist or AndroidManifest.xml, keep it in the native project files in your repository. For a value native code only needs while the app runs, read it in Dart and hand it over through a platform channel.

Keep Values Safe

  • Values are encrypted at rest and sent only to the build runner for the deployment that claims them.
  • The build log Blaze shows you masks variable values. On Android, values shorter than 8 characters are not masked.
  • Values are compiled into your app, and anyone who has the .ipa or .aab can read them. Do not use them for secrets that must stay on a server, such as a payment provider's secret key or an admin token. Keys that are meant to ship in apps, such as a restricted Maps key, are fine.

Troubleshooting

Dart reads an empty value or the default. Check the spelling and case of the name, check that the lookup is const, and deploy again if you added the variable after the deployment started.

Save reports a line. Line 4 is not KEY=value. means that line has no =. Line 4: "MY-KEY" is not a valid variable name. means the name uses a character other than letters, digits and underscores, or starts with a digit.

The editor never shows the variables. Only the app's creator and workspace owners and admins can load them. Ask one of them to make the change.

A native setting is empty or the Android build fails after using a variable in Info.plist or Gradle. Variables reach Dart only. See Dart Only.

Next Steps