@nexly/react-web

React bindings for @nexly/core.

Install

npm install @nexly/react-web react

@nexly/core is installed automatically as a dependency of @nexly/react-web.

Usage

import { NexlyProvider, useNexlyClient } from '@nexly/react-web'

function Root() {
  return (
    <NexlyProvider
      appId={appId}
      ingestKey={apiToken}
      autoPageView
      autoEngagement
    >
      <App />
    </NexlyProvider>
  )
}

function App() {
  const client = useNexlyClient()
  if (!client) return <p>Add credentials</p>
  return (
    <button type="button" onClick={() => client.customEvent('cta_clicked', { placement: 'hero' })}>
      Track
    </button>
  )
}

NexlyProvider props

• appId, ingestKey — required strings (ingestKey is the ingest API token; not named key because that is reserved in React).
• autoPageView (default false) — when a client exists, send one pageview on mount.
• autoEngagement (default false) — when true and a client exists (all three strings non-empty after trim), attach engagement listeners; otherwise no-op. Cleanup on unmount or when the client or flag changes. The underlying startEngagement() is idempotent, so double-mounts (StrictMode, HMR) don't produce duplicate listeners.

Opting elements out of auto-capture

Mark any element with data-nexly-ignore to skip auto-click and auto-input_focus events for it (and its descendants). Use it on elements where you already emit your own event(...) to avoid semantic duplicates:

<button data-nexly-ignore onClick={() => client?.customEvent('signup_clicked')}>
  Sign up
</button>

useNexlyClient()

Returns Nexly | null inside a provider (null if any credential trims to empty).

Using outside React (plain functions)

The provider initializes a global singleton. Access it anywhere without hooks:

import { Nexly } from '@nexly/react-web'

Nexly.getInstance()?.customEvent('cta_click', { placement: 'hero' })

Next.js

For Next.js App Router (route-aware autoPageView on every navigation), use @nexly/next instead.

License

MIT — see LICENSE.