@nexly/next
v0.16.2
Published
Next.js App Router helpers for Nexly: route-aware auto pageview on top of @nexly/react-web
Maintainers
m_brtnReadme
@nexly/next
Next.js App Router helpers for @nexly/react-web.
The base @nexly/react-web provider fires a pageview once on mount. In Next.js App Router, client navigations do not remount the root layout, so subsequent route changes are missed. @nexly/next adds a thin wrapper that listens to usePathname() and sends a pageview on every route change.
Install
npm install @nexly/next@nexly/react-web and @nexly/core are installed automatically as transitive dependencies.
Usage
// app/providers.tsx
'use client'
import { NexlyNextProvider } from '@nexly/next'
export function Providers({ children }: { children: React.ReactNode }) {
return (
<NexlyNextProvider
appId={process.env.NEXT_PUBLIC_NEXLY_APP_ID!}
ingestKey={process.env.NEXT_PUBLIC_NEXLY_INGEST_KEY!}
autoPageView
autoEngagement
>
{children}
</NexlyNextProvider>
)
}// app/layout.tsx
import { Providers } from './providers'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<Providers>{children}</Providers>
</body>
</html>
)
}Custom events
'use client'
import { useNexlyClient } from '@nexly/next'
export function SignUpButton() {
const client = useNexlyClient()
return (
<button onClick={() => client?.customEvent('sign_up_clicked', { source_section: 'hero' })}>
Sign up
</button>
)
}Props
NexlyNextProvider accepts the same props as NexlyProvider from @nexly/react-web:
appId,ingestKey— required credentials.autoPageView(defaultfalse) — send a pageview on mount and on every client-side route change.autoEngagement(defaultfalse) — attach scroll, click, visibility, and heartbeat listeners. The underlyingstartEngagement()is idempotent. Mark elements withdata-nexly-ignoreto exclude them (and their descendants) from auto-click/ auto-input_focuscapture.
Using outside React (plain functions)
The provider initializes a global singleton. Access it anywhere without hooks:
import { Nexly } from '@nexly/next'
Nexly.getInstance()?.customEvent('cta_click', { placement: 'hero' })Re-exports
useNexlyClient and Nexly are re-exported for convenience — no need to install the base packages separately.
License
MIT — see LICENSE.