Merge branches 'main' and 'main' of github.com:nuxt/scripts

Author: harlan-zw

docs/content/scripts/tracking/google-tag-manager.md

@@ -2,10 +2,10 @@
 title: Google Tag Manager
 description: Use Google Tag Manager in your Nuxt app.
 links:
-- label: Source
-  icon: i-simple-icons-github
-  to: https://github.com/nuxt/scripts/blob/main/src/runtime/registry/google-tag-manager.ts
-  size: xs
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/scripts/blob/main/src/runtime/registry/google-tag-manager.ts
+    size: xs
 ---
 
 [Google Tag Manager](https://marketingplatform.google.com/about/tag-manager/) is a tag management system that allows you to quickly and easily update tags and code snippets on your website or mobile app, such as those intended for traffic analysis and marketing optimization.
@@ -62,7 +62,7 @@ export default defineNuxtConfig({
         googleTagManager: {
           // .env
           // NUXT_PUBLIC_SCRIPTS_GOOGLE_TAG_MANAGER_ID=<your-id>
-          id: '', 
+          id: '',
         },
       },
     },
@@ -95,14 +95,14 @@ This composable will trigger the provided function on route change after the pag
 ```ts
 const { proxy } = useScriptGoogleTagManager({
   id: 'YOUR_ID' // id is only needed if you haven't configured globally
-}) 
+})
 
 useScriptEventPage((title, path) => {
   // triggered on route change after title is updated
-  proxy.dataLayer.push({ 
+  proxy.dataLayer.push({
     event: 'pageview',
-    title, 
-    path 
+    title,
+    path
   })
 })
 ```
@@ -163,7 +163,41 @@ export const GoogleTagManagerOptions = object({
 type GoogleTagManagerInput = typeof GoogleTagManagerOptions & { onBeforeGtmStart?: (gtag: Gtag) => void }
 ```
 
-## Example
+## Examples
+
+### Server-Side GTM Setup
+
+We can add custom GTM script source for server-side implementation. You can override the script src, this will merge in any of the computed query params. 
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      googleTagManager: {
+        id: 'GTM-XXXXXX',
+        scriptInput: {
+          src: 'https://your-domain.com/gtm.js'
+        }
+      }
+    }
+  }
+})
+```
+
+```vue
+<!-- Component usage -->
+<script setup lang="ts">
+const { proxy } = useScriptGoogleTagManager({
+  id: 'GTM-XXXXXX',
+  scriptInput: {
+    src: 'https://your-domain.com/gtm.js'
+  }
+})
+</script>
+```
+
+### Basic Usage
 
 Using Google Tag Manager only in production while using `dataLayer` to send a conversion event.
 
@@ -198,3 +232,37 @@ function sendConversion() {
 `useScriptGoogleTagManager` initialize Google Tag Manager by itself. This means it pushes the `js`, `config` and the `gtm.start` events for you.
 
 If you need to configure GTM before it starts. For example, [setting the consent mode](https://developers.google.com/tag-platform/security/guides/consent?consentmode=basic). You can use the `onBeforeGtmStart` hook which is run right before we push the `gtm.start` event into the dataLayer.
+
+```vue
+const { proxy } = useScriptGoogleTagManager({
+  onBeforeGtmStart: (gtag) => {
+    // set default consent state to denied
+    gtag('consent', 'default', {
+      'ad_user_data': 'denied',
+      'ad_personalization': 'denied',
+      'ad_storage': 'denied',
+      'analytics_storage': 'denied',
+      'wait_for_update': 500,
+    })
+
+    // if consent was already given, update gtag accordingly
+    if (consent.value === 'granted') {
+      gtag('consent', 'update', {
+        ad_user_data: consent.value,
+        ad_personalization: consent.value,
+        ad_storage: consent.value,
+        analytics_storage: consent.value
+      })
+    }
+  }
+})
+
+// push pageview events to dataLayer
+useScriptEventPage(({ title, path }) => {
+  proxy.dataLayer.push({
+    event: 'pageview',
+    title,
+    path
+  })
+})
+```

src/runtime/registry/google-tag-manager.ts

@@ -159,12 +159,14 @@ export function useScriptGoogleTagManager<T extends GoogleTagManagerApi>(
         clientInit: import.meta.server
           ? undefined
           : () => {
-            // Initialize dataLayer if it doesn't exist
+              // Initialize dataLayer if it doesn't exist
               (window as any)[dataLayerName] = (window as any)[dataLayerName] || []
 
               // Create gtag function
-              function gtag(...args: any[]) {
-                (window as any)[dataLayerName].push(args)
+              function gtag() {
+                // Pushing arguments to dataLayer is necessary for GTM to process events
+                // eslint-disable-next-line prefer-rest-params
+                (window as any)[dataLayerName].push(arguments)
               }
 
               // Allow custom initialization

src/runtime/utils.ts

@@ -13,6 +13,7 @@ import type {
   UseFunctionType,
   ScriptRegistry, UseScriptContext,
 } from '#nuxt-scripts/types'
+import { parseQuery, parseURL, withQuery } from 'ufo'
 
 export type MaybePromise<T> = Promise<T> | T
 
@@ -30,7 +31,7 @@ function validateScriptInputSchema<T extends GenericSchema>(key: string, schema:
   return null
 }
 
-type OptionsFn<O> = (options: InferIfSchema<O>) => ({
+type OptionsFn<O> = (options: InferIfSchema<O>, ctx: { scriptInput?: UseScriptInput & { src?: string } }) => ({
   scriptInput?: UseScriptInput
   scriptOptions?: NuxtUseScriptOptions
   schema?: O extends ObjectSchema<any, any> ? O : undefined
@@ -44,9 +45,34 @@ export function scriptRuntimeConfig<T extends keyof ScriptRegistry>(key: T) {
 export function useRegistryScript<T extends Record<string | symbol, any>, O = EmptyOptionsSchema>(registryKey: keyof ScriptRegistry | string, optionsFn: OptionsFn<O>, _userOptions?: RegistryScriptInput<O>): UseScriptContext<UseFunctionType<NuxtUseScriptOptions<T>, T>> {
   const scriptConfig = scriptRuntimeConfig(registryKey as keyof ScriptRegistry)
   const userOptions = Object.assign(_userOptions || {}, typeof scriptConfig === 'object' ? scriptConfig : {})
-  const options = optionsFn(userOptions as InferIfSchema<O>)
+  const options = optionsFn(userOptions as InferIfSchema<O>, { scriptInput: userOptions.scriptInput as UseScriptInput & { src?: string } })
 
-  const scriptInput = defu(userOptions.scriptInput, options.scriptInput, { key: registryKey }) as any as UseScriptInput
+  let finalScriptInput = options.scriptInput
+
+  // If user provided a custom src and the options function returned a src with query params,
+  // extract those query params and apply them to the user's custom src
+  const userSrc = (userOptions.scriptInput as any)?.src
+  const optionsSrc = (options.scriptInput as any)?.src
+
+  if (userSrc && optionsSrc && typeof optionsSrc === 'string' && typeof userSrc === 'string') {
+    const defaultUrl = parseURL(optionsSrc)
+    const customUrl = parseURL(userSrc)
+
+    // Merge query params: user params override default params
+    const defaultQuery = parseQuery(defaultUrl.search || '')
+    const customQuery = parseQuery(customUrl.search || '')
+    const mergedQuery = { ...defaultQuery, ...customQuery }
+
+    // Build the final URL with the custom base and merged query params
+    const baseUrl = customUrl.href?.split('?')[0] || userSrc
+
+    finalScriptInput = {
+      ...((options.scriptInput as object) || {}),
+      src: withQuery(baseUrl, mergedQuery),
+    }
+  }
+
+  const scriptInput = defu(finalScriptInput, userOptions.scriptInput, { key: registryKey }) as any as UseScriptInput
   const scriptOptions = Object.assign(userOptions?.scriptOptions || {}, options.scriptOptions || {})
   if (import.meta.dev) {
     scriptOptions.devtools = defu(scriptOptions.devtools, { registryKey })

test/unit/utils.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it, vi } from 'vitest'
+import { useRegistryScript } from '../../src/runtime/utils'
+
+// Mock dependencies
+vi.mock('nuxt/app', () => ({
+  useRuntimeConfig: () => ({ public: { scripts: {} } }),
+}))
+
+vi.mock('../../src/runtime/composables/useScript', () => ({
+  useScript: vi.fn((input, options) => ({ input, options })),
+}))
+
+vi.mock('#nuxt-scripts-validator', () => ({
+  parse: vi.fn(),
+}))
+
+describe('useRegistryScript query param merging', () => {
+  it('should merge query params when user provides custom src', () => {
+    const mockOptionsFunction = vi.fn((_opts, _ctx) => ({
+      scriptInput: {
+        src: 'https://example.com/script.js?id=123&auth=abc&existing=default',
+      },
+    }))
+
+    const userOptions = {
+      scriptInput: {
+        src: 'https://custom-domain.com/script.js?auth=override&new=param',
+      },
+    }
+
+    const result = useRegistryScript('test', mockOptionsFunction, userOptions)
+
+    // The options function should be called with the user options and context
+    expect(mockOptionsFunction).toHaveBeenCalledWith(
+      userOptions,
+      { scriptInput: userOptions.scriptInput },
+    )
+
+    // Check the result contains merged query params (user params come first due to object spread)
+    expect(result.input.src).toBe('https://custom-domain.com/script.js?auth=override&new=param&id=123&existing=default')
+  })
+
+  it('should preserve user query params over default ones', () => {
+    const mockOptionsFunction = vi.fn((_opts, _ctx) => ({
+      scriptInput: {
+        src: 'https://example.com/script.js?param1=default&param2=default',
+      },
+    }))
+
+    const userOptions = {
+      scriptInput: {
+        src: 'https://custom-domain.com/script.js?param1=override',
+      },
+    }
+
+    const result = useRegistryScript('test', mockOptionsFunction, userOptions)
+
+    expect(result.input.src).toBe('https://custom-domain.com/script.js?param1=override&param2=default')
+  })
+
+  it('should handle cases where user src has no query params', () => {
+    const mockOptionsFunction = vi.fn((_opts, _ctx) => ({
+      scriptInput: {
+        src: 'https://example.com/script.js?id=123&auth=abc',
+      },
+    }))
+
+    const userOptions = {
+      scriptInput: {
+        src: 'https://custom-domain.com/script.js',
+      },
+    }
+
+    const result = useRegistryScript('test', mockOptionsFunction, userOptions)
+
+    expect(result.input.src).toBe('https://custom-domain.com/script.js?id=123&auth=abc')
+  })
+
+  it('should handle cases where default src has no query params', () => {
+    const mockOptionsFunction = vi.fn((_opts, _ctx) => ({
+      scriptInput: {
+        src: 'https://example.com/script.js',
+      },
+    }))
+
+    const userOptions = {
+      scriptInput: {
+        src: 'https://custom-domain.com/script.js?custom=param',
+      },
+    }
+
+    const result = useRegistryScript('test', mockOptionsFunction, userOptions)
+
+    expect(result.input.src).toBe('https://custom-domain.com/script.js?custom=param')
+  })
+
+  it('should not modify src when no user src is provided', () => {
+    const mockOptionsFunction = vi.fn((_opts, _ctx) => ({
+      scriptInput: {
+        src: 'https://example.com/script.js?id=123&auth=abc',
+      },
+    }))
+
+    const userOptions = {}
+
+    const result = useRegistryScript('test', mockOptionsFunction, userOptions)
+
+    expect(result.input.src).toBe('https://example.com/script.js?id=123&auth=abc')
+  })
+
+  it('should handle complex URLs with paths and fragments', () => {
+    const mockOptionsFunction = vi.fn((_opts, _ctx) => ({
+      scriptInput: {
+        src: 'https://example.com/path/to/script.js?id=123&version=1',
+      },
+    }))
+
+    const userOptions = {
+      scriptInput: {
+        src: 'https://custom-domain.com/custom/path/script.js?version=2&custom=true',
+      },
+    }
+
+    const result = useRegistryScript('test', mockOptionsFunction, userOptions)
+
+    expect(result.input.src).toBe('https://custom-domain.com/custom/path/script.js?version=2&custom=true&id=123')
+  })
+})