Nuxt Matomo Tag Manager (MTM)

Nuxt module for integrating Matomo Tag Manager into your Nuxt 3+ application.

• ✨  Release Notes

Features

• Injects the Matomo Tag Manager container script with SSR support
• Initializes the window._mtm data layer automatically
• Automatic SPA page view tracking on route changes
• useMtm() composable and $mtm instance for manual event tracking
• Debug mode support
• Fully typed with TypeScript

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxt module add @remindgmbh/nuxt-typo3-mtm

Or install manually:

npm install @remindgmbh/nuxt-typo3-mtm

Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@remindgmbh/nuxt-typo3-mtm'],
  mtm: {
    matomoUrl: 'https://analytics.example.com',
    containerId: 'aBcDeFg1',
  },
})

That's it! You can now use Matomo Tag Manager in your Nuxt app.

Configuration

| Option | Type | Default | Description | |---|---|---|---| | matomoUrl | string | '' | Required. Your Matomo server URL (e.g. https://analytics.example.com) | | containerId | string | '' | Required. MTM container ID (e.g. aBcDeFg1) | | enabled | boolean | true | Enable or disable the module entirely | | debug | boolean | false | Enable Matomo Tag Manager debug mode | | loadScript | boolean | true | Whether to inject the container script into the page | | trackPageView | boolean | true | Automatically track page views on SPA route changes |

Environment Variables

You can also configure the module via runtimeConfig in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@remindgmbh/nuxt-typo3-mtm'],
  mtm: {
    matomoUrl: process.env.NUXT_PUBLIC_MTM_MATOMO_URL,
    containerId: process.env.NUXT_PUBLIC_MTM_CONTAINER_ID,
  },
})

Usage

Automatic Tracking

With trackPageView: true (default), page views are automatically tracked on every SPA route change. The initial page load is handled by the MTM container itself.

Manual Tracking

Use the useMtm() composable anywhere in your app:

<script setup>
const mtm = useMtm()

function trackCustomEvent() {
  mtm.push({
    event: 'customEvent',
    category: 'button',
    action: 'click',
    label: 'signup',
  })
}

function trackPageView() {
  mtm.trackPageView()
}
</script>

Using $mtm in Options API

export default defineComponent({
  methods: {
    trackEvent() {
      this.$mtm.push({ event: 'myEvent', value: 42 })
    },
  },
})

Disabling Script Injection

If you want to manage the MTM container script yourself (e.g. via consent management), set loadScript: false and manually push events:

export default defineNuxtConfig({
  modules: ['@remindgmbh/nuxt-typo3-mtm'],
  mtm: {
    matomoUrl: 'https://analytics.example.com',
    containerId: 'aBcDeFg1',
    loadScript: false,
  },
})

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