npm.io
0.5.4 • Published 11h ago

@flusterduck/next

Licence
SEE LICENSE IN LICENSE.md
Version
0.5.4
Deps
0
Size
16 kB
Vulns
0
Weekly
18
SummaryDependencyVersions

@flusterduck/next

Next.js integration for Flusterduck. Includes a FlusterduckScript component for script-tag based loading and a useFlusterduck hook for SDK-based initialization with SSR safety built in.

Installation

npm install flusterduck @flusterduck/next

Script component (recommended)

Add FlusterduckScript to your root layout. It renders a next/script tag with strategy="afterInteractive" and passes config via data-* attributes.

// app/layout.tsx
import { FlusterduckScript } from '@flusterduck/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <FlusterduckScript
          apiKey="fd_pub_..."
          environment="production"
        />
      </body>
    </html>
  );
}

Props:

Prop Type Description
apiKey string Publishable key (fd_pub_...)
environment string Tag events by environment
debug boolean Enable console debug output
cookieless boolean Use memory-only session IDs instead of cookies
sampleRate number Fraction of sessions to track (0-1)
segment Record<string, string> Segment all events from this load

Hook usage

For App Router client components or when you need programmatic control:

'use client';

import { useFlusterduck } from '@flusterduck/next';

export function CheckoutForm() {
  const { signal, track, setConsent, optOut } = useFlusterduck({
    key: 'fd_pub_...',
    environment: 'production',
  });

  return (
    <button onClick={() => signal('checkout_abandoned')}>
      Cancel
    </button>
  );
}

The hook is SSR-safe. It checks typeof window before initializing and never runs on the server.

Consent gating

'use client';

import { useFlusterduck } from '@flusterduck/next';

export function ConsentBanner() {
  const { setConsent } = useFlusterduck({
    key: 'fd_pub_...',
    enabled: false,
  });

  return (
    <button onClick={() => setConsent(true)}>Accept</button>
  );
}

API

signal(name: string, data?: { element?: string; metadata?: Record<string, unknown> }): void
track(name: string, metadata?: Record<string, unknown>): void
identify(segment: Record<string, string>): void
setConsent(consented: boolean): void
optOut(): void

All Config options from the core flusterduck package are supported.

Keywords

nextjsnextnext-jsnext-analyticsnext-trackingapp-routerpages-routerserver-componentsnext-scriptrage-clickdead-clickclick-trackingform-abandonmentscroll-trackingux-analyticsuser-behaviorbehavioral-analyticshotjar-nextjsfullstory-nextjsposthog-nextjssession-replay-alternativeheatmapvercelvercel-analyticsproduct-analyticsconversion-trackingfrustration-detectionfriction