nuxt-meta-pixel

I needed a Facebook pixel integration for a large project, but what I found didn't meet my expectations. That's why I took the time to understand how a pixel works and developed a unique integration that's as simple as it should be, and much more effective than any other integration.

Features

• ✨  Written in TypeScript, even the Facebook's events are typed.
• 🤖  You can load as much meta pixels as you want.
• 📨  PageView event are sent automatically based on configurable route match.
• ⚙️  Configurable via a .env file.
• 🚀  All the possibilities offered by Facebook are available: track, trackSingle, trackCustom & trackSingleCustom.
• ❤️  Contributions are welcome.

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add nuxt-meta-pixel

That's it! You can now use nuxt-meta-pixel in your Nuxt app ✨

Getting started

Module configuration

The module can also be configured under the key metapixel.

// nuxt.config.ts
// This example show how to load multiple pixels

export default defineNuxtConfig({
  modules: ['nuxt-meta-pixel'],
  runtimeConfig: {
    public: {
      metapixel: {
        default: { id: '1176370652884847', pageView: '/posts/**' },
        ads01: { id: '415215247513663' },
        ads02: { id: '415215247513664', pageView: '!/posts/**' },
      }
    }
  }
})

Pixel options

• id string - your pixel id
• autoconfig boolean (default: true) - enable or disable pixel autoconfig. see more
• pageView string (default: **) - glob expression to decide which route or not should send a PageView event automatically. see more
• consent 'revoke' - opt into GDPR consent gating. Set revoke to hold event delivery until the user opts in (see GDPR consent). When omitted, the pixel behaves normally. see more

GDPR consent

Meta's consent is a global setting — the command takes no pixel id, so it applies to every pixel at once. Concretely:

• Setting consent: 'revoke' on any pixel revokes all pixels (the most restrictive value wins). You can't keep one pixel live while another is revoked.
• consent in the config only meaningfully accepts 'revoke' (opting into gating). Granting is done at runtime — tracking is allowed by default, so a config 'grant' would be a no-op.

To stay GDPR compliant, set consent: 'revoke' so the module revokes before initialization — nothing is sent to Meta until you grant consent:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-meta-pixel'],
  runtimeConfig: {
    public: {
      metapixel: {
        default: { id: '1176370652884847', consent: 'revoke' },
      }
    }
  }
})

Then grant (or re-revoke) consent at runtime once your cookie banner is answered, via the injected $fbq:

<script setup lang="ts">
const { $fbq } = useNuxtApp()

function onCookieBannerAccepted() {
  $fbq('consent', 'grant')
}

function onCookieBannerRejected() {
  $fbq('consent', 'revoke')
}
</script>

Note: on a classic multi-page (non-SPA) site Meta requires calling revoke on every page load — the module handles this by revoking on plugin init. see more

Environment variables

// .env
// This example show how to define pixel ids via your environment variables
NUXT_PUBLIC_METAPIXEL_DEFAULT_ID=ID1
NUXT_PUBLIC_METAPIXEL_ADS01_ID=ID2
NUXT_PUBLIC_METAPIXEL_ADS02_ID=ID3

The variable you are trying to update via an environment variable must be defined in your nuxt.config.ts. Replace DEFAULT, ADS01 or ADS02 by the names you defined.

Advanced usage

// app.vue
// This example show how to use fbq in your pages

<script setup lang="ts">
const { $fbq } = useNuxtApp()

onMounted(() => {
  $fbq('track', 'CompleteRegistration')
  $fbq('trackSingle', YOUR_PIXEL_ID, 'CompleteRegistration')
})
</script>

<template>
  <div>nuxt-meta-pixel</div>
</template>

Useful resources

• Conversion Tracking
• Events
• Accurate Event Tracking with Multiple Pixels
• GDPR consent

Contribution

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release