Flipper Common Utilities

Common errors

• TypeError: Cannot read properties of undefined (reading 'Logger')

  cause Attempting to `require()` named exports from 'flipper-common' in a CommonJS environment, which primarily ships as ES Modules.
  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.

• Error: Package subpath './lib/Logger' is not defined by 'exports' in .../node_modules/flipper-common/package.json

  cause Directly importing internal subpaths of the `flipper-common` package that are not exposed via its `exports` field in `package.json`.
  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.

• TS2305: Module ''flipper-common'' has no exported member 'SomeNonExistentType'.

  cause Trying to import a type or function that does not exist or is not publicly exported by `flipper-common`.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  Fix: For Flipper Zero development, refer to the Flipper Zero JavaScript SDK (e.g., `@flipperdevices/fz-sdk`) and documentation specific to that hardware platform.

Install

• npm install flipper-common npm
• yarn add flipper-common yarn
• pnpm add flipper-common pnpm

Imports

• Logger
  wrong:

  const Logger = require('flipper-common');

  correct:

  import { Logger } from 'flipper-common';

  Flipper common utilities are primarily consumed as ES Modules. CommonJS `require` is not officially supported and may lead to issues.
• Id
  wrong:

  import Id from 'flipper-common'; // Id is a named export, not default

  correct:

  import { Id } from 'flipper-common';

  Many utilities, including ID generation, are named exports. Avoid default import syntax unless explicitly documented.
• FlipperClient
  wrong:

  import { FlipperClient } from 'flipper-common'; // FlipperClient is a type, not a runtime value

  correct:

  import type { FlipperClient } from 'flipper-common';

  For TypeScript users, interfaces and types like `FlipperClient` should be imported using `import type` to ensure they are stripped from the JavaScript output.

Quickstart

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.

import { Logger, Id, FlipperClient } from 'flipper-common';

interface MyPluginClient extends FlipperClient {
  sendEvent: (event: string, payload: any) => void;
}

class MyFlipperPlugin {
  id: Id;
  logger: Logger;
  client: MyPluginClient;

  constructor(client: MyPluginClient) {
    this.id = new Id();
    this.logger = new Logger('MyFlipperPlugin');
    this.client = client;

    this.logger.info(`Plugin initialized with ID: ${this.id.newID()}`);
  }

  initiateConnection() {
    this.client.sendEvent('plugin-connected', { pluginName: 'MyFlipperPlugin', version: '1.0.0' });
    this.logger.debug('Sent connection event to Flipper desktop.');
  }

  // Example of using another utility or type
  processData(data: any) {
    const transactionId = this.id.newID();
    this.logger.verbose(`Processing data with transaction ID: ${transactionId}`);
    // Imagine further processing or sending data back via client
    this.client.sendEvent('data-processed', { id: transactionId, result: data });
  }
}

// Simulate a Flipper client for demonstration
const mockFlipperClient: MyPluginClient = {
  sendEvent: (event, payload) => {
    console.log(`[Mock Flipper Client] Event: ${event}, Payload: ${JSON.stringify(payload)}`);
  },
  // In a real FlipperClient, there would be more methods like 'onMessage', 'call', etc.
  // These are omitted for a minimal runnable example.
};

const plugin = new MyFlipperPlugin(mockFlipperClient);
plugin.initiateConnection();
plugin.processData({ value: 123, status: 'complete' });