@lupinum/nuxt-utils

Reusable Nuxt module for analytics, consent management, chat, and form infrastructure. Built to be shared across multiple site templates.

What it owns

• Consent state — cookie persistence for bannerless and categories modes
• Analytics dispatch — Umami and Plausible, loaded after page is ready
• Marketing trackers — Google Ads (consent-aware) and Meta Pixel (consent-gated)
• Semantic event tracking — named events routed to providers via a config map
• Chat — Brevo widget with manual-optin or functional-consent gating
• Basin forms — submission state, error handling, FormData serialization
• Headless UI primitives — SiteModalShell, SiteConsentCategories, SiteLegalLinks

Each site owns its own cookie banner UI and event map. This module owns the infrastructure underneath.

Setup

Published on npm as a public scoped package: @lupinum/nuxt-utils.

# Install
pnpm add @lupinum/nuxt-utils @nuxt/scripts

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/scripts',        // required peer — loads tracking scripts
    '@lupinum/nuxt-utils',
  ],

  lupinum: {
    consent: {
      mode: 'categories',   // 'bannerless' (default) or 'categories'
      legalLinks: {
        privacyPolicy: '/datenschutz',
        imprint: '/impressum',
      },
    },
    analytics: {
      provider: 'umami',
      umami: { websiteId: 'your-website-id' },
    },
    events: {
      contact_submitted: {
        umami: 'Contact Form Submitted',
      },
    },
    chat: false,            // or { provider: 'brevo', conversationsId: '...' }
  },
})

Local development (link: protocol)

When developing the module alongside a consuming project, link it via pnpm's link: protocol:

// consuming-project/package.json
{
  "dependencies": {
    "@lupinum/nuxt-utils": "link:../../0_libs/@lupinum-nuxt-utils"
  }
}

Then in the module repo, run npm run dev:prepare once to generate stubs. Changes to src/ are immediately reflected in the consuming project without rebuilding.

Config key: lupinum

lupinum: {
  // --- Analytics ---
  analytics?: {
    enabled?: boolean           // default: true in production, false in dev
    provider?: 'umami' | 'plausible'
    queue?: boolean             // queue events until script loads (default: true)
    umami?: {
      websiteId: string
      scriptSrc?: string        // default: https://cloud.umami.is/script.js
    }
    plausible?: {
      domain: string
      scriptSrc?: string        // default: https://plausible.io/js/script.js
    }
    mirror?: Array<            // send to multiple providers simultaneously
      | { provider: 'umami'; websiteId: string; scriptSrc?: string }
      | { provider: 'plausible'; domain: string; scriptSrc?: string }
    >
  }

  // --- Marketing trackers (require marketing consent) ---
  marketing?: {
    googleAds?: {
      tagId: string
      consentMode?: 'advanced'  // enables Google Consent Mode v2
    }
    metaPixel?: {
      pixelId: string
    }
  }

  // --- Semantic event map ---
  // Keys are internal event names passed to track(). Values map to provider-specific events.
  // String shorthand: 'Event Name' — object form for params/props.
  // Use false to disable a destination for a specific event.
  events?: {
    [eventKey: string]: {
      umami?: string | { name?: string; props?: Record<string, unknown> | 'passthrough' }
      plausible?: string | { name?: string; props?: Record<string, unknown> | 'passthrough' }
      googleAds?: string | { command?: string; name?: string; params?: Record<string, unknown> }
      metaPixel?: string | { command?: string; name?: string; params?: Record<string, unknown> }
    }
  }

  // --- Consent ---
  consent?: {
    mode?: 'bannerless' | 'categories'   // default: 'bannerless'
    cookieNames?: {
      decision?: string         // default: 'site-consent'
      categories?: string       // default: 'site-consent-categories'
      chatPermission?: string   // default: 'site-chat-permission'
    }
    maxAge?: number             // cookie lifetime in seconds (default: 365 days)
    defaultCategories?: {
      functional?: boolean      // default: false
      marketing?: boolean       // default: false
    }
    legalLinks?: {
      privacyPolicy?: string    // default: '/datenschutz'
      imprint?: string          // default: '/impressum'
    }
  }

  // --- Chat ---
  chat?: false | {
    provider?: 'brevo'
    conversationsId: string     // required
    gating?: 'manual-optin' | 'functional-consent'  // default: 'manual-optin'
    scriptUrl?: string          // default: Brevo CDN
    hiddenRoutePrefixes?: string[]   // hide the chat widget on these routes
  }
}

Composables

useSiteConsent()

Core consent state. All cookie banner UI components should source their state here — never manage consent cookies directly.

const {
  mode,               // 'bannerless' | 'categories'
  categories,         // ComputedRef<{ essential: true, functional: bool, marketing: bool }>
  hasUserDecided,     // ComputedRef<boolean> — false until user interacts with the banner
  showBanner,         // ComputedRef<boolean> — true when mode='categories' and !hasUserDecided
  functionalConsent,  // ComputedRef<boolean> — shorthand for categories.functional
  marketingConsent,   // ComputedRef<boolean> — shorthand for categories.marketing
  legalLinks,         // { privacyPolicy?: string, imprint?: string }
  acceptAll,          // () => void — grant all categories
  rejectAll,          // () => void — reject optional categories
  saveSettings,       // (partial: Partial<Categories>) => void — save custom choices
  reset,              // () => void — clear decision cookie, re-show banner
} = useSiteConsent()

Consent categories:

• essential — always true, cannot be opted out
• functional — enhanced features (e.g. Brevo chat with functional-consent gating)
• marketing — ad trackers (Meta Pixel, Google Ads) and third-party embeds (YouTube)

Consent modes:

• bannerless — implicit consent, no banner shown. All categories treated as granted for display purposes.
• categories — explicit opt-in required. Banner shown until hasUserDecided is true.

useSiteTracking()

Routes semantic event names to configured analytics and marketing providers.

const { track } = useSiteTracking()

// eventKey must match a key in lupinum.events config
track('contact_submitted')
track('plan_upgraded', { plan: 'pro', userId: '123' })

Event mapping:

// nuxt.config — lupinum.events
events: {
  contact_submitted: {
    umami: 'Contact Form Submitted',
    plausible: 'Contact Form Submitted',
    googleAds: { name: 'conversion', params: { send_to: 'AW-.../...' } },
    metaPixel: { command: 'track', name: 'Lead' },
  },
  // Dynamic values from payload — use {payload.fieldName} syntax:
  plan_upgraded: {
    umami: { name: 'Plan Upgraded', props: { plan: '{payload.plan}' } },
  },
}

Queue behavior: If a provider script hasn't finished loading, events are queued and retried every 300ms. Events are dropped after 100 items in the queue. Meta Pixel events are silently dropped if marketingConsent is false.

useSiteConsent() + useSiteTracking() together

Analytics scripts (Umami/Plausible) load unconditionally when analytics.enabled is true — they're privacy-respecting and don't require consent. Marketing scripts (Meta Pixel) only load after marketingConsent is granted.

useBasinForm(endpoint, options?)

Manages form submission state for Basin endpoints.

const { isSubmitting, isSubmitted, errorMessage, submit, reset } = useBasinForm(
  'https://usebasin.com/f/your-form-id',
  {
    // Optional: resolve a human-readable error from the response
    getErrorMessage: ({ response, responseData, error }) => {
      if (responseData?.message) return responseData.message
    },
  },
)

// In your template handler:
async function handleSubmit(formData: FormData) {
  const ok = await submit(formData)  // also accepts plain objects
  if (!ok) {
    console.error(errorMessage.value)
  }
}

// Reset after navigating away or showing a new form
reset(() => {
  // optional side-effect, e.g. clear form fields
  name.value = ''
})

Payload types: FormData (passed through), plain objects (serialized to FormData — supports arrays and File/Blob values).

useSiteChat()

Controls the Brevo chat widget with consent gating.

const {
  isEnabled,              // ComputedRef<boolean> — false if chat: false in config
  status,                 // Ref<'idle' | 'loading' | 'loaded' | 'error'>
  isLoaded,               // ComputedRef<boolean>
  showPermissionModal,    // Ref<boolean> — set to true when user clicks a chat trigger
  shouldShowFloatingButton, // ComputedRef<boolean> — show custom open button?
  hasManualPermission,    // ComputedRef<boolean> — manual-optin permission cookie granted?
  requestOpen,            // () => void — open chat (or show permission modal if needed)
  approvePermission,      // () => void — grant permission + open chat
  denyPermission,         // () => void — dismiss the permission modal
  openChat,               // () => void — open Brevo widget directly
  hideChat,               // () => void — visually hide widget (still loaded)
  showChat,               // () => void — restore hidden widget
  clearChat,              // () => void — remove widget DOM + localStorage, reset status
} = useSiteChat()

Gating modes:

• manual-optin (default) — user must explicitly click "Allow chat" before the script loads. Permission stored in a cookie (site-chat-permission). Typical use: a floating "Chat with us" button that shows a permission dialog.
• functional-consent — chat loads automatically when functionalConsent is true. Use when the cookie banner already covers chat as part of "Functional Cookies".

Minimal chat button example:

<script setup>
const { requestOpen, showPermissionModal, approvePermission, denyPermission } = useSiteChat()
</script>

<template>
  <button @click="requestOpen">Chat with us</button>

  <!-- Your permission modal -->
  <SiteModalShell :open="showPermissionModal" @close="denyPermission">
    <p>This will load Brevo chat (a third-party service).</p>
    <button @click="approvePermission">Allow</button>
    <button @click="denyPermission">No thanks</button>
  </SiteModalShell>
</template>

Headless UI components

These components are styling-free primitives. Use them inside your own cookie banner or consent modal.

SiteModalShell

Dialog/modal container with backdrop, accessible close handling, and slot-based content.

<SiteModalShell
  :open="showBanner"
  @close="rejectAll"
  :close-on-backdrop="false"
  panel-class="max-w-lg"
>
  <!-- Banner content -->
</SiteModalShell>

SiteConsentCategories

Three toggle rows (Essential disabled, Functional, Marketing) bound via v-model.

<SiteConsentCategories
  v-model="{ functional: categories.functional, marketing: categories.marketing }"
  :copy="{
    essentialLabel: 'Required',
    functionalLabel: 'Functional',
    marketingLabel: 'Marketing',
  }"
/>

SiteLegalLinks

Privacy policy and imprint links.

<SiteLegalLinks
  :privacy-policy="legalLinks.privacyPolicy"
  :imprint="legalLinks.imprint"
/>

Consent-gated third-party embeds

For embeds like YouTube that set third-party cookies, check marketingConsent before rendering the iframe. The template includes a VideoEmbed.vue reference component that:

1. Shows a local thumbnail with a play button
2. On click, loads the YouTube iframe (using the privacy-enhanced youtube-nocookie.com domain)
3. If marketing consent is not yet granted, shows a secondary "Load & allow YouTube cookies" button that calls saveSettings({ marketing: true }) before loading

<VideoEmbed
  src="dQw4w9WgXcQ"
  thumbnail="/images/video-thumb.jpg"
  title="Product demo"
/>

Development

# Start playground with live reload (stubs src/ into playground)
npm run dev

# Run unit + fixture tests
npm run test

# Run type checks
npm run test:types

# Build publishable dist/
npm run prepack

# Verify cold-start npm pack/publish flow
npm run release:verify

Stub mode (npm run dev:prepare) creates dist/ stubs that redirect imports to src/ at runtime. This allows a consuming project linked via link: to pick up source changes immediately without rebuilding the module.