expo-community-flipper

Flipper Support for Expo Apps <= SDK 47

🎉 As of Expo 48, Flipper support is available via the official build-properties plugin, with a simpler interface and proper support! read the docs announcement
If you're running into issues with the official build-properties plugin, check for an existing issue

⚠️ (SDK 46, 47) Please see this issue about known compatibility issues with other plugins.

The remainder of this README applies to installing expo-community-flipper for SDK 47 and earlier.

Usage (Quick Guide)

1. Install this module: yarn add expo-community-flipper

2. Add expo-community-flipper configuration to the plugins section of your app.json, as per the examples below. You have the option to specify the version of Flipper, though the one built in with React Native is (usually) sufficient.

If you don't specify anything, expo-community-flipper will default to the version of Flipper bundled with the version of React Native you're currently using.

Configuration

type FlipperOptions =
  | undefined // take the default options for the entire plugin
  | string // sets <root>.version and takes defaults for all nested options
  | {
      version?: string; // sets the flipper version to build against (defaults to undefined, uses react-native bundled version)
      ios?:
        | boolean // sets <root>.ios.enabled and takes defaults for all nested options
        | {
            enabled: boolean; // enable flipper for iOS (default true)
            stripUseFrameworks?: boolean; // strip instances of use_frameworks from the Podfile (default false)
          };
      android?:
        | boolean // sets <root>.android.enabled and takes defaults for all nested options
        | {
            enabled: boolean; // enable flipper for Android (default true)
          };
    };

Configuration of this plugin is done in app.json. all configurations are optional with defaults designed to minimize the chances of your build breaking.

{
  "expo": {
    "..."
    "plugins": [
      "expo-community-flipper"
    ]
  }
}

// or configured (See FlipperOptions above):

{
  "expo": {
    "..."
    "plugins": [
      ["expo-community-flipper", FlipperOptions]
    ]
  }
}

Disabling Flipper in CI (>= 45.1.0)

🛠️ 47.0.1 expo-community-flipper now supports the standard ENV['NO_FLIPPER'] == 1 flag to disable flipper. You may also simply omit this plugin via app.config.js when building a production version of your app, as Flipper is not enabled by default.

📜 Prior to 47.0.1, Flipper was disabled using ENV['FLIPPER_DISABLE'] == "1". This is still supported, but deprecated in favor of the emerging standard from the react-native team. In production, Flipper is automatically disabled by the react-native framework, but see this issue regarding a possible regression in upstream react-native/flipper.

Windows Users + Hermes

As of right now, using Windows with the Hermes engine requires you to run your app inside of a WSL environment. The tracked issue is here and if you have a Podfile, please let me know. It's likely an upstream issue, but we're continuing to look at build artifacts in case we spot something that may resolve this issue.

Versions

Starting with Expo SDK 46, Flipper manages its own compatibility layer (though it can be upgraded by specifying a version of Flipper that you want). Prior to SDK 46, we recommended running Flipper @ 0.123.0 as it had the widest range of compatibility with devices and simulators.

This package follows expo's policy for the deprecation of old SDKs. It's MAJOR version tracks against the Expo SDK version, making it easy to spot compatibility differences in your package.json file.

Testing

An /example directory is built with expo init example for each major SDK release with a default eas.json file. The plugin is directly linked using expo's filepath support for config plugins. You can run expo prebuild in the directory to verify the plugin is modifying build files appropriately.

example eas.json

{
  "cli": {
    "version": ">= 0.35.0"
  },
  "build": {
    "example": {
      "releaseChannel": "default",
      "channel": "default"
    }
  }
}

example app.json

{
  "expo": {
    "...": "... standard app.json entries ...",
    "plugins": [["./../build/withFlipper", "0.158.0"]]
  }
}

References

This code is based on the Flipper Getting Started Guide
Expo Config Plugins
Using the latest Flipper SDK
React Native Community's Typescript Template

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Jakob Heuser} 💻	_gregfenton 📖	_AronBe 📖	_rlam3 📖	_Slapbox 🐛	_{Jeremy Gollehon} 🐛	_{Nikola Kalinov} 🐛
_{Kudo Chien} 📖 💬 💻	_{Maxence Gilliot} 💬	_{Andrew Gerber} 🐛	_{Pim Knops} 🐛