> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lucenthq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Expo setup

> Use @lucenthq/react-native in Expo apps with development builds, EAS builds, or prebuilt native projects.

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`.

<Warning>
  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.
</Warning>

## Choose the right Expo path

| Current app                                   | Recommended path                                                                      |
| --------------------------------------------- | ------------------------------------------------------------------------------------- |
| Already using `expo-dev-client` or EAS builds | Install Lucent, rebuild the development or production build, and run your app.        |
| Using Expo Go only                            | Add `expo-dev-client`, create a development build, and test Lucent there.             |
| Using prebuild or custom native code          | Install Lucent, run prebuild if needed, run pods for iOS, and rebuild native targets. |

## Install in an Expo app

<Steps>
  <Step title="Install the package">
    ```bash theme={null}
    npm install @lucenthq/react-native
    ```
  </Step>

  <Step title="Add Expo dev client if you use local development builds">
    ```bash theme={null}
    npx expo install expo-dev-client
    ```
  </Step>

  <Step title="Generate or update native projects">
    ```bash theme={null}
    npx expo prebuild
    ```

    If your native projects already exist and are committed, review the prebuild
    diff before committing it.
  </Step>

  <Step title="Run a native build">
    ```bash theme={null}
    npx expo run:ios
    npx expo run:android
    ```
  </Step>
</Steps>

For EAS development builds:

```bash theme={null}
eas build --profile development --platform ios
eas build --profile development --platform android
```

Open the resulting development build, not Expo Go.

## Add the provider

```tsx theme={null}
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.

These controls affect only the current project selected in the Lucent app
header.

When you configure a Required URL such as `/onboarding`, emit path-style screen
evidence from your Expo app:

```tsx theme={null}
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](/sdk/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.

```json theme={null}
{
  "expo": {
    "plugins": [["@lucenthq/react-native/expo", { "skipOnConflict": true }]]
  }
}
```

Set these variables in EAS or your native build environment:

```bash theme={null}
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:

```js theme={null}
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:

   ```tsx theme={null}
   import { useLucent } from "@lucenthq/react-native";

   const lucent = useLucent();

   await lucent.track("expo_replay_test", {
     source: "development-build",
   });
   ```

4. Open [app.lucenthq.com](https://app.lucenthq.com) -> **Sessions**.

5. Confirm the session shows mobile screenshot replay.

## Troubleshooting

<AccordionGroup>
  <Accordion title="I only see Expo Go fallback">
    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.
  </Accordion>

  <Accordion title="No sessions appear after installing">
    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`.
  </Accordion>

  <Accordion title="Native module not linked">
    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.
  </Accordion>

  <Accordion title="The config plugin changed native files">
    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.
  </Accordion>

  <Accordion title="track() works, but replay is missing">
    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.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="React Native SDK" icon="mobile" href="/sdk/react-native">
    Install, configure, and use the complete mobile SDK API.
  </Card>

  <Card title="Browser SDK" icon="code" href="/sdk/installation">
    Use `@lucenthq/sdk` for web apps and rrweb-based browser replay.
  </Card>
</CardGroup>