Skip to main content

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.

The React entry point exposes three things: a provider that manages tracker lifecycle, a renderless identify component that syncs user identity, and a hook that returns the underlying tracker. 
import { LucentProvider, LucentIdentify, useLucent } from "@lucenthq/sdk/react";

​
LucentProvider

Wraps your app, creates a single LucentTracker instance, and manages start/stop across the component lifetime. 
<LucentProvider publicKey="luc_pk_..." options={{ environment: "production" }}>
  {children}
</LucentProvider>

​
Props

​
publicKey
string
required
Your Lucent publishable key (luc_pk_...). Safe to expose in client‑side code — it can only write session data to your org and cannot read anything.
​
options
Omit<LucentInitOptions, 'publicKey'>
Any option accepted by LucentTracker except publicKey. See the Configuration page for the full list.
​
children
ReactNode
required
Your application tree.

​
Lifecycle

The provider creates the tracker lazily on first render. On mount it calls tracker.start() (unless options.autoStart === false). On unmount it calls tracker.stop(), which flushes any buffered events.
Do not remount LucentProvider on every render or route change — it should sit at the root of your app. Remounting will reset the recording session and cause gaps in your data.

​
LucentIdentify

A renderless component that calls tracker.identify(...) whenever its props change, and tracker.resetIdentity() when userId becomes null. Use it to sync your auth state with Lucent declaratively. 
<LucentProvider publicKey="luc_pk_...">
  <LucentIdentify
    userId={user?.id}
    email={user?.email}
    name={user?.name}
    properties={{
      plan: user?.plan,
      featureFlags: {
        "new-checkout-flow": flags.newCheckoutFlow,
      },
    }}
  />
  {children}
</LucentProvider>

​
Props

​
userId
string | null
Your internal user ID. When this transitions from a value to null, Lucent resets the identity and generates a new anonymous ID.
​
email
string | null
Optional email address. Shown in the dashboard to help you find sessions.
​
name
string | null
Optional display name.
​
properties
Record<string, unknown>
Arbitrary key/value pairs attached to the user. Useful for plan tier, signup date, feature flags, etc.

​
Feature flags for Signals

If your app records sessions with Lucent SDK and uses a separate feature flag provider, pass the evaluated flag values through properties.featureFlags. Signals can filter SDK sessions by these observed values. 
<LucentIdentify
  userId={user?.id}
  email={user?.email}
  properties={{
    featureFlags: {
      "new-checkout-flow": launchDarkly.variation("new-checkout-flow"),
      "pricing-page-redesign": statsig.checkGate("pricing-page-redesign"),
      "paywall-test": growthbook.getFeatureValue("paywall-test", "control"),
    },
  }}
/>
Use the same flag key when creating a Signal filter. If a flag value changes during the session, update the properties object so LucentIdentify calls identify again.

​
useLucent

Returns the tracker instance from the nearest LucentProvider, or null if called outside a provider. Use this when you want to track custom events or manually flush. 
import { useLucent } from "@lucenthq/sdk/react";

export function CheckoutButton() {
  const lucent = useLucent();

  return (
    <button
      onClick={() => {
        lucent?.track("checkout_clicked", { plan: "pro" });
      }}
    >
      Upgrade
    </button>
  );
}
useLucent returns null during SSR and on the first render if the provider hasn’t mounted yet. Always guard with lucent?. or a conditional before calling methods.
For install steps, see Next.js or React.