{"id":13190,"library":"flipper-server-client","title":"Flipper Server Client","description":"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.","status":"active","version":"0.273.0","language":"javascript","source_language":"en","source_url":"https://github.com/facebook/flipper","tags":["javascript","Flipper","typescript"],"install":[{"cmd":"npm install flipper-server-client","lang":"bash","label":"npm"},{"cmd":"yarn add flipper-server-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add flipper-server-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary class for establishing a connection to the Flipper server. The package is primarily designed for modern ESM usage.","wrong":"const FlipperServerClient = require('flipper-server-client');","symbol":"FlipperServerClient","correct":"import { FlipperServerClient } from 'flipper-server-client';"},{"note":"TypeScript interface for accessing the server's state, useful for type-checking and understanding available data structures exchanged with the server.","symbol":"IFlipperServerState","correct":"import type { IFlipperServerState } from 'flipper-server-client';"},{"note":"Enum representing the current connection status of the Flipper server client, enabling programmatic handling of connection states.","symbol":"ServerConnectionStatus","correct":"import { ServerConnectionStatus } from 'flipper-server-client';"}],"quickstart":{"code":"import { FlipperServerClient } from 'flipper-server-client';\n\nasync function connectToFlipper() {\n  // Optionally provide a custom FlipperServerConfig here if not using defaults\n  const client = new FlipperServerClient();\n\n  // Event listener for errors\n  client.on('error', (err) => {\n    console.error('Flipper client error:', err.message);\n  });\n\n  // Event listener for connection status changes\n  client.on('status', (status) => {\n    console.log('Flipper client status:', status);\n  });\n\n  try {\n    console.log('Attempting to connect to Flipper server...');\n    await client.connect();\n    console.log('Successfully connected to Flipper server!');\n\n    // Example: Sending a message/command to a hypothetical Flipper plugin\n    // The exact 'pluginId', 'method', and 'payload' depend on the Flipper plugin protocol.\n    console.log('Sending example message...');\n    await client.send('my-custom-plugin', 'doSomething', { value: 123, message: 'Hello from client!' });\n    console.log('Example message sent.');\n\n    // Listen for incoming messages from the Flipper server\n    client.on('message', (pluginId, method, payload) => {\n      console.log(`Received message from plugin '${pluginId}': method '${method}' with payload:`, payload);\n      if (method === 'responseToSomething') {\n        console.log('Received expected response:', payload);\n      }\n    });\n\n    // Keep the connection active for a short period to observe messages\n    // In a real application, you'd manage the client lifecycle more robustly.\n    await new Promise(resolve => setTimeout(resolve, 15000));\n\n    await client.disconnect();\n    console.log('Disconnected from Flipper server.');\n  } catch (e: any) {\n    console.error('Failed to connect or interact with Flipper server:', e.message);\n  }\n}\n\nconnectToFlipper();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"As 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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"The `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`).","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The Flipper server process is not running, or a firewall is blocking the connection on the default WebSocket port (52787).","error":"Error: Could not connect to Flipper server at ws://localhost:52787. Connection refused."},{"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.","cause":"This typically occurs when attempting to use a CommonJS `require()` statement or an incorrect named import in an environment expecting ESM, or vice-versa.","error":"TypeError: FlipperServerClient is not a constructor"},{"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.","cause":"The TypeScript compiler indicates that the event string provided to the `client.on()` method is not a known event type for the `FlipperServerClient` instance.","error":"Argument of type '\"status\"' is not assignable to parameter of type '\"error\" | \"close\" | \"open\"'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}