Flipper and JS: why we added JavaScript support to a mobile debugging platform

This post was co-authored by Andrey Goncharov, Software Engineer at Meta.

Flipper is an open-source platform for debugging Android, iOS and React Native apps, allowing engineers to visualize, inspect and control their apps from a simple desktop interface. Since 2018, it has been a key tool at Meta and the wider community.

Within Flipper, there has been an undocumented and experimental JavaScript SDK, which extends support to browsers and Node.js apps. This has become established and stabilized at Meta, and we’ve now graduated it to an official SDK for JavaScript clients: js-flipper.

In this post, we will discuss:

• What js-flipper is and how to try it out
• How we use it at Meta
• How you could benefit from it

What is js-flipper?

js-flipper is a new NPM package that exposes a Flipper client to your JavaScript app and allows you to easily develop new or reuse existing Flipper plugins. Any JS client, whether it runs in your browser or on your Node.js server, can now connect to Flipper for a debugging session.

We’ve prepared a quickstart guide that will help you to create your first Flipper plugin and integrate it with your app. Or you can simply run our demo app and play with it!

Why is js-flipper an important step for the Flipper community?

Flipper’s superpower comes from the ecosystem of plugins and people who build them.

Flipper was originally built to debug mobile apps. It supports Android and iOS (including React Native) out of the box. The new js-flipper SDK expands Flipper’s focus area and adds support for non-mobile JavaScript applications.

We believe that many JS apps can benefit from reusing existing plugins. Based on our experience in Meta, we found that several web and mobile apps share a lot of infrastructure that is debuggable with the same plugins.

New JS developers will bring expertise and help grow our community. Flipper and its plugins’ UI are written in TypeScript + React, so newcomers’ experience will be very relevant.

js-flipper is the first attempt to use Flipper for non-mobile apps, and it can prove the idea of expanding Flipper to more platforms and use cases. We hope that it will trigger community growth and lead to an increasing number and quality of the plugins.

How does Flipper work?

Let's take a quick look at the principal architecture of Flipper:

Here is what happens:

1. Flipper constantly polls ADB (Android Debug Bridge, which allows developers to communicate with Android devices) for available Android devices and IDB (iOS Debug Bridge, which was created for a similar purpose) for available iOS devices.
2. If the device is running a program with an enabled Flipper client, the client tries to connect to Flipper on your laptop. That is, the client lets Flipper know that there is an app that it can talk to. Flipper and the app then establish a secure connection. Shortly after, they negotiate the list of supported plugins. Flipper then sends a request to list supported plugins to the device. Finally, the device replies with the list over the WebSocket connection.
3. The developer selects one of the connected applications / devices.
4. The developer clicks one of the available plugins.
5. The plugin starts talking to the app on the device via the message bus that is exposed by Flipper. The plugin asks for necessary data from the app and shows it on the desktop UI.

At Meta, we have many active plugins across a wide variety of devices, not just phones, but also AR/VR, desktop applications, etc. At its core, Flipper is data-agnostic and connects data flows to plugin displays. All Flipper core (we call it Flipper Server) knows is what devices and Flipper-enabled apps are out there. We hope it gets us on the same page regarding why plugins (and plugin developers!) are crucial for Flipper.

Another important conclusion that you can draw from the diagram is that the state of Flipper plugins is ephemeral and lives in the UI.

How we use js-flipper at Meta

Flipper and its plugins are the crucial tools for engineers in Meta, and they cover most of the use cases and flows that one wants to debug in the mobile world. About three years ago, two teams who were working on JS apps that were targeting mobile platforms asked if they could get a similar debugging experience—they were building a Facebook app for KaiOS and a new mobile Facebook web site.

Both projects share a lot of infrastructure and custom solutions with mobile Facebook clients, and a lot of existing plugins were ready to be reused. Therefore, we decided to implement a WebSocket based client and benefit from the ecosystem of plugins out of the box. That’s how the first version of js-flipper was born—we called it flipper-js-client-sdk.

The second big use case for js-flipper appeared unexpectedly. We use a custom build of VS Code with several in-house built extensions. Similarly to our mobile JS apps, the core part of VS Code and its extensions could benefit from plugins we already had, and specifically from plugins that are built for telemetry and performance debugging.

In both cases we could have taken an alternative approach by building Chrome Dev Tools Extensions to replicate existing Flipper plugins, and infra to pipe data to them. However, the existing ecosystem and ease of developing new Flipper plugins outweighed the alternative. In addition, we can debug JS apps that don’t have access to Chrome Dev Tools. The WebSocket based library gives a lot of flexibility.

When to use js-flipper

Here are some scenarios where js-flipper can be useful:

1. Extending the debugging experience from mobile to web apps in the case of shared infrastructure and logic. Js-flipper can enable capabilities available for mobile developers and make the experience consistent across platforms. It can be done both for custom build and open-sourced plugins.
2. Debugging complex, sometimes distributed, JS based applications. In our case it is VS Code and its extensions. WebSocket based communication protocol makes js-flipper pluggable almost everywhere and lets developers benefit from debugging with Flipper plugins.
3. JS-flipper opens an alternative way to debug your React Native apps. See this GitHub thread for details.

Share your ideas and success stories on Flipper GitHub discussions!

Next steps

If you want more technical details about the message protocol or want to learn what it takes to support a new platform, check out this blog post in Flipper blog.

Flipper is supported by Meta. Our team's goal is to support Flipper as a plugin-based platform for which we maintain the infrastructure. We don't typically invest in individual plugins, but we do love plugin improvements.

For that reason, we've marked many requests in the issue tracker as PR Welcome. Contributing changes should be as simple as cloning the repository and running yarn && yarn start in the desktop/ folder.

We are looking forward to your PRs!

To learn more about Meta Open Source, visit our open source site, subscribe to our YouTube channel, or follow us on Twitter, Facebook and LinkedIn.