{"id":14578,"library":"flipper-common","title":"Flipper Common Utilities","description":"flipper-common is a core utility package within the Facebook Flipper debugging platform, designed to provide shared functionalities and interfaces for `flipper-ui`, `flipper-server`, and Flipper plugins. It encapsulates common logic and types used across different components of the Flipper ecosystem, ensuring consistency and reducing code duplication. The package is currently at version 0.273.0 and maintains a rapid release cadence, often seeing multiple updates per month to align with the active development of the broader Flipper project. Its key differentiators lie in its deep integration within the Flipper architecture, serving as a foundational layer for building robust mobile (iOS/Android) and web/Node.js debugging plugins and server-side interactions, rather than being a general-purpose, standalone utility library.","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-common","lang":"bash","label":"npm"},{"cmd":"yarn add flipper-common","lang":"bash","label":"yarn"},{"cmd":"pnpm add flipper-common","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Flipper common utilities are primarily consumed as ES Modules. CommonJS `require` is not officially supported and may lead to issues.","wrong":"const Logger = require('flipper-common');","symbol":"Logger","correct":"import { Logger } from 'flipper-common';"},{"note":"Many utilities, including ID generation, are named exports. Avoid default import syntax unless explicitly documented.","wrong":"import Id from 'flipper-common'; // Id is a named export, not default","symbol":"Id","correct":"import { Id } from 'flipper-common';"},{"note":"For TypeScript users, interfaces and types like `FlipperClient` should be imported using `import type` to ensure they are stripped from the JavaScript output.","wrong":"import { FlipperClient } from 'flipper-common'; // FlipperClient is a type, not a runtime value","symbol":"FlipperClient","correct":"import type { FlipperClient } from 'flipper-common';"}],"quickstart":{"code":"import { Logger, Id, FlipperClient } from 'flipper-common';\n\ninterface MyPluginClient extends FlipperClient {\n  sendEvent: (event: string, payload: any) => void;\n}\n\nclass MyFlipperPlugin {\n  id: Id;\n  logger: Logger;\n  client: MyPluginClient;\n\n  constructor(client: MyPluginClient) {\n    this.id = new Id();\n    this.logger = new Logger('MyFlipperPlugin');\n    this.client = client;\n\n    this.logger.info(`Plugin initialized with ID: ${this.id.newID()}`);\n  }\n\n  initiateConnection() {\n    this.client.sendEvent('plugin-connected', { pluginName: 'MyFlipperPlugin', version: '1.0.0' });\n    this.logger.debug('Sent connection event to Flipper desktop.');\n  }\n\n  // Example of using another utility or type\n  processData(data: any) {\n    const transactionId = this.id.newID();\n    this.logger.verbose(`Processing data with transaction ID: ${transactionId}`);\n    // Imagine further processing or sending data back via client\n    this.client.sendEvent('data-processed', { id: transactionId, result: data });\n  }\n}\n\n// Simulate a Flipper client for demonstration\nconst mockFlipperClient: MyPluginClient = {\n  sendEvent: (event, payload) => {\n    console.log(`[Mock Flipper Client] Event: ${event}, Payload: ${JSON.stringify(payload)}`);\n  },\n  // In a real FlipperClient, there would be more methods like 'onMessage', 'call', etc.\n  // These are omitted for a minimal runnable example.\n};\n\nconst plugin = new MyFlipperPlugin(mockFlipperClient);\nplugin.initiateConnection();\nplugin.processData({ value: 123, status: 'complete' });\n","lang":"typescript","description":"This quickstart demonstrates how to initialize and use core utilities like `Logger` and `Id` within a simulated Flipper plugin context, leveraging TypeScript types such as `FlipperClient` for illustrative purposes."},"warnings":[{"fix":"Review the Flipper main repository's `desktop/static/CHANGELOG.md` for specific breaking changes and migration steps before upgrading. Ensure your `flipper-common` version aligns with other `flipper-*` packages you are using.","message":"As `flipper-common` is versioned `0.x.x` and part of a rapidly evolving internal Facebook project, breaking changes can be introduced in minor version increments. Always consult the detailed Flipper `CHANGELOG.md` (linked in npm metadata) when upgrading to a new minor version.","severity":"breaking","affected_versions":">=0.x.x"},{"fix":"For Flipper Zero development, refer to the Flipper Zero JavaScript SDK (e.g., `@flipperdevices/fz-sdk`) and documentation specific to that hardware platform.","message":"This `flipper-common` package is part of the Facebook Flipper debugging platform for mobile and web applications, not related to the Flipper Zero hardware device. Attempting to use these utilities for Flipper Zero development will result in incompatibility.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your project is configured for ES Modules (e.g., `\"type\": \"module\"` in `package.json` or using `.mjs` files) and use `import { Logger } from 'flipper-common';` syntax. If truly stuck in CommonJS, you might need dynamic `import()` or a bundler to transpile.","cause":"Attempting to `require()` named exports from 'flipper-common' in a CommonJS environment, which primarily ships as ES Modules.","error":"TypeError: Cannot read properties of undefined (reading 'Logger')"},{"fix":"Always import symbols directly from the main package entry point: `import { Logger } from 'flipper-common';`. Do not attempt to import from `flipper-common/lib/Logger` or similar internal paths.","cause":"Directly importing internal subpaths of the `flipper-common` package that are not exposed via its `exports` field in `package.json`.","error":"Error: Package subpath './lib/Logger' is not defined by 'exports' in .../node_modules/flipper-common/package.json"},{"fix":"Consult the official Flipper documentation or the package's type definitions (`.d.ts` files) to verify the correct names and availability of exported members. Flipper's internal nature means not all internal types or functions are exposed publicly.","cause":"Trying to import a type or function that does not exist or is not publicly exported by `flipper-common`.","error":"TS2305: Module ''flipper-common'' has no exported member 'SomeNonExistentType'."}],"ecosystem":"npm"}