feat(globals): runtime disable + scripts:globals hook

docs/content/docs/1.guides/4.global.md

@@ -99,6 +99,23 @@ NUXT_PUBLIC_SCRIPTS_GLOBALS_TRUSTED_SHOPS_SRC=https://widgets.trustedshops.com/X
 
 Any input field (e.g. `src`, `integrity`, `crossorigin`, or your own `data-*` attributes) can be overridden this way. The env value replaces the build-time default at runtime via `runtimeConfig.public.scriptsGlobals`.
 
+#### Disabling a global per deployment
+
+For multi-tenant single-build setups, an instance can skip a global it doesn't use without rebuilding. Set its `enabled` to `false`, or override `src` to an empty value, and the script is never registered for that deployment:
+
+```bash [.env per deployment]
+# Drop this integration for this instance only:
+NUXT_PUBLIC_SCRIPTS_GLOBALS_AWIN_SRC=
+# or, if you keep an `enabled` field on the build-time default:
+NUXT_PUBLIC_SCRIPTS_GLOBALS_AWIN_ENABLED=false
+```
+
+A disabled global resolves to `undefined` on `$scripts`, so guard access (`$scripts.awin?.`) if a script may be turned off per instance.
+
+#### Computing globals at runtime
+
+When env-var overrides aren't enough (you need to compute `src` from runtime config, or conditionally remove entries with logic), tap the [`scripts:globals`](/docs/api/nuxt-app-hooks#scriptsglobals) runtime hook. It hands you a mutable map of your declared globals' resolved inputs right before they register, so you can rewrite or `delete` entries per instance without rebuilding, while they keep their `$scripts` types and asset bundling.
+
 **Not overridable at runtime:**
 
 - `scriptOptions` (the second tuple slot, e.g. `trigger`, `mode`) and object-form triggers stay baked in at build.

docs/content/docs/3.api/6.nuxt-app-hooks.md

@@ -21,6 +21,32 @@ export default defineNuxtPlugin({
 })
 ```
 
+## `scripts:globals`{lang="ts"}
+
+- Type: `(globals: Record<string, Record<string, any>>) => void | Promise<void>`{lang="ts"}
+
+Fired inside the generated `scripts:init` plugin, right before it registers each `scripts.globals` entry. `globals` is a mutable map of your statically declared globals, keyed by each global's key, with values already merged (build-time default first, then any `NUXT_PUBLIC_SCRIPTS_GLOBALS_*` env override). Mutate it to rewrite a `src`/attributes, or `delete` an entry so it never loads, all per instance without a rebuild.
+
+This is the runtime equivalent of a globals factory: it keeps statically declared globals typed on `$scripts` and asset-bundled, while letting you compute their inputs at server/client startup. Deleting an entry (or setting `enabled: false` / an empty `src`) skips its registration; that key then resolves to `undefined` on `$scripts`, so guard access. The hook operates on the declared set only; to load a script that isn't declared in `scripts.globals`, call [`useScript()`{lang="ts"}](/docs/api/use-script) in your own plugin.
+
+Register the listener from an `enforce: 'pre'` plugin so it runs before `scripts:init`, otherwise it arrives too late to fire.
+
+```ts [plugins/nuxt-scripts-globals.ts]
+export default defineNuxtPlugin({
+ enforce: 'pre',
+ setup(nuxtApp) {
+ const { tenant } = useRuntimeConfig().public
+ nuxtApp.hooks.hook('scripts:globals', (globals) => {
+ // Drop an integration this tenant doesn't use:
+ if (!tenant.awinEnabled)
+ delete globals.awin
+ // Compute the src from runtime config:
+ globals.trustedShops.src = `https://widgets.trustedshops.com/${tenant.trustedShopsId}.js`
+ })
+ }
+})
+```
+
 ## `script:instance-fn`{lang="ts"} (Unhead Hook)
 
 - Type: `(ctx: { script: ScriptInstance<any>, fn: string | symbol, args: any, exists: boolean }) => HookResult`{lang="ts"}

packages/script/src/templates.ts

@@ -26,6 +26,9 @@ declare module '#app' {
  }
  interface RuntimeNuxtHooks {
  'scripts:updated': (ctx: { scripts: Record<string, import('#nuxt-scripts/types').NuxtDevToolsScriptInstance> }) => void | Promise<void>
+ // Index signature (not a literal-key Record) so listeners can both \`delete globals[key]\`
+ // and mutate \`globals[key].src\` without TS2790 / possibly-undefined errors.
+ 'scripts:globals': (globals: Record<string, Record<string, any>>) => void | Promise<void>
  }
 }
 ${globalsKeys.length
@@ -113,6 +116,10 @@ export function templatePlugin(config: Partial<ModuleOptions>, registry: Require
  }
  const imports = []
  const inits = []
+ // Globals are split out so the resolved inputs can be collected into a mutable map,
+ // passed through the `scripts:globals` runtime hook, then registered.
+ const globalMapEntries: string[] = []
+ const globalInits: string[] = []
  const resolvedRegistryKeys: string[] = []
  let needsIdleTimeoutImport = false
  let needsInteractionImport = false
@@ -211,7 +218,13 @@ export function templatePlugin(config: Partial<ModuleOptions>, registry: Require
  }
  const useFn = `use: () => ({ ${k}: window.${k} })`
  const optionsArg = optionsJson ? `{ ...${optionsJson}, ${useFn} }` : `{ ${useFn} }`
- inits.push(`const ${k} = useScript(${inputExpr}, ${optionsArg})`)
+ // Resolved input goes into the mutable `__globals` map keyed by its global key, so the
+ // `scripts:globals` hook can rewrite/delete/add entries before registration.
+ globalMapEntries.push(`${JSON.stringify(k)}: ${inputExpr}`)
+ // Registration is guarded so a runtime override (env or hook) can disable an entry
+ // per-instance (multi-tenant single-build): set `enabled: false` or an empty/null `src`
+ // and the script is never registered. See https://github.com/nuxt/scripts/issues/759.
+ globalInits.push(`const ${k} = __registerGlobal(__globals[${JSON.stringify(k)}], ${optionsArg})`)
  }
  // Add conditional imports for trigger composables
  const triggerImports = []
@@ -226,8 +239,20 @@ export function templatePlugin(config: Partial<ModuleOptions>, registry: Require
  }
 
  const setupBody: string[] = []
- if (hasGlobals)
+ if (hasGlobals) {
  setupBody.push(` const __scriptsGlobals = useRuntimeConfig().public.scriptsGlobals || {}`)
+ // A global is skipped when the merged input disables it: `enabled === false`, or an
+ // empty/null `src` (the env-overridable way to drop an unused integration per instance).
+ setupBody.push(` const __registerGlobal = (input, options) => { if (!input) return undefined; const { enabled, ...rest } = input; return (enabled === false || rest.src === '' || rest.src === null) ? undefined : useScript(rest, options) }`)
+ // Resolved inputs (build-time default <- env override) collected into a mutable map.
+ setupBody.push(` const __globals = {`)
+ setupBody.push(...globalMapEntries.map(e => ` ${e},`))
+ setupBody.push(` }`)
+ // Runtime hook: userland may rewrite `src`/attrs, delete keys, or add new entries before
+ // registration. Register the listener from an `enforce: 'pre'` plugin so it runs first.
+ setupBody.push(` await nuxtApp.hooks.callHook('scripts:globals', __globals)`)
+ setupBody.push(...globalInits.map(i => ` ${i}`))
+ }
  setupBody.push(...inits.map(i => ` ${i}`))
  setupBody.push(` return { provide: { scripts: { ${[...Object.keys(config.globals || {}), ...resolvedRegistryKeys].join(', ')} } } }`)
  return [
@@ -240,7 +265,7 @@ export function templatePlugin(config: Partial<ModuleOptions>, registry: Require
  ` name: "scripts:init",`,
  ` env: { islands: false },`,
  ` parallel: true,`,
- ` setup() {`,
+ ` ${hasGlobals ? 'async setup(nuxtApp) {' : 'setup() {'}`,
  ...setupBody,
  ` }`,
  `})`,

test/e2e/issue-759-globals-env-override.test.ts

@@ -8,6 +8,8 @@ const { resolve } = createResolver(import.meta.url)
 // This proves the single-build / multi-deploy contract for issue #759:
 // the same build produces different rendered src values depending on env.
 process.env.NUXT_PUBLIC_SCRIPTS_GLOBALS_TRUSTED_SHOPS_SRC = 'https://widgets.trustedshops.com/from-env.js'
+// Empty src disables the global for this instance (multi-tenant single build).
+process.env.NUXT_PUBLIC_SCRIPTS_GLOBALS_AWIN_SRC = ''
 
 await setup({
  rootDir: resolve('../fixtures/issue-759'),
@@ -22,4 +24,25 @@ describe('issue-759 globals env override', () => {
  expect(html).toContain('https://widgets.trustedshops.com/from-env.js')
  expect(html).not.toContain('build-default.js')
  })
+
+ it('a global with an empty src override is not registered for this instance', async () => {
+ const html = await $fetch<string>('/')
+ expect(html).toContain('<div id="awin-registered">no</div>')
+ })
+
+ it('the scripts:globals hook rewrites a global src at runtime', async () => {
+ const html = await $fetch<string>('/')
+ // The hook-mutated src is what actually gets registered/preloaded...
+ expect(html).toContain('href="https://scrads.example/from-hook.js"')
+ // ...while the un-mutated build-time src is never used for registration.
+ expect(html).not.toContain('href="https://scrads.example/baked.js"')
+ })
+
+ it('the scripts:globals hook can delete an entry without crashing setup', async () => {
+ const html = await $fetch<string>('/')
+ // Page renders (plugin setup didn't throw on the deleted entry)...
+ expect(html).toContain('<div id="legacy-registered">no</div>')
+ // ...and the deleted global is never registered/preloaded.
+ expect(html).not.toContain('href="https://legacy.example/baked.js"')
+ })
 })

test/fixtures/issue-759/app.vue

@@ -7,5 +7,8 @@ const rc = useRuntimeConfig()
  <div>
  <div id="globals-runtime">{{ JSON.stringify(rc.public.scriptsGlobals) }}</div>
  <div id="script-src">{{ $scripts?.trustedShops?.$script?.src || $scripts?.trustedShops?.options?.src || '' }}</div>
+ <div id="awin-registered">{{ $scripts?.awin ? 'yes' : 'no' }}</div>
+ <div id="scrads-src">{{ $scripts?.scrads?.$script?.src || $scripts?.scrads?.options?.src || '' }}</div>
+ <div id="legacy-registered">{{ $scripts?.legacy ? 'yes' : 'no' }}</div>
  </div>
 </template>

test/fixtures/issue-759/nuxt.config.ts

@@ -11,6 +11,15 @@ export default defineNuxtConfig({
  { src: 'https://widgets.trustedshops.com/build-default.js' },
  { trigger: 'onNuxtReady' },
  ],
+ // Disabled per-instance via an empty `src` env override (no rebuild).
+ awin: { src: 'https://www.dwin1.com/build-default.js' },
+ // `src` rewritten at runtime by the scripts:globals hook (see plugins/globals.ts).
+ scrads: [
+ { src: 'https://scrads.example/baked.js' },
+ { trigger: 'onNuxtReady' },
+ ],
+ // `delete`d at runtime by the scripts:globals hook; must not crash plugin setup.
+ legacy: { src: 'https://legacy.example/baked.js' },
  },
  },
  compatibilityDate: '2024-07-05',

test/fixtures/issue-759/plugins/globals.ts

@@ -0,0 +1,12 @@
+// `enforce: 'pre'` so the listener is registered before the module's scripts:init plugin
+// runs and fires the hook. Proves runtime mutation of globals per instance (issue #759).
+export default defineNuxtPlugin({
+ enforce: 'pre',
+ setup(nuxtApp) {
+ nuxtApp.hooks.hook('scripts:globals', (globals) => {
+ globals.scrads.src = 'https://scrads.example/from-hook.js'
+ // Removing an entry must skip its registration without crashing setup.
+ delete globals.legacy
+ })
+ },
+})

test/unit/templates.test.ts

@@ -36,7 +36,8 @@ describe('template plugin file', () => {
  stripe: 'https://js.stripe.com/v3/',
  },
  }, [])
- expect(res).toContain('const stripe = useScript(Object.assign({ key: "stripe" }, {"src":"https://js.stripe.com/v3/"}, __scriptsGlobals["stripe"] || {}), { use: () => ({ stripe: window.stripe }) })')
+ expect(res).toContain('"stripe": Object.assign({ key: "stripe" }, {"src":"https://js.stripe.com/v3/"}, __scriptsGlobals["stripe"] || {})')
+ expect(res).toContain('const stripe = __registerGlobal(__globals["stripe"], { use: () => ({ stripe: window.stripe }) })')
  })
  it('object global', async () => {
  const res = templatePlugin({
@@ -50,7 +51,8 @@ describe('template plugin file', () => {
  },
  },
  }, [])
- expect(res).toContain('const stripe = useScript(Object.assign({ key: "stripe" }, {"async":true,"src":"https://js.stripe.com/v3/","key":"stripe","defer":true,"referrerpolicy":"no-referrer"}, __scriptsGlobals["stripe"] || {}), { use: () => ({ stripe: window.stripe }) })')
+ expect(res).toContain('"stripe": Object.assign({ key: "stripe" }, {"async":true,"src":"https://js.stripe.com/v3/","key":"stripe","defer":true,"referrerpolicy":"no-referrer"}, __scriptsGlobals["stripe"] || {})')
+ expect(res).toContain('const stripe = __registerGlobal(__globals["stripe"], { use: () => ({ stripe: window.stripe }) })')
  })
  it('array global', async () => {
  const res = templatePlugin({
@@ -70,7 +72,8 @@ describe('template plugin file', () => {
  ],
  },
  }, [])
- expect(res).toContain('const stripe = useScript(Object.assign({ key: "stripe" }, {"async":true,"src":"https://js.stripe.com/v3/","key":"stripe","defer":true,"referrerpolicy":"no-referrer"}, __scriptsGlobals["stripe"] || {}), { ...{"trigger":"onNuxtReady","mode":"client"}, use: () => ({ stripe: window.stripe }) })')
+ expect(res).toContain('"stripe": Object.assign({ key: "stripe" }, {"async":true,"src":"https://js.stripe.com/v3/","key":"stripe","defer":true,"referrerpolicy":"no-referrer"}, __scriptsGlobals["stripe"] || {})')
+ expect(res).toContain('const stripe = __registerGlobal(__globals["stripe"], { ...{"trigger":"onNuxtReady","mode":"client"}, use: () => ({ stripe: window.stripe }) })')
  })
  it('mixing global', async () => {
  const res = templatePlugin({
@@ -100,11 +103,18 @@ describe('template plugin file', () => {
  name: "scripts:init",
  env: { islands: false },
  parallel: true,
- setup() {
+async setup(nuxtApp) {
  const __scriptsGlobals = useRuntimeConfig().public.scriptsGlobals || {}
- const stripe1 = useScript(Object.assign({ key: "stripe1" }, {"src":"https://js.stripe.com/v3/"}, __scriptsGlobals["stripe1"] || {}), { use: () => ({ stripe1: window.stripe1 }) })
- const stripe2 = useScript(Object.assign({ key: "stripe2" }, {"async":true,"src":"https://js.stripe.com/v3/","key":"stripe","defer":true,"referrerpolicy":"no-referrer"}, __scriptsGlobals["stripe2"] || {}), { use: () => ({ stripe2: window.stripe2 }) })
- const stripe3 = useScript(Object.assign({ key: "stripe3" }, {"src":"https://js.stripe.com/v3/"}, __scriptsGlobals["stripe3"] || {}), { ...{"trigger":"onNuxtReady","mode":"client"}, use: () => ({ stripe3: window.stripe3 }) })
+ const __registerGlobal = (input, options) => { if (!input) return undefined; const { enabled, ...rest } = input; return (enabled === false || rest.src === '' || rest.src === null) ? undefined : useScript(rest, options) }
+ const __globals = {
+ "stripe1": Object.assign({ key: "stripe1" }, {"src":"https://js.stripe.com/v3/"}, __scriptsGlobals["stripe1"] || {}),
+ "stripe2": Object.assign({ key: "stripe2" }, {"async":true,"src":"https://js.stripe.com/v3/","key":"stripe","defer":true,"referrerpolicy":"no-referrer"}, __scriptsGlobals["stripe2"] || {}),
+ "stripe3": Object.assign({ key: "stripe3" }, {"src":"https://js.stripe.com/v3/"}, __scriptsGlobals["stripe3"] || {}),
+ }
+ await nuxtApp.hooks.callHook('scripts:globals', __globals)
+ const stripe1 = __registerGlobal(__globals["stripe1"], { use: () => ({ stripe1: window.stripe1 }) })
+ const stripe2 = __registerGlobal(__globals["stripe2"], { use: () => ({ stripe2: window.stripe2 }) })
+ const stripe3 = __registerGlobal(__globals["stripe3"], { ...{"trigger":"onNuxtReady","mode":"client"}, use: () => ({ stripe3: window.stripe3 }) })
  return { provide: { scripts: { stripe1, stripe2, stripe3 } } }
  }
  })"
@@ -289,6 +299,71 @@ describe('template plugin file', () => {
  expect(res).toContain('Object.assign({ key: "trustedShops" }, {"src":"https://widgets.trustedshops.com/build-time.js"}, __scriptsGlobals["trustedShops"] || {})')
  })
 
+ // A runtime override can drop an unused integration per instance (multi-tenant single
+ // build) by disabling it: `enabled: false` or an empty/null `src`. The generated plugin
+ // routes every global through __registerGlobal which skips registration when disabled.
+ // See https://github.com/nuxt/scripts/issues/759.
+ it('global registration is guarded so a runtime override can disable it', async () => {
+ const res = templatePlugin({
+ globals: {
+ awin: { src: 'https://www.dwin1.com/build-time.js' },
+ },
+ }, [])
+ // Helper is emitted once and strips `enabled` so it never leaks as a script attribute.
+ expect(res).toContain('const __registerGlobal = (input, options) => { if (!input) return undefined; const { enabled, ...rest } = input; return (enabled === false || rest.src === \'\' || rest.src === null) ? undefined : useScript(rest, options) }')
+ // Each global goes through the guard rather than calling useScript directly.
+ expect(res).toContain('const awin = __registerGlobal(__globals["awin"]')
+ expect(res).not.toContain('const awin = useScript(')
+ })
+
+ // Resolved inputs are collected into a mutable map and passed through a runtime hook
+ // before registration, so userland can rewrite/delete/add entries per instance.
+ // See https://github.com/nuxt/scripts/issues/759.
+ it('globals are passed through the scripts:globals runtime hook before registration', async () => {
+ const res = templatePlugin({
+ globals: {
+ awin: { src: 'https://www.dwin1.com/build-time.js' },
+ },
+ }, [])
+ // setup is async and receives nuxtApp so the hook can be awaited.
+ expect(res).toContain('async setup(nuxtApp) {')
+ // Resolved input lives in the mutable map keyed by the global key.
+ expect(res).toContain('"awin": Object.assign({ key: "awin" }')
+ // Hook fires before any registration, with the mutable map.
+ expect(res).toContain('await nuxtApp.hooks.callHook(\'scripts:globals\', __globals)')
+ const hookIdx = res.indexOf('callHook(\'scripts:globals\'')
+ const registerIdx = res.indexOf('const awin = __registerGlobal')
+ expect(hookIdx).toBeGreaterThan(-1)
+ expect(registerIdx).toBeGreaterThan(hookIdx)
+ })
+
+ // The runtime guard itself: enabled:false and empty/null src skip; undefined src (non-src
+ // globals) and a normal src register.
+ it('__registerGlobal skips disabled entries and registers the rest', () => {
+ const calls: any[] = []
+ const useScript = (input: any) => {
+ calls.push(input)
+ return input
+ }
+ const __registerGlobal = (input: any, options: any) => {
+ if (!input)
+ return undefined
+ const { enabled, ...rest } = input
+ return (enabled === false || rest.src === '' || rest.src === null) ? undefined : useScript(rest, options)
+ }
+
+ expect(__registerGlobal({ key: 'a', src: 'https://e/x.js' }, {})).toBeDefined()
+ expect(__registerGlobal({ key: 'b', src: 'https://e/x.js', enabled: false }, {})).toBeUndefined()
+ expect(__registerGlobal({ key: 'c', src: '' }, {})).toBeUndefined()
+ expect(__registerGlobal({ key: 'd', src: null }, {})).toBeUndefined()
+ // No src field (inline/non-src global) still registers.
+ expect(__registerGlobal({ key: 'e' }, {})).toBeDefined()
+ // A hook that deleted the entry leaves `undefined`; must not throw on destructure.
+ expect(__registerGlobal(undefined, {})).toBeUndefined()
+ // `enabled` is stripped, never forwarded to useScript as an attribute.
+ expect(calls.every(c => !('enabled' in c))).toBe(true)
+ })
+
  // Test serviceWorker trigger in globals
  it('global with serviceWorker trigger', async () => {
  const res = templatePlugin({