@flusterduck/next
v0.5.2
Published
Flusterduck Next.js integration
Readme
@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/nextScript 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(): voidAll Config options from the core flusterduck package are supported.