Registry / http-networking / flipper-server-client

flipper-server-client

JSON →
library0.273.0jsnpmunverified

The `flipper-server-client` package provides a lightweight JavaScript/TypeScript abstraction for connecting to and interacting with a Flipper Server instance. It is part of the broader Flipper ecosystem, an open-source debugging platform for iOS, Android, and React Native applications, developed by Meta (formerly Facebook). The current stable version is 0.273.0, and the project demonstrates a rapid release cadence, often releasing new versions weekly or bi-weekly, reflecting active development. Its primary role is to enable external tools or scripts to programmatically communicate with a running Flipper Server, allowing for automation, custom debugging flows, or integration with non-standard environments. Key differentiators include its tight integration with the Flipper ecosystem and its focus on providing a simple API for server interaction, distinct from the desktop Flipper application itself.

npm install flipper-server-client
INSTALL
IMPORT
SIG · FLIPPER-SERVER-CLI
F
flipper-server-client
http-networkingjavascriptv0.273.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

FlipperServerClient
import { FlipperServerClient } from 'flipper-server-client';
const FlipperServerClient = require('flipper-server-client');
Primary class for establishing a connection to the Flipper server. The package is primarily designed for modern ESM usage.
IFlipperServerState
import type { IFlipperServerState } from 'flipper-server-client';
TypeScript interface for accessing the server's state, useful for type-checking and understanding available data structures exchanged with the server.
ServerConnectionStatus
import { ServerConnectionStatus } from 'flipper-server-client';
Enum representing the current connection status of the Flipper server client, enabling programmatic handling of connection states.

Demonstrates how to instantiate `FlipperServerClient`, establish a connection to a Flipper server, register event listeners for errors and status changes, send an example message to a plugin, and listen for incoming messages from the server before gracefully disconnecting. This provides a foundational setup for custom Flipper integrations.

import { FlipperServerClient } from 'flipper-server-client'; async function connectToFlipper() { // Optionally provide a custom FlipperServerConfig here if not using defaults const client = new FlipperServerClient(); // Event listener for errors client.on('error', (err) => { console.error('Flipper client error:', err.message); }); // Event listener for connection status changes client.on('status', (status) => { console.log('Flipper client status:', status); }); try { console.log('Attempting to connect to Flipper server...'); await client.connect(); console.log('Successfully connected to Flipper server!'); // Example: Sending a message/command to a hypothetical Flipper plugin // The exact 'pluginId', 'method', and 'payload' depend on the Flipper plugin protocol. console.log('Sending example message...'); await client.send('my-custom-plugin', 'doSomething', { value: 123, message: 'Hello from client!' }); console.log('Example message sent.'); // Listen for incoming messages from the Flipper server client.on('message', (pluginId, method, payload) => { console.log(`Received message from plugin '${pluginId}': method '${method}' with payload:`, payload); if (method === 'responseToSomething') { console.log('Received expected response:', payload); } }); // Keep the connection active for a short period to observe messages // In a real application, you'd manage the client lifecycle more robustly. await new Promise(resolve => setTimeout(resolve, 15000)); await client.disconnect(); console.log('Disconnected from Flipper server.'); } catch (e: any) { console.error('Failed to connect or interact with Flipper server:', e.message); } } connectToFlipper();
Debug
Known issues
breakingAs a 0.x.y versioned package, `flipper-server-client` does not strictly adhere to semantic versioning. Breaking changes to the API can occur in minor or even patch releases. Developers should exercise caution and thorough testing when upgrading.
fix
Always consult the official Flipper `CHANGELOG.md` (located at `desktop/static/CHANGELOG.md` in the main Flipper repository) before upgrading `flipper-server-client` to understand potential API changes and required migration steps for your integration.
affects: >=0.1.0
gotchaThe `flipper-server-client` requires a running `flipper-server` process to connect. This server is typically part of the Flipper desktop application but can also run independently. Connection attempts will fail if no server is accessible on the configured host and port (defaulting to `localhost:52787`).
fix
Ensure the Flipper desktop application is running, or start the `flipper-server` manually before attempting to connect. Verify network configurations and firewall rules if experiencing `Connection refused` errors to the default WebSocket port.
affects: >=0.1.0
gotchaThe client-server communication protocol, including the structure of commands and events, is tightly coupled to the specific `flipper-server` version. Significant version discrepancies between `flipper-server-client` and the target `flipper-server` can lead to unexpected behavior, malformed messages, or connection failures.
fix
Strive to keep your `flipper-server-client` package version synchronized with the version of the Flipper desktop application (and thus `flipper-server`) you are targeting. Check Flipper documentation or release notes for any explicit compatibility matrices.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Could not connect to Flipper server at ws://localhost:52787. Connection refused.
The Flipper server process is not running, or a firewall is blocking the connection on the default WebSocket port (52787).
fix
Start the Flipper desktop application or ensure `flipper-server` is running independently. Check local firewall settings and confirm no other process is using port 52787.
TypeError: FlipperServerClient is not a constructor
This typically occurs when attempting to use a CommonJS `require()` statement or an incorrect named import in an environment expecting ESM, or vice-versa.
fix
Verify your project is configured for ES Modules (e.g., `"type": "module"` in `package.json` for Node.js) and use `import { FlipperServerClient } from 'flipper-server-client';`. If forced to use CommonJS, ensure your bundler/transpiler correctly handles ESM imports.
Argument of type '"status"' is not assignable to parameter of type '"error" | "close" | "open"'.
The TypeScript compiler indicates that the event string provided to the `client.on()` method is not a known event type for the `FlipperServerClient` instance.
fix
Consult the TypeScript type definitions (`.d.ts` files) for `flipper-server-client` to determine the exact string literals for supported events. The specific events exposed might vary by version.
Upgrade
Version history
0.273.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
8 hits · last 30 days
node
8
Resources
flipper-server-client — npm install flipper-server-client · libregistry