{"id":19568299,"url":"https://github.com/stackbuilders/nuxt-utm","last_synced_at":"2026-03-07T08:03:18.970Z","repository":{"id":239772151,"uuid":"706785513","full_name":"stackbuilders/nuxt-utm","owner":"stackbuilders","description":"Nuxt 3/4 module for capturing and tracking UTM parameters from URLs, with additional contextual data collection.","archived":false,"fork":false,"pushed_at":"2026-02-20T21:39:22.000Z","size":1320,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":14,"default_branch":"main","last_synced_at":"2026-02-21T02:56:50.065Z","etag":null,"topics":["nuxt","nuxt-module","nuxt-modules","nuxt3","utm","utm-parameters"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stackbuilders.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-10-18T15:59:15.000Z","updated_at":"2026-02-20T21:34:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"9f5355be-9a89-4706-b21a-d7484e8f8456","html_url":"https://github.com/stackbuilders/nuxt-utm","commit_stats":null,"previous_names":["stackbuilders/nuxt-utm"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/stackbuilders/nuxt-utm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackbuilders%2Fnuxt-utm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackbuilders%2Fnuxt-utm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackbuilders%2Fnuxt-utm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackbuilders%2Fnuxt-utm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackbuilders","download_url":"https://codeload.github.com/stackbuilders/nuxt-utm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackbuilders%2Fnuxt-utm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30209797,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T05:23:27.321Z","status":"ssl_error","status_checked_at":"2026-03-07T05:00:17.256Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nuxt","nuxt-module","nuxt-modules","nuxt3","utm","utm-parameters"],"created_at":"2024-11-11T06:03:24.519Z","updated_at":"2026-03-07T08:03:18.941Z","avatar_url":"https://github.com/stackbuilders.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nuxt UTM\n\n[![CI](https://github.com/stackbuilders/nuxt-utm/actions/workflows/main.yml/badge.svg)](https://github.com/stackbuilders/nuxt-utm/actions/workflows/main.yml)\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n[![License][license-src]][license-href]\n[![Nuxt][nuxt-src]][nuxt-href]\n\n**Built in collaboration with The Durst Organization**\n\n---\n\nA Nuxt 3/4 module for tracking UTM parameters.\n\n- [✨ \u0026nbsp;Release Notes](/CHANGELOG.md)\n  \u003c!-- - [🏀 Online playground](https://stackblitz.com/github/stackbuilders/nuxt-utm?file=playground%2Fapp.vue) --\u003e\n  \u003c!-- - [📖 \u0026nbsp;Documentation](https://example.com) --\u003e\n\n## How it works / motivation / purpose\n\nIf a visitor arrives at a website that uses the Nuxt UTM module and a UTM parameter is present in the URL, the module will collect the UTM parameters along with additional information. This information is saved in the device's local storage within the user's browser. This is especially useful for static generated websites that can later integrate with the backend to save this data. For example, when a visitor or lead submits a form, you can send this data alongside the form data. Later, this information can be especially useful for evaluating the effectiveness of ad campaigns and assessing their impact.\n\n## Features\n\n- **📍 UTM Tracking**: Easily capture UTM parameters to gain insights into traffic sources and campaign performance.\n- **🔍 Intelligent De-duplication**: Smart recognition of page refreshes to avoid data duplication, ensuring each visit is uniquely accounted for.\n- **🔗 Comprehensive Data Collection**: Alongside UTM parameters, gather additional context such as referrer details, user agent, landing page url, browser language, and screen resolution. This enriched data empowers your marketing strategies with a deeper understanding of campaign impact.\n\n## Quick Setup\n\n1. Add `nuxt-utm` dependency to your project\n\n```bash\n# Using pnpm\npnpm add -D nuxt-utm\n\n# Using yarn\nyarn add --dev nuxt-utm\n\n# Using npm\nnpm install --save-dev nuxt-utm\n```\n\n2. Add `nuxt-utm` to the `modules` section of `nuxt.config.ts`\n\n```js\nexport default defineNuxtConfig({\n  modules: ['nuxt-utm'],\n})\n```\n\nThat's it! You can now use Nuxt UTM in your Nuxt app ✨\n\n## Usage\n\n### Configuration\n\nYou can configure the module by passing options in your `nuxt.config.ts`:\n\n```js\nexport default defineNuxtConfig({\n  modules: ['nuxt-utm'],\n  utm: {\n    trackingEnabled: true, // defaults to true - initial tracking state\n  },\n})\n```\n\n#### Options\n\n- `trackingEnabled`: Boolean (default: `true`) - Sets the initial state for UTM tracking. This can be changed at runtime.\n\n### Runtime Tracking Control\n\nThe module provides runtime control over tracking, perfect for implementing cookie consent banners or user privacy preferences.\n\n#### Using the Composable\n\n```vue\n\u003cscript setup\u003e\nconst utm = useNuxtUTM()\n\n// The composable returns:\n// - data: Reactive array of collected UTM data\n// - trackingEnabled: Reactive boolean indicating if tracking is active\n// - enableTracking(): Enable UTM tracking\n// - disableTracking(): Disable UTM tracking\n// - clearData(): Clear all stored UTM data\n\u003c/script\u003e\n```\n\n#### Example: Cookie Banner Integration\n\n```vue\n\u003ctemplate\u003e\n  \u003cdiv v-if=\"showBanner\" class=\"cookie-banner\"\u003e\n    \u003cp\u003eWe use tracking to improve your experience.\u003c/p\u003e\n    \u003cbutton @click=\"acceptTracking\"\u003eAccept\u003c/button\u003e\n    \u003cbutton @click=\"rejectTracking\"\u003eReject\u003c/button\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\nimport { ref } from 'vue'\nconst utm = useNuxtUTM()\nconst showBanner = ref(!utm.trackingEnabled.value)\n\nconst acceptTracking = () =\u003e {\n  utm.enableTracking()\n  showBanner.value = false\n}\n\nconst rejectTracking = () =\u003e {\n  utm.disableTracking()\n  utm.clearData() // Optional: clear any existing data\n  showBanner.value = false\n}\n\u003c/script\u003e\n```\n\n#### Privacy Controls\n\n```vue\n\u003ctemplate\u003e\n  \u003cdiv class=\"privacy-settings\"\u003e\n    \u003ch3\u003ePrivacy Settings\u003c/h3\u003e\n    \u003clabel\u003e\n      \u003cinput \n        type=\"checkbox\" \n        :checked=\"utm.trackingEnabled.value\"\n        @change=\"toggleTracking\"\n      /\u003e\n      Enable UTM tracking\n    \u003c/label\u003e\n    \u003cbutton @click=\"utm.clearData\" v-if=\"utm.data.value.length \u003e 0\"\u003e\n      Clear tracking data ({{ utm.data.value.length }} entries)\n    \u003c/button\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\nconst utm = useNuxtUTM()\n\nconst toggleTracking = (event) =\u003e {\n  if (event.target.checked) {\n    utm.enableTracking()\n  } else {\n    utm.disableTracking()\n  }\n}\n\u003c/script\u003e\n```\n\n### Accessing UTM Data\n\nYou can use `useNuxtUTM` composable to access the UTM data:\n\n```vue\n\u003cscript setup\u003e\nconst utm = useNuxtUTM()\n\n// Access the collected data\nconsole.log(utm.data.value)\n\u003c/script\u003e\n```\n\n\u003e Remember: You don't need to import the composable because Nuxt imports it automatically.\n\n### Data Structure\n\nThe `data` property contains an array of UTM parameters collected. Each element in the array represents a set of UTM parameters collected from a URL visit, and is structured as follows\n\n```json\n[\n  {\n    \"timestamp\": \"2023-11-02T10:11:17.219Z\",\n    \"utmParams\": {\n      \"utm_source\": \"test_source\",\n      \"utm_medium\": \"test_medium\",\n      \"utm_campaign\": \"test_campaign\",\n      \"utm_term\": \"test_term\",\n      \"utm_content\": \"test_content\"\n    },\n    \"additionalInfo\": {\n      \"referrer\": \"http://referrer.url\",\n      \"userAgent\": \"User-Agent String\",\n      \"language\": \"en-GB\",\n      \"landingPageUrl\": \"http://landingpage.url\",\n      \"screen\": {\n        \"width\": 1728,\n        \"height\": 1117\n      }\n    },\n    \"sessionId\": \"beai1gx7dg\",\n    \"gclidParams\": {\n      \"gclid\": \"CjklsefawEFRfeafads\",\n      \"gad_source\": \"1\"\n    }\n  }\n]\n```\n\nEach entry provides a `timestamp` indicating when the UTM parameters were collected, the `utmParams` object containing the UTM parameters, `additionalInfo` object with more context about the visit, and a `sessionId` to differentiate visits in different sessions.\n\n### Key Features\n\n- **Runtime Control**: Enable/disable tracking dynamically based on user consent\n- **Privacy Friendly**: Respects user preferences and provides clear data management\n- **Persistent Preferences**: Tracking preferences are saved and persist across sessions\n- **Data Clearing**: Ability to completely remove all collected data\n- **Session Management**: Automatically manages sessions to avoid duplicate tracking\n\n## Development\n\n```bash\n# Install dependencies\nyarn install\n\n# Generate type stubs\nyarn dev:prepare\n\n# Develop with the playground\nyarn dev\n\n# Build the playground\nyarn dev:build\n\n# Run ESLint\nyarn lint\n\n# Install Playwright Browsers\nnpx playwright install --with-deps\n\n# Run Vitest\nyarn test\nyarn test:watch\n\n# Release new version\nyarn release\n```\n\nFor detailed information about the release process, please refer to our [Release Documentation](/docs/RELEASING.md).\n\n## License\n\n\u003c!-- NOTE: If you need a different type of licence, please check with the OSS team before changing it --\u003e\n\nMIT, see [the LICENSE file](LICENSE).\n\n## Contributing\n\nDo you want to contribute to this project? Please take a look at our [contributing guideline](/docs/CONTRIBUTING.md) to know how you can help us build it.\n\n\u003c!-- Badges --\u003e\n\n[npm-version-src]: https://img.shields.io/npm/v/nuxt-utm/latest.svg?style=flat\u0026colorA=18181B\u0026colorB=28CF8D\n[npm-version-href]: https://npmjs.com/package/nuxt-utm\n[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-utm.svg?style=flat\u0026colorA=18181B\u0026colorB=28CF8D\n[npm-downloads-href]: https://npmjs.com/package/nuxt-utm\n[license-src]: https://img.shields.io/npm/l/nuxt-utm.svg?style=flat\u0026colorA=18181B\u0026colorB=28CF8D\n[license-href]: https://npmjs.com/package/nuxt-utm\n[nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js\n[nuxt-href]: https://nuxt.com\n\n---\n\n\u003cimg src=\"https://www.stackbuilders.com/media/images/Sb-supports.original.png\" alt=\"Stack Builders\" width=\"50%\"\u003e\u003c/img\u003e\n[Check out our libraries](https://github.com/stackbuilders/) | [Join our team](https://www.stackbuilders.com/join-us/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackbuilders%2Fnuxt-utm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackbuilders%2Fnuxt-utm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackbuilders%2Fnuxt-utm/lists"}