diff --git a/README.md b/README.md index 049530f..98efdfc 100644 --- a/README.md +++ b/README.md @@ -53,13 +53,33 @@ That's it! You can now use Nuxt UTM in your Nuxt app ✨ ## Usage -You can use ```useNuxtUTM``` composable to access the UTM object: +### Configuration + +You can configure the module by passing options in your `nuxt.config.ts`: + +```js +export default defineNuxtConfig({ + modules: ["nuxt-utm"], + utm: { + enabled: true, // defaults to true + }, +}); +``` + +#### Options + +- `enabled`: Boolean (default: `true`) - Controls whether UTM tracking is active. When set to `false`, the module won't track any UTM parameters or add any functionality to your app. + +### Accessing UTM Data + +You can use `useNuxtUTM` composable to access the UTM object: ```vue ``` + > Remember: You don't need to import the composable because nuxt imports it automatically. Alternatively, you can get the UTM information through the Nuxt App with the following instructions: @@ -106,7 +126,7 @@ In the `$utm` array, each entry provides a `timestamp` indicating when the UTM p ### Devenv -You can take advantage of [devenv.sh](https://devenv.sh) to quickly create the development environment for this this project. Use it in combination with [direnv](https://direnv.net/) to quickly load all the environment while navigating into the project directory in your shell. +You can take advantage of [devenv.sh](https://devenv.sh) to quickly create the development environment for this this project. Use it in combination with [direnv](https://direnv.net/) to quickly load all the environment while navigating into the project directory in your shell. ```bash # Install dependencies diff --git a/playground/nuxt.config.ts b/playground/nuxt.config.ts index d725d31..101d727 100644 --- a/playground/nuxt.config.ts +++ b/playground/nuxt.config.ts @@ -1,5 +1,12 @@ export default defineNuxtConfig({ + app: { + head: { + title: "Nuxt UTM Playground", + }, + }, modules: ["../src/module"], - utm: {}, + utm: { + enabled: true, + }, devtools: { enabled: true }, }); diff --git a/src/module.ts b/src/module.ts index 90d6cbf..c7c234f 100644 --- a/src/module.ts +++ b/src/module.ts @@ -1,23 +1,32 @@ -import { defineNuxtModule, addPlugin, addImports, createResolver } from "@nuxt/kit"; +import { + defineNuxtModule, + addPlugin, + addImports, + createResolver, +} from "@nuxt/kit"; -// Module options TypeScript interface definition -export interface ModuleOptions {} +export interface ModuleOptions { + enabled: boolean; +} export default defineNuxtModule({ meta: { name: "utm", configKey: "utm", }, - // Default configuration options of the Nuxt module - defaults: {}, - setup() { + defaults: { + enabled: true, + }, + setup(options) { const resolver = createResolver(import.meta.url); - // Do not add the extension since the `.ts` will be transpiled to `.mjs` after `npm run prepack` - addPlugin(resolver.resolve("./runtime/plugin")); - addImports({ - name: 'useNuxtUTM', - from: resolver.resolve('runtime/composables'), - }) + if (options.enabled) { + // Do not add the extension since the `.ts` will be transpiled to `.mjs` after `npm run prepack` + addPlugin(resolver.resolve("./runtime/plugin")); + addImports({ + name: "useNuxtUTM", + from: resolver.resolve("runtime/composables"), + }); + } }, }); diff --git a/test/fixtures/disabled/app.vue b/test/fixtures/disabled/app.vue new file mode 100644 index 0000000..4d31aac --- /dev/null +++ b/test/fixtures/disabled/app.vue @@ -0,0 +1,12 @@ + + + diff --git a/test/fixtures/disabled/nuxt.config.ts b/test/fixtures/disabled/nuxt.config.ts new file mode 100644 index 0000000..dbca3cd --- /dev/null +++ b/test/fixtures/disabled/nuxt.config.ts @@ -0,0 +1,8 @@ +import UtmModule from "../../../src/module"; + +export default defineNuxtConfig({ + modules: [UtmModule], + utm: { + enabled: false, + }, +}); diff --git a/test/integration.test.ts b/test/integration.test.ts index 0a642ba..e1d7e86 100644 --- a/test/integration.test.ts +++ b/test/integration.test.ts @@ -113,3 +113,46 @@ describe("ssr", async () => { }); }); }); + +describe("Module configuration", () => { + describe("when enabled", async () => { + await setup({ + rootDir: fileURLToPath(new URL("./fixtures/basic", import.meta.url)), + server: true, + browser: true, + setupTimeout: 60000, + build: true, + }); + + it("should track UTM parameters", async () => { + const page = await createPage( + "/?utm_source=test_source&utm_medium=test_medium" + ); + const rawData = await page.evaluate(() => + window.localStorage.getItem("nuxt-utm-data") + ); + const entries = JSON.parse(rawData ?? "[]"); + expect(entries.length).toBeGreaterThan(0); + }); + }); + + describe("when disabled", async () => { + await setup({ + rootDir: fileURLToPath(new URL("./fixtures/disabled", import.meta.url)), + server: true, + browser: true, + setupTimeout: 60000, + build: true, + }); + + it("should not track UTM parameters", async () => { + const page = await createPage( + "/?utm_source=test_source&utm_medium=test_medium" + ); + const rawData = await page.evaluate(() => + window.localStorage.getItem("nuxt-utm-data") + ); + expect(rawData).toBeNull(); + }); + }); +});