feat: build-time debug flag with script-lifecycle tracing (#760)

Author: harlan-zw

packages/script/src/module.ts

@@ -563,6 +563,14 @@ export default defineNuxtModule<ModuleOptions>({
  : undefined,
 }asany
 
+// Build-time constant: `__NUXT_SCRIPTS_DEBUG__` is replaced inline by the
+// bundler, so debug branches DCE away in production when `debug: false`.
+constdebugConst=JSON.stringify(!!config.debug)
+nuxt.options.vite||={}
+nuxt.options.vite.define={ ...nuxt.options.vite.define,__NUXT_SCRIPTS_DEBUG__: debugConst}
+nuxt.options.nitro||={}
+nuxt.options.nitro.replace={ ...nuxt.options.nitro.replace,__NUXT_SCRIPTS_DEBUG__: debugConst}
+
 // Register proxy handler unconditionally. The handler rejects unknown domains
 // at runtime, so it's safe to register even when no scripts use proxy.
 constscriptsBase=config.prefix||'/_scripts'

packages/script/src/runtime/composables/useScript.ts

@@ -6,6 +6,7 @@ import { injectHead, onNuxtReady, useHead, useNuxtApp, useRuntimeConfig } from '
 import{markRaw,ref}from'vue'
 // @ts-expect-error virtual template
 import{resolveTrigger}from'#build/nuxt-scripts-trigger-resolver'
+import{debugEnabled}from'../debug'
 import{logger}from'../logger'
 
 typeNuxtScriptsApp=ReturnType<typeofuseNuxtApp>&{
@@ -293,6 +294,58 @@ export function useScript<T extends Record<symbol | string, any> = Record<symbol
 returnreloaded.load()
 }
 nuxtApp.$scripts[id]=instance
+
+// Debug logging: emit a structured log per script lifecycle event when debug
+// is enabled at build-time (or in dev). Tagged with registryKey when present
+// (e.g. `googleTagManager`), else the script id (src/key).
+if(import.meta.client&&debugEnabled){
+constregistryKey=options?.devtools?.registryKeyasstring|undefined
+constsrc=(inputasany)?.src
+consttrigger=options?.trigger
+constloadedFrom=options?.devtools?.loadedFromasstring|undefined
+constctx={
+id: instance.id,
+ ...(registryKey ? { registryKey } : {}),
+ ...(src ? { src } : {}),
+ ...(loadedFrom ? { loadedFrom } : {}),
+}
+constlog=logger.withTag(registryKey||instance.id)
+constt0=performance.now()
+lettLoadStart=0
+log.debug('registered',{
+ ...ctx,
+trigger: typeoftrigger==='object' ? (triggerinstanceofPromise ? 'promise' : JSON.stringify(trigger)) : trigger,
+})
+options.head.hooks.hook('script:updated',(entry)=>{
+if(entry.script.id!==instance.id)
+return
+conststatus=entry.script.status
+constelapsed=Math.round(performance.now()-t0)
+if(status==='loading')
+tLoadStart=performance.now()
+constpayload: Record<string,any>={ ...ctx, status,elapsedMs: elapsed}
+if(status==='loaded'&&tLoadStart)
+payload.loadMs=Math.round(performance.now()-tLoadStart)
+constfn=status==='error' ? log.warn : log.debug
+fn(`status: ${status}`,payload)
+})
+const_origLoad=instance.load
+instance.load=()=>{
+log.debug('load() called',ctx)
+return_origLoad()
+}
+const_origRemove=instance.remove
+instance.remove=()=>{
+log.debug('remove() called',ctx)
+return_origRemove()
+}
+const_origReload=instance.reload
+instance.reload=async()=>{
+log.debug('reload() called',ctx)
+return_origReload()
+}
+}
+
 // used for devtools integration
 if(import.meta.dev&&import.meta.client){
 if(exists){

packages/script/src/runtime/debug.ts

@@ -0,0 +1,4 @@
+declareconst__NUXT_SCRIPTS_DEBUG__: boolean
+
+exportconstdebugEnabled: boolean
+=typeof__NUXT_SCRIPTS_DEBUG__!=='undefined'&&__NUXT_SCRIPTS_DEBUG__

packages/script/src/runtime/logger.ts

@@ -1,6 +1,10 @@
 import{createConsola}from'consola'
+import{debugEnabled}from'./debug'
 
 exportconstlogger=createConsola({
+// 4 = debug, 3 = info (consola defaults). Lift the threshold so `logger.debug`
+// fires when debug is opted-in at build time or in dev.
+level: debugEnabled ? 4 : 3,
 defaults: {
 tag: 'nuxt-scripts',
 },

packages/script/src/runtime/types.ts

@@ -168,6 +168,13 @@ export type NuxtUseScriptOptions<T extends Record<symbol | string, any> = {}> =
  * @internal
  */
 registryMeta?: Record<string,string>
+/**
+ * Source location (file:line:col) the script was registered from, captured
+ * via dev-only stack-trace parsing in `useRegistryScript`. Surfaced in
+ * debug logs and Nuxt DevTools.
+ * @internal
+ */
+loadedFrom?: string
 /**
  * Known third-party domains this script communicates with.
  * @internal