feat: env-var overrides for scripts.globals (single-build, multi-deploy) (#780)

Author: harlan-zw

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

@@ -74,6 +74,38 @@ export default defineNuxtConfig({
 })
 ```
 
+### Overriding the script per deployment
+
+Globals also support runtime overrides via `NUXT_PUBLIC_SCRIPTS_GLOBALS_*` env vars. This lets a single build serve multiple deployments with different third-party IDs (e.g. Trusted Shops, Awin, GTM) without rebuilding.
+
+The env var path mirrors the global's key in `SCREAMING_SNAKE_CASE` (camelCase boundaries become underscores):
+
+```ts [nuxt.config.ts]
+exportdefaultdefineNuxtConfig({
+ scripts: {
+ globals: {
+ trustedShops: {
+ src: 'https://widgets.trustedshops.com/build-default.js',
+ },
+ },
+ },
+})
+```
+
+```bash [.env per deployment]
+# Override the src for this deployment only:
+NUXT_PUBLIC_SCRIPTS_GLOBALS_TRUSTED_SHOPS_SRC=https://widgets.trustedshops.com/X1234.js
+```
+
+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`.
+
+**Not overridable at runtime:**
+
+-`scriptOptions` (the second tuple slot, e.g. `trigger`, `mode`) and object-form triggers stay baked in at build.
+- Asset bundling: the bundle transformer can't statically read `src` through the runtime-config wrapper, so it skips globals that are env-overridable. They load directly from their CDN at runtime. If you need bundling, set `src` statically and skip the env override for that script.
+
+Typos in env var keys are surfaced as dev warnings with suggestions, e.g. `NUXT_PUBLIC_SCRIPTS_GLOBALS_TRUSTED_SHOP_SRC` → suggest `trustedShops`.
+
 ### Accessing a global script
 
 All Nuxt Scripts register on the `$scripts` Nuxt App property.

packages/script/src/module.ts

@@ -563,6 +563,7 @@ export default defineNuxtModule<ModuleOptions>({
 scripts,
 newSet(Object.keys(config.registry||{}).filter(k=>(config.registryasany)?.[k]!==false)),
 logger,
+Object.keys(config.globals||{}),
 )
 
 // Setup runtimeConfig for proxies and devtools.
@@ -720,6 +721,35 @@ export default defineNuxtModule<ModuleOptions>({
 }
 }
 
+// Expose globals input via runtimeConfig so it can be overridden per
+// deployment via NUXT_PUBLIC_SCRIPTS_GLOBALS_<KEY>_<FIELD> env vars
+// without rebuilding. The codegen reads + Object.assigns these on plugin setup.
+// Must run in the main setup body — runtimeConfig is locked in before modules:done.
+if(Object.keys(config.globals||{}).length){
+constglobalsRuntime: Record<string,Record<string,any>>={}
+for(const[k,c]ofObject.entries(config.globals||{})){
+letinput: Record<string,any>
+if(typeofc==='string')
+input={src: c}
+elseif(Array.isArray(c)&&c.length===2)
+input=typeofc[0]==='string' ? {src: c[0]} : { ...c[0]}
+elseif(typeofc==='object'&&c!==null)
+input={ ...(casRecord<string,any>)}
+else
+continue
+// scriptOptions / object-triggers are build-time only — they can't
+// round-trip through env vars and stay baked into the generated plugin.
+deleteinput.trigger
+globalsRuntime[k]=input
+}
+// Top-level `scriptsGlobals` (camelCase, no hyphen) so Nuxt's standard
+// env-var override resolves cleanly: NUXT_PUBLIC_SCRIPTS_GLOBALS_<KEY>_<FIELD>.
+nuxt.options.runtimeConfig.public.scriptsGlobals=defu(
+globalsRuntime,
+nuxt.options.runtimeConfig.public.scriptsGlobalsasany,
+)asany
+}
+
 nuxt.hooks.hook('modules:done',async()=>{
 constregistryScripts=[...scripts]
 

packages/script/src/templates.ts

@@ -17,17 +17,27 @@ export function registerTypeTemplates({ config, newScripts }: TypeTemplateContex
 addTypeTemplate({
 filename: 'types/nuxt-scripts-augments.d.ts',
 getContents: ()=>{
+constglobalsKeys=Object.keys(config.globals||{})
 letaugments=`// Generated by @nuxt/scripts
 declare module '#app' {
  interface NuxtApp {
- $scripts: Record<${[...[...Object.keys(config.globals||{}), ...Object.keys(config.registry||{})].map(k=>`'${k}'`), ...['string']].join(' | ')}, import('#nuxt-scripts/types').UseScriptContext<any> | undefined>
+ $scripts: Record<${[...[...globalsKeys, ...Object.keys(config.registry||{})].map(k=>`'${k}'`), ...['string']].join(' | ')}, import('#nuxt-scripts/types').UseScriptContext<any> | undefined>
  _scripts: Record<string, import('#nuxt-scripts/types').NuxtDevToolsScriptInstance>
  }
  interface RuntimeNuxtHooks {
  'scripts:updated': (ctx: { scripts: Record<string, import('#nuxt-scripts/types').NuxtDevToolsScriptInstance> }) => void | Promise<void>
  }
 }
+${globalsKeys.length
+ ? `declare module '@nuxt/schema' {
+ interface PublicRuntimeConfig {
+ scriptsGlobals?: {
+${globalsKeys.map(k=>` ${JSON.stringify(k)}?: Record<string, any>`).join('\n')}
+ }
+ }
+}
 `
+ : ''}`
 
 if(newScripts.length){
 augments+=`
@@ -142,45 +152,66 @@ export function templatePlugin(config: Partial<ModuleOptions>, registry: Require
 inits.push(`const ${k} = ${importDefinition.import.name}(${argsJson})`)
 }
 }
+// Globals input is merged at runtime so `runtimeConfig.public['nuxt-scripts'].globals[<key>]`
+// (set via env vars like NUXT_PUBLIC_NUXT_SCRIPTS_GLOBALS_<KEY>_<FIELD>) wins over
+// the build-time defaults. scriptOptions/object-triggers stay compile-time.
+consthasGlobals=Object.keys(config.globals||{}).length>0
 for(const[k,c]ofObject.entries(config.globals||{})){
+letbuildInput: Record<string,any>
+letextraOptions: Record<string,any>|undefined
 if(typeofc==='string'){
-inits.push(`const ${k} = useScript(${JSON.stringify({src: c,key: k})}, { use: () => ({ ${k}: window.${k} }) })`)
+buildInput={src: c}
 }
 elseif(Array.isArray(c)&&c.length===2){
-constoptions=c[1]
-consttriggerResolved=resolveTriggerForTemplate(options?.trigger)
-if(triggerResolved){
-if(triggerResolved.includes('useScriptTriggerIdleTimeout'))
-needsIdleTimeoutImport=true
-if(triggerResolved.includes('useScriptTriggerInteraction'))
-needsInteractionImport=true
-if(triggerResolved.includes('useScriptTriggerServiceWorker'))
-needsServiceWorkerImport=true
-constresolvedOptions={ ...options,trigger: '__TRIGGER_PLACEHOLDER__'}asany
-constoptionsJson=JSON.stringify(resolvedOptions).replace(TRIGGER_PLACEHOLDER_RE,triggerResolved)
-inits.push(`const ${k} = useScript(${JSON.stringify({key: k, ...(typeofc[0]==='string' ? {src: c[0]} : c[0])})}, { ...${optionsJson}, use: () => ({ ${k}: window.${k} }) })`)
-}
-else{
-inits.push(`const ${k} = useScript(${JSON.stringify({key: k, ...(typeofc[0]==='string' ? {src: c[0]} : c[0])})}, { ...${JSON.stringify(c[1])}, use: () => ({ ${k}: window.${k} }) })`)
-}
+buildInput=typeofc[0]==='string' ? {src: c[0]} : { ...(c[0]asany)}
+extraOptions=c[1]asany
 }
 elseif(typeofc==='object'&&c!==null){
-consttriggerResolved=resolveTriggerForTemplate((casany).trigger)
-if(triggerResolved){
-if(triggerResolved.includes('useScriptTriggerIdleTimeout'))
+buildInput={ ...(casany)}
+}
+else{
+continue
+}
+// Object-form triggers in the input bag need a placeholder substitution after JSON.stringify.
+constinputTrigger=buildInput.trigger
+constinputTriggerResolved=resolveTriggerForTemplate(inputTrigger)
+if(inputTriggerResolved)
+buildInput.trigger='__TRIGGER_PLACEHOLDER__'
+letbuildInputJson=JSON.stringify(buildInput)
+if(inputTriggerResolved)
+buildInputJson=buildInputJson.replace(TRIGGER_PLACEHOLDER_RE,inputTriggerResolved)
+constinputExpr=`Object.assign({ key: ${JSON.stringify(k)} }, ${buildInputJson}, __scriptsGlobals[${JSON.stringify(k)}] || {})`
+
+// scriptOptions trigger (array form, second slot) — same dance, separate JSON.
+letoptionsJson=''
+if(extraOptions&&Object.keys(extraOptions).length>0){
+constoptsCopy: Record<string,any>={ ...extraOptions}
+constoptsTriggerResolved=resolveTriggerForTemplate(optsCopy.trigger)
+if(optsTriggerResolved)
+optsCopy.trigger='__TRIGGER_PLACEHOLDER__'
+optionsJson=JSON.stringify(optsCopy)
+if(optsTriggerResolved)
+optionsJson=optionsJson.replace(TRIGGER_PLACEHOLDER_RE,optsTriggerResolved)
+if(optsTriggerResolved){
+if(optsTriggerResolved.includes('useScriptTriggerIdleTimeout'))
 needsIdleTimeoutImport=true
-if(triggerResolved.includes('useScriptTriggerInteraction'))
+if(optsTriggerResolved.includes('useScriptTriggerInteraction'))
 needsInteractionImport=true
-if(triggerResolved.includes('useScriptTriggerServiceWorker'))
+if(optsTriggerResolved.includes('useScriptTriggerServiceWorker'))
 needsServiceWorkerImport=true
-constresolvedOptions={ ...c,trigger: '__TRIGGER_PLACEHOLDER__'}asany
-constargsJson=JSON.stringify({key: k, ...resolvedOptions}).replace(TRIGGER_PLACEHOLDER_RE,triggerResolved)
-inits.push(`const ${k} = useScript(${argsJson}, { use: () => ({ ${k}: window.${k} }) })`)
-}
-else{
-inits.push(`const ${k} = useScript(${JSON.stringify({key: k, ...c})}, { use: () => ({ ${k}: window.${k} }) })`)
 }
 }
+if(inputTriggerResolved){
+if(inputTriggerResolved.includes('useScriptTriggerIdleTimeout'))
+needsIdleTimeoutImport=true
+if(inputTriggerResolved.includes('useScriptTriggerInteraction'))
+needsInteractionImport=true
+if(inputTriggerResolved.includes('useScriptTriggerServiceWorker'))
+needsServiceWorkerImport=true
+}
+constuseFn=`use: () => ({ ${k}: window.${k} })`
+constoptionsArg=optionsJson ? `{ ...${optionsJson}, ${useFn} }` : `{ ${useFn} }`
+inits.push(`const ${k} = useScript(${inputExpr}, ${optionsArg})`)
 }
 // Add conditional imports for trigger composables
 consttriggerImports=[]
@@ -194,9 +225,14 @@ export function templatePlugin(config: Partial<ModuleOptions>, registry: Require
 triggerImports.push(`import { useScriptTriggerServiceWorker } from '#nuxt-scripts/composables/useScriptTriggerServiceWorker'`)
 }
 
+constsetupBody: string[]=[]
+if(hasGlobals)
+setupBody.push(` const __scriptsGlobals = useRuntimeConfig().public.scriptsGlobals || {}`)
+setupBody.push(...inits.map(i=>` ${i}`))
+setupBody.push(` return { provide: { scripts: { ${[...Object.keys(config.globals||{}), ...resolvedRegistryKeys].join(', ')} } } }`)
 return[
 `import { useScript } from '#nuxt-scripts/composables/useScript'`,
-`import { defineNuxtPlugin } from 'nuxt/app'`,
+`import { defineNuxtPlugin${hasGlobals ? ', useRuntimeConfig' : ''} } from 'nuxt/app'`,
  ...triggerImports,
  ...imports,
 '',
@@ -205,8 +241,7 @@ export function templatePlugin(config: Partial<ModuleOptions>, registry: Require
 ` env: { islands: false },`,
 ` parallel: true,`,
 ` setup() {`,
- ...inits.map(i=>` ${i}`),
-` return { provide: { scripts: { ${[...Object.keys(config.globals||{}), ...resolvedRegistryKeys].join(', ')} } } }`,
+ ...setupBody,
 ` }`,
 `})`,
 ].join('\n')

packages/script/src/validate-env.ts

@@ -5,6 +5,7 @@ const UPPER_RE = /([A-Z])/g
 consttoScreamingSnake=(s: string)=>s.replace(UPPER_RE,'_$1').toUpperCase()
 
 constENV_PREFIX='NUXT_PUBLIC_SCRIPTS_'
+constGLOBALS_ENV_PREFIX='NUXT_PUBLIC_SCRIPTS_GLOBALS_'
 
 functionlevenshtein(a: string,b: string): number{
 if(a===b)
@@ -39,7 +40,14 @@ export function validateScriptsEnvVars(
 scripts: RegistryScript[],
 enabledRegistryKeys: Set<string>,
 logger: ConsolaInstance,
+globalsKeys: string[]=[],
 ): void{
+// Configured `scripts.globals` keys — env vars NUXT_PUBLIC_SCRIPTS_GLOBALS_<KEY>_*
+// are validated against these (typo detection, suggestions). Globals are
+// schemaless so we can't validate the trailing field name.
+constvalidGlobalsByScreaming=newMap<string,string>()
+for(constkofglobalsKeys)
+validGlobalsByScreaming.set(toScreamingSnake(k),k)
 // Build a map from screaming-snake registry key to its envDefaults fields
 constvalidByKey=newMap<string,{camel: string,fields: Set<string>}>()
 for(constsofscripts){
@@ -50,7 +58,7 @@ export function validateScriptsEnvVars(
 validByKey.set(screaming,{camel: s.registryKey, fields })
 }
 
-if(!validByKey.size)
+if(!validByKey.size&&!validGlobalsByScreaming.size)
 return
 
 constallValidEnvKeys: string[]=[]
@@ -62,6 +70,41 @@ export function validateScriptsEnvVars(
 for(constenvKeyofObject.keys(process.env)){
 if(!envKey.startsWith(ENV_PREFIX))
 continue
+// Globals env vars (NUXT_PUBLIC_SCRIPTS_GLOBALS_*) target user-defined keys in
+// `scripts.globals`. Validate against the configured globals keys with typo
+// suggestions; fields can't be checked (globals are schemaless).
+if(envKey.startsWith(GLOBALS_ENV_PREFIX)){
+if(!validGlobalsByScreaming.size)
+continue
+constsegment=envKey.slice(GLOBALS_ENV_PREFIX.length)
+constsegmentParts=segment.split('_')
+letmatched=false
+for(const[screaming]ofvalidGlobalsByScreaming){
+constkeyParts=screaming.split('_')
+if(segmentParts.length>keyParts.length
+&&keyParts.every((p,i)=>segmentParts[i]===p)){
+matched=true
+break
+}
+}
+if(matched)
+continue
+// No exact prefix match — suggest the closest configured globals key.
+letbest: {screaming: string,camel: string,dist: number}|undefined
+for(const[screaming,camel]ofvalidGlobalsByScreaming){
+consthead=segmentParts.slice(0,screaming.split('_').length).join('_')
+constd=levenshtein(head,screaming)
+if(!best||d<best.dist)
+best={ screaming, camel,dist: d}
+}
+constsuggestion=best&&best.dist<=Math.max(2,Math.floor(best.screaming.length/2))
+ ? ` Did you mean globals key \`${best.camel}\` (\`${GLOBALS_ENV_PREFIX}${best.screaming}_*\`)?`
+ : ` Configured globals: ${[...validGlobalsByScreaming.values()].map(k=>`\`${k}\``).join(', ')}.`
+logger.warn(
+`[scripts] env var \`${envKey}\` does not map to any configured \`scripts.globals\` key.${suggestion}`,
+)
+continue
+}
 if(allValidEnvKeys.includes(envKey))
 continue
 

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

@@ -0,0 +1,25 @@
+import{createResolver}from'@nuxt/kit'
+import{$fetch,setup}from'@nuxt/test-utils/e2e'
+import{describe,expect,it}from'vitest'
+
+const{ resolve }=createResolver(import.meta.url)
+
+// Set env vars BEFORE setup() so Nitro picks them up when it builds the server.
+// 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'
+
+awaitsetup({
+rootDir: resolve('../fixtures/issue-759'),
+dev: true,
+browser: false,
+})
+
+describe('issue-759 globals env override',()=>{
+it('runtimeConfig.public.scriptsGlobals picks up the env-var override',async()=>{
+consthtml=await$fetch<string>('/')
+// The fixture serializes rc.public.scriptsGlobals into #globals-runtime.
+expect(html).toContain('https://widgets.trustedshops.com/from-env.js')
+expect(html).not.toContain('build-default.js')
+})
+})

test/fixtures/issue-759/app.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+const { $scripts } =useNuxtApp() asany
+const rc =useRuntimeConfig()
+</script>
+
+<template>
+ <div>
+ <divid="globals-runtime">{{ JSON.stringify(rc.public.scriptsGlobals) }}</div>
+ <divid="script-src">{{ $scripts?.trustedShops?.$script?.src || $scripts?.trustedShops?.options?.src || '' }}</div>
+ </div>
+</template>

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

@@ -0,0 +1,17 @@
+import{defineNuxtConfig}from'nuxt/config'
+
+// Single build, multi-deployment: src is overridable via
+// NUXT_PUBLIC_SCRIPTS_GLOBALS_TRUSTED_SHOPS_SRC at server start.
+// https://github.com/nuxt/scripts/issues/759
+exportdefaultdefineNuxtConfig({
+modules: ['@nuxt/scripts'],
+scripts: {
+globals: {
+trustedShops: [
+{src: 'https://widgets.trustedshops.com/build-default.js'},
+{trigger: 'onNuxtReady'},
+],
+},
+},
+compatibilityDate: '2024-07-05',
+})

test/fixtures/issue-759/package.json

@@ -0,0 +1,3 @@
+{
+"private": true
+}