@flusterduck/nuxt

Nuxt integration for Flusterduck. Provides a plugin factory for app-level initialization and standalone tracking functions for use in components and composables.

Installation

npm install flusterduck @flusterduck/nuxt

Setup

Create a Nuxt plugin that initializes Flusterduck on the client side. createFlusterduckPlugin returns a plugin function, so export it directly:

// plugins/flusterduck.client.ts
import { createFlusterduckPlugin } from '@flusterduck/nuxt';

export default createFlusterduckPlugin({
  key: 'fd_pub_...',
  environment: process.env.NODE_ENV,
});

The .client.ts suffix ensures this plugin only runs in the browser. The plugin also guards against SSR on its own, so a missing suffix degrades to a no-op rather than an error.

Initialization goes through the npm SDK only. Don't add the d.js script tag alongside this plugin; the two hold separate state and would double-track every visitor.

Configuration helper

Use defineFlusterduckConfig to build a typed config object for reuse. It only passes through key, environment, sampleRate, debug, cookieless, respectDoNotTrack, and segment; any other Config field you pass in is dropped. Set those directly on the object you pass to createFlusterduckPlugin instead.

// flusterduck.config.ts
import { defineFlusterduckConfig } from '@flusterduck/nuxt';

export default defineFlusterduckConfig({
  key: 'fd_pub_...',
  environment: 'production',
  sampleRate: 1,
  cookieless: false,
});

Tracking in components

<script setup lang="ts">
import { signal, track, identify } from '@flusterduck/nuxt';

function onPayClick() {
  signal('checkout_error', { element: '#pay-btn' });
}

function onPlanSelect(plan: string) {
  track('plan_selected', { plan });
  identify({ plan });
}
</script>

Consent

import { setConsent, optOut } from '@flusterduck/nuxt';

setConsent(true);
optOut();

API

defineFlusterduckConfig(options: NuxtFlusterduckOptions): Pick<NuxtFlusterduckOptions, 'key' | 'environment' | 'sampleRate' | 'debug' | 'cookieless' | 'respectDoNotTrack' | 'segment'>
createFlusterduckPlugin(options: NuxtFlusterduckOptions): () => Promise<void>
signal(name: string, data?: { element?: string; metadata?: Record<string, unknown>; weight?: number }): 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 by createFlusterduckPlugin (see the caveat above for defineFlusterduckConfig).

signal, track, and identify are also exported as trackSignal, trackBusinessEvent, and identifySegment for naming parity with the other framework packages' hook return values.