Docs
BlogChangelogStar Us on GitHub
HomeGuidesEASReferenceLearn
ArchiveExpo SnackDiscord and ForumsNewsletter

This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Integrate a third-party package with EAS Observe

Edit page

Learn how to add an optional EAS Observe integration to a third-party package.

Third-party packages can integrate with EAS Observe to send events that help developers identify performance and usage issues. These are often problems that are difficult to detect from application code alone.

Events should describe actionable issues that developers can fix. For example, a package might report:

  • An image that is much larger than the device's screen
  • A background task that takes too long to complete
  • A native resource that loads slowly

Prerequisites

Prerequisites

2 requirements

1.

Expo SDK 57 and later

Third-party integrations require SDK 57 and later to access Observe.initIntegration().

2.

An app already using EAS Observe

Follow Get started to install expo-observe and create your first build.

1

Add expo-observe as an optional peer dependency

Add expo-observe as an optional peer dependency so your package continues to work when it is not installed. Also, add it as a development dependency for TypeScript types and tests. Do not add it as a required runtime dependency.

package.json
{
  "peerDependencies": {
    "expo-observe": ">=57.0.0"
  },
  "peerDependenciesMeta": {
    "expo-observe": {
      "optional": true
    }
  },
  "devDependencies": {
    "expo-observe": "^57.0.0"
  }
}

Load the package with require() inside a try/catch block. Use typeof import() to preserve its TypeScript types:

observe.ts
let observeModule: typeof import('expo-observe') | undefined;

try {
  observeModule = require('expo-observe') as typeof import('expo-observe');
} catch {
  // The integration remains disabled when expo-observe is not installed.
}

2

Declare the integration configuration

Use declaration merging to add your package's integration key to expo-observe:

observe.types.ts
export type YourPackageIntegrationConfig = {
  thresholdMs?: number;
};

declare module 'expo-observe' {
  interface ObserveIntegrationsConfig {
    'your-package'?: boolean | YourPackageIntegrationConfig;
  }
}

Export this declaration from your package entry point so TypeScript loads it when users import your package.

Developers using your package can then enable the integration with Observe.configure():

app/_layout.tsx
import { Observe } from 'expo-observe';

Observe.configure({
  integrations: {
    'your-package': true,
  },
});

If the integration accepts options, developers can pass a configuration object instead of true:

app/_layout.tsx
Observe.configure({
  integrations: {
    'your-package': {
      thresholdMs: 1500,
    },
  },
});

3

Initialize the integration

Call Observe.initIntegration() with your integration key. The callback receives the configuration for your integration:

observe.ts
export function initObserveIntegration() {
  // The `typeof window` check skips initialization during server-side rendering on web.
  if (typeof window !== 'undefined' && observeModule) {
    const { Observe } = observeModule;

    Observe.initIntegration('your-package', config => {
      if (config) {
        enableObserveIntegration(config === true ? {} : config);
      }
    });
  }
}

let enabled = false;

function enableObserveIntegration() {
  // Initialize the integration here
  // For example:
  enabled = true;
}

Implement enableObserveIntegration() in your package. The callback does not run when the integration is omitted or set to false.

Call the initialization function from your package entry point:

index.ts
import { initObserveIntegration } from './observe';

export type { YourPackageIntegrationConfig } from './observe.types';

initObserveIntegration();

4

Log events

Call Observe.logEvent() when your package detects an actionable issue. Use a lowercase event name with the package name as the first segment. Separate segments with periods:

observe.ts
export function logExpensiveOperation(durationMs: number, thresholdMs: number) {
  if (!observeModule || !enabled) {
    return;
  }

  const { Observe } = observeModule;

  Observe.logEvent('your-package.expensive-operation', {
    severity: 'warn',
    body: 'Reduce the work performed by this operation or increase the configured threshold.',
    attributes: {
      durationMs,
      thresholdMs,
    },
  });
}

For more information about naming events and adding details, see User-defined events.