Skip to main content
Lucent works in Expo apps that can load custom native modules. Use an Expo development build, EAS build, or a prebuilt native project generated by expo prebuild, expo run:ios, or expo run:android.
Expo Go is not a full Lucent replay environment. It can import the JavaScript package and render LucentProvider, but native screenshot replay, native crash capture, native network capture, and native log capture are disabled.

​
Choose the right Expo path

Current appRecommended path
Already using expo-dev-client or EAS buildsInstall Lucent, rebuild the development or production build, and run your app.
Using Expo Go onlyAdd expo-dev-client, create a development build, and test Lucent there.
Using prebuild or custom native codeInstall Lucent, run prebuild if needed, run pods for iOS, and rebuild native targets.

​
Install in an Expo app

1

Install the package

npm install @lucenthq/react-native
2

Add Expo dev client if you use local development builds

npx expo install expo-dev-client
3

Generate or update native projects

npx expo prebuild
If your native projects already exist and are committed, review the prebuild diff before committing it.
4

Run a native build

npx expo run:ios
npx expo run:android
For EAS development builds: 
eas build --profile development --platform ios
eas build --profile development --platform android
Open the resulting development build, not Expo Go.

​
Add the provider

import {
  LucentIdentify,
  LucentProvider,
  useLucentScreen,
} from "@lucenthq/react-native";

function AppContent() {
  useLucentScreen("Home");

  return <RootNavigator />;
}

export default function App() {
  return (
    <LucentProvider
      publicKey="luc_pk_..."
      autocapture={{ captureTouches: true }}
      options={{
        ingestBaseUrl: "https://ingest-api.lucenthq.com",
      }}
    >
      <LucentIdentify id={user?.id} email={user?.email} />
      <AppContent />
    </LucentProvider>
  );
}

​
Expo Go fallback behavior

Expo Go cannot load custom native modules from npm packages. In Expo Go:
  • LucentProvider, LucentIdentify, and useLucent() do not crash because the JavaScript API falls back safely.
  • Native screenshot replay is disabled.
  • Native crash capture is disabled.
  • Native network and log capture are disabled.
  • lucent.getSessionInfo() returns null.
  • Full session replay appears only after you run a development build, EAS build, or prebuilt native app.
Use Expo Go for screens that do not need Lucent replay validation. Use a native build when verifying Lucent sessions.

​
Processing controls

Expo sessions use the same processing controls as React Native sessions. Filters and sampling usually control whether a session is analyzed, not whether the app can send events at all. When you configure a Required URL such as /onboarding, emit path-style screen evidence from your Expo app: 
import { useLucentScreen } from "@lucenthq/react-native";

export function OnboardingScreen() {
  useLucentScreen("/onboarding");

  return <OnboardingFlow />;
}
Avoid relying on human screen labels such as Onboarding when the filter is a path like /onboarding. The same principle applies to Excluded URL filters: Lucent can only skip a mobile session for an excluded path when the session contains matching path-like screen evidence. For user, email, domain, property, anonymous-user, sampling, event-trigger, minimum-duration, privacy, capture-toggle, batching, and source-map behavior, see React Native processing controls.

​
Source-map and release metadata

The Expo config plugin is optional. You do not need it for replay capture. Autolinking is enough once Expo generates or builds the native app. Add the plugin only when you want Lucent source-map upload wrappers installed during prebuild. Source maps and release metadata make React Native JavaScript stack traces readable in Lucent. 
{
  "expo": {
    "plugins": [["@lucenthq/react-native/expo", { "skipOnConflict": true }]]
  }
}
Set these variables in EAS or your native build environment: 
LUCENT_SOURCEMAP_UPLOAD_URL=...
LUCENT_PUBLIC_KEY=luc_pk_...
LUCENT_RELEASE=1.2.3+123
Use the Metro helper to attach deterministic Lucent release metadata to serializer output: 
const { getDefaultConfig } = require("expo/metro-config");
const { withLucentMetroConfig } = require("@lucenthq/react-native/metro");

const config = getDefaultConfig(__dirname);

module.exports = withLucentMetroConfig(config, {
  release: process.env.LUCENT_RELEASE,
});

​
Verify Expo replay

  1. Launch a development build, EAS build, or prebuilt app.
  2. Navigate through a few screens.
  3. Trigger a custom event: 
    import { useLucent } from "@lucenthq/react-native";

const lucent = useLucent();

await lucent.track("expo_replay_test", {
  source: "development-build",
});
  4. Open app.lucenthq.com -> Sessions.
  5. Confirm the session shows mobile screenshot replay.

​
Troubleshooting

You are running in Expo Go. Create a development build with expo-dev-client, run npx expo run:ios, run npx expo run:android, or install an EAS build. Expo Go cannot load Lucent’s native screenshot replay module.
Rebuild the native app after installing @lucenthq/react-native. A Metro reload is not enough because the native module must be compiled into the app. Also confirm the public key starts with luc_pk_ and the app can reach https://ingest-api.lucenthq.com.
Run npx expo prebuild and rebuild. If iOS fails, run npx pod-install. If Android fails, make sure Android Studio command-line tools, a compatible JDK, and ANDROID_HOME or ANDROID_SDK_ROOT are configured.
The plugin is optional and is only for source-map metadata and upload hooks. If you do not need those hooks, remove the plugin from app.json and rerun prebuild. Replay capture still works through native module autolinking.
Confirm the session lasted longer than replay.minimumDurationMs, if set. Confirm sampling.sessionReplay is not 0. If you configured replay.eventTriggers, call lucent.track() with one of those names before expecting screenshot recording to begin.

React Native SDK

Install, configure, and use the complete mobile SDK API.

Browser SDK

Use @lucenthq/sdk for web apps and rrweb-based browser replay.