Quick Start

npm

bash npm install expo-build-flags

yarn

bash yarn add expo-build-flags

pnpm

bash pnpm add expo-build-flags

typescript is a peer dependency and should already be in your Expo project.

1. Initialize

   npm
   bash npx build-flags init
   yarn
   bash yarn build-flags init
   pnpm
   bash pnpm build-flags init

   This scaffolds a flags.yml at the project root, detects your source directory (src/ or app/), generates the initial buildFlags.ts module, and adds the generated file to .gitignore.

2. Define a flag

   Open the generated flags.yml and add a flag:

   flags.yml

   mergePath: src/constants/buildFlags.ts
   flags:
     newCheckout:
       value: false
       meta:
         team: growth

   mergePath is the relative path where the generated TypeScript module will be written. The value field is the default boolean state of the flag.

3. Generate the runtime module

   npm
   bash npx build-flags override
   yarn
   bash yarn build-flags override
   pnpm
   bash pnpm build-flags override

   This reads flags.yml and writes the module at your mergePath:

   src/constants/buildFlags.ts

   // This file is auto-generated by expo-build-flags
   export const BuildFlags = {
     newCheckout: false,
   };

4. Use the flag in code

   src/screens/checkout.tsx

   import { BuildFlags } from "../constants/buildFlags";
   
   export function CheckoutScreen() {
     if (BuildFlags.newCheckout) {
       return <NewCheckoutFlow />;
     }
     return <LegacyCheckoutFlow />;
   }

5. Override a flag during development

   Prefix a flag name with + to enable or - to disable:

   npm

   bash npx build-flags override +newCheckout

   yarn

   bash yarn build-flags override +newCheckout

   pnpm

   bash pnpm build-flags override +newCheckout

   The generated module now has newCheckout: true. Your bundle server picks up the change on the next reload.

Your project structure should now look like this:

• flags.yml - src/ - constants/ - buildFlags.ts (generated, gitignored) - screens/ - checkout.tsx - …

Integrate into your dev workflow

Since the generated module is gitignored, new contributors won’t have it after cloning. We recommend adding the override command to your postinstall script so it runs automatically after npm install:

package.json

{
  "scripts": {
    "postinstall": "build-flags override"
  }
}

This ensures every developer has a valid buildFlags.ts without needing to remember a manual step.

What’s next?

From here you can layer on additional capabilities:

• Config Plugin — set flags for EAS native builds via an environment variable.
• Babel Plugin — enable tree shaking so disabled features are stripped from production bundles.
• Flagged Autolinking — exclude native modules from autolinking when their flag is off.
• Flag Inversion — invert a flag’s default value for specific bundle IDs.