Integrate Luciq with Expo

This page covers the recommended way to install and configure the Luciq SDK in your Expo application using the Expo Plugin system.

Overview

Luciq supports modern Expo development. The recommended way to install Luciq is by using our Expo Plugin, which automatically handles native project configuration and automates the sourcemap uploading process for your standard builds.

The Luciq SDK is not supported in the Expo Go app. You will need to create a development build or use a simulator/physical device.

---

Recommended Setup: Using the Expo Plugin

This is the simplest and most robust way to integrate Luciq into an Expo project.

1

Install the SDK

In your project directory, install the Luciq SDK.

npm

Install (npm)

npm install @luciq/react-native

yarn

2

Configure the Expo Plugin

Add the @luciq/react-native plugin to the plugins array in your app.json file.

app.json

{
  "expo": {
    "plugins": [
      [
        "@luciq/react-native",
        {
          "addScreenRecordingBugReportingPermission": true //check note below
        }
      ]
    ]
  }
}

The addScreenRecordingBugReportingPermission is an optional helper that automatically adds the required microphone and photo library permissions on iOS and the foreground service permission on Android for the screen recording feature.

3

Rebuild Your App

After adding the plugin, rebuild your app's native directories for the changes to take effect.

Rebuild (local)

npx expo prebuild

This command is for local development. If you are using EAS Build, this step is handled automatically for you during the build process.

This command will modify your ios and android directories to include the necessary Luciq configurations.

4

Initialize the SDK

Import and initialize Luciq in your app's main file (e.g. App.js):

import Luciq, { InvocationEvent } from '@luciq/react-native';

Luciq.init({
  token: 'APP_TOKEN',
  invocationEvents: [InvocationEvent.shake],
});

You can find your app token by selecting SDK Integration in the Settings menu from your Luciq dashboard.

---

Automatic Sourcemap Uploads

A key benefit of using the Expo Plugin is that it automatically handles sourcemap uploads for all your standard Expo builds (eas build). By adding the plugin to your app.json, it will detect your builds and upload the correct sourcemaps to Luciq with no additional configuration required.

This automatic process applies to standard builds only. For Expo Updates (OTA), you must manually upload sourcemaps using our CLI. See our Over-the-Air (OTA) Updates Guide for more details.

---

OTA updates (expo-updates)

Supported

Luciq.setOverAirVersion() attaches the active OTA update identifier to all events:

import * as Updates from 'expo-updates';
import Luciq, { OverAirUpdateServices } from '@luciq/react-native';
Luciq.setOverAirVersion({
  service: OverAirUpdateServices.expo,
  version: Updates.updateId ?? 'embedded',
});

Once set, every report, crash, and APM span carries the update version.

Enriching with channel, runtime version, and emergency-launch state

These fields are not auto-collected. Add them as user attributes and tags so you can filter on them in the dashboard:

import * as Updates from 'expo-updates';
import Luciq from '@luciq/react-native';

Luciq.setUserAttribute('expo.updates.channel', Updates.channel ?? 'unknown');
Luciq.setUserAttribute('expo.updates.runtime_version', Updates.runtimeVersion ?? 'unknown');
Luciq.setUserAttribute('expo.updates.is_embedded', String(Updates.isEmbeddedLaunch));

if (Updates.isEmergencyLaunch) {
  Luciq.appendTags(['expo.updates.emergency_launch']);
  Luciq.setUserAttribute(
    'expo.updates.emergency_launch_reason',
    Updates.emergencyLaunchReason ?? 'unknown',
  );
  Luciq.logUserEvent('expo_updates_emergency_launch');
}

Call this once after Luciq.init(), ideally inside your root component or in App.tsx.

---

Expo execution environment context (expo-constants)

Expo Constants metadata (Expo Go vs standalone vs bare, EAS project ID, app config name/version, SDK version) is not collected automatically. Forward it as user attributes:

import Constants from 'expo-constants';
import Luciq from '@Luciq/react-native';

Luciq.setUserAttribute('expo.execution_environment', Constants.executionEnvironment);
Luciq.setUserAttribute('expo.sdk_version', Constants.expoConfig?.sdkVersion ?? '');
Luciq.setUserAttribute('expo.eas_project_id', Constants.expoConfig?.extra?.eas?.projectId ?? '');
Luciq.setUserAttribute('expo.app_name', Constants.expoConfig?.name ?? '');
Luciq.setUserAttribute('expo.app_version', Constants.expoConfig?.version ?? '');

---

Expo Router (expo-router)

Supported

Screen-load APM spans fire automatically when a route renders, regardless of whether you got there via router.push, router.replace, or a deep link. No extra code is needed - this is part of the standard navigation integration.

Tracking router.prefetch()

router.prefetch() does not surface in screen-load timings because no screen mounts. To measure prefetch cost, wrap it with a custom APM span:

import { useRouter } from 'expo-router';
import { APM } from '@luciq/react-native';

export function useTracedRouter() {
  const router = useRouter();
  return {
    ...router,
    prefetch: async (href: string) => {
      const span = await APM.startCustomSpan(`navigation.prefetch:${href}`);
      try {
        return await router.prefetch(href);
      } finally {
        await span?.end();
      }
    },
  };
}

Use useTracedRouter() instead of useRouter() anywhere you call prefetch.

---

Image and asset loading (expo-image, expo-asset)

Network requests for images are already captured by Luciq's network logger. The cache and decoding work that happens after the request - which is what Image.prefetch, Image.loadAsync, and Asset.loadAsync do - is not auto-instrumented.

To time these calls, wrap them with custom spans:

import { Image } from 'expo-image';
import { APM } from '@luciq/react-native';

export async function tracedImagePrefetch(urls: string | string[]) {
  const span = await APM.startCustomSpan('expo-image.prefetch');
  try {
    return await Image.prefetch(urls);
  } finally {
    await span?.end();
  }
}

The same pattern applies to Image.loadAsync and Asset.loadAsync. Keep span names stable so they aggregate cleanly in the APM dashboard.

---

EAS Build pipeline visibility

EAS builds run on remote infrastructure outside the app, so the SDK cannot observe them. There is no Luciq-side hook for eas-build-pre-install, eas-build-on-success, or eas-build-on-error.

---

Legacy: Using a Custom Development Client

For older managed workflows that do not use the Expo plugin system, you will need to use Expo’s custom development client.

1

Run the dev client package install:

Install expo-dev-client

npx expo install expo-dev-client

2

Modify your package.json scripts to use the --dev-client flag for the start command.

package.json (scripts)

"scripts": {
  "start": "expo start --dev-client",
  "android": "expo run:android",
  "ios": "expo run:ios"
}

3

Proceed with the Luciq SDK installation and initialization as described above.