Config Plugin

The config plugin integrates with expo prebuild and EAS Build so that flags are set at native build time.

What it does

When a native build runs, the config plugin will:

1. Read EXPO_BUILD_FLAGS from the environment (comma-separated, with optional +/- prefixes — see Syntax)
2. Generate the runtime buildFlags.ts module with the resolved flag values
3. Add an EXBuildFlags array to Info.plist (iOS)
4. Add a <meta-data android:name="EXBuildFlags"> tag to AndroidManifest.xml (Android)

The native metadata is informational — it lets you inspect which flags a given binary was built with. A convenience API for reading these values from native code is a planned goal.

Setup

1. Add the plugin to app.json

   app.json

   {
     "expo": {
       "plugins": ["expo-build-flags"]
     }
   }

2. Set flags in your EAS build profile

   eas.json

   {
     "build": {
       "staging": {
         "env": {
           "EXPO_BUILD_FLAGS": "newCheckout,betaDashboard"
         }
       }
     }
   }

3. Build

   eas build --profile staging

   The generated buildFlags.ts will have newCheckout and betaDashboard set to true.

EXPO_BUILD_FLAGS syntax

Entries are comma-separated. Each entry uses the same +/- convention as the build-flags override CLI:

Entry	Effect
flagName	Enable (same as +flagName)
+flagName	Enable — explicit form
-flagName	Disable — forces a default-true flag to false

Whitespace around entries (and between the prefix and the name) is ignored, so " foo, -bar " is equivalent to "foo,-bar". If the same flag appears with both prefixes, the disable wins.

eas.json

{
  "build": {
    "staging": {
      "env": {
        "EXPO_BUILD_FLAGS": "newCheckout,-legacyDashboard"
      }
    }
  }
}

The example above enables newCheckout and disables legacyDashboard for that build profile, regardless of the defaults committed to flags.yml.

Note

When flaggedAutolinking: true is set on the plugin, only the enabled env entries influence autolinking exclusions. Disabling a default-true flag via env will flip the runtime value but will not re-introduce its modules: exclusions for that build.

Skipping the CLI in EAS

If you run build-flags override in a postinstall script (as recommended in the Quick Start), you’ll want to skip it during EAS builds since the config plugin already handles generation. Use --skip-if-env:

package.json

{
  "scripts": {
    "postinstall": "build-flags override --skip-if-env EAS_BUILD"
  }
}

When EAS_BUILD is set (which EAS does automatically), the override command is a no-op. You can reference any CI var name here (not value).