Global Scripts

Background

Nuxt's app.head can load a global script:

export default defineNuxtConfig({
  app: {
    head: {
      script: [{ src: 'https://analytics.com/tracker.js', async: true }]
    }
  }
})

scripts.globals routes the same script through Nuxt Scripts, including its triggers and warmup behavior.

Use a global script when:

• The script isn't a supported Registry Script.
• You do not call the third-party API, such as gtag.
• You call the API but do not need it typed.

Use a registry composable or useScript() when you need a typed API.

Usage

The globals key supports strings, objects, and two-item tuples.

URL string

export default defineNuxtConfig({
  scripts: {
    globals: {
      myScript: 'https://analytics.com/tracker.js',
    }
  }
})

Script attributes

export default defineNuxtConfig({
  scripts: {
    globals: {
      myScript: {
        src: 'https://example.com/script.js',
        integrity: 'sha256-abc123',
      }
    }
  }
})

Script options

Use a two-item tuple to include Script Options:

export default defineNuxtConfig({
  scripts: {
    globals: {
      myScript: [
        { src: 'https://example.com/script.js' },
        // load the script as part of the hydration process instead of on idle
        { trigger: 'client' }
      ]
    }
  }
})

Keep trigger in the tuple's second item. If it is placed beside src in the input object, the current generated plugin passes it as script input rather than as a useScript option, so the global still inherits the module's default trigger.

Overriding the script per deployment

Override globals through Nuxt's public runtime config with NUXT_PUBLIC_SCRIPTS_GLOBALS_* environment variables. One build can then use different Trusted Shops, Awin, or GTM values across deployments.

The env var path mirrors the global's key in SCREAMING_SNAKE_CASE (camelCase boundaries become underscores):

export default defineNuxtConfig({
  scripts: {
    globals: {
      trustedShops: {
        src: 'https://widgets.trustedshops.com/build-default.js',
      },
    },
  },
})

# Override the src for this deployment only:
NUXT_PUBLIC_SCRIPTS_GLOBALS_TRUSTED_SHOPS_SRC=https://widgets.trustedshops.com/X1234.js

Object fields such as src, integrity, crossorigin, and referrerpolicy can be overridden this way. The environment value replaces the build-time default at runtime via runtimeConfig.public.scriptsGlobals.

Disabling a global per deployment

A deployment can also skip a global without rebuilding. Use an empty src in an environment variable. A runtime hook or typed runtime-config value can instead set enabled to the boolean false:

# Drop this integration for this instance only:
NUXT_PUBLIC_SCRIPTS_GLOBALS_AWIN_SRC=

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

Use the scripts:globals runtime hook when src depends on runtime config or a deployment must remove an entry conditionally. The hook receives the resolved inputs immediately before registration. Rewrite or delete declared entries there; their $scripts types remain available.

Not overridable at runtime:

• scriptOptions (the second tuple slot, for example trigger or warmupStrategy) 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 environment-overridable. They load directly from their CDN at runtime. If you need bundling, use useScript() with a static src instead.

Typos in environment-variable keys produce warnings with suggestions. For example, NUXT_PUBLIC_SCRIPTS_GLOBALS_TRUSTED_SHOP_SRC suggests trustedShops.

Accessing a global script

Nuxt Scripts registers globals on the Nuxt app's typed $scripts property:

<script setup lang="ts">
const { $scripts } = useNuxtApp()
$scripts.myScript // UseScriptContext<any> | undefined
</script>

Generated plugin

The module turns scripts.globals into a virtual Nuxt plugin. That plugin calls useScript(), so globals share its defaults and singleton behavior.

export default defineNuxtConfig({
  scripts: {
    globals: {
      tracker: 'https://analytics.com/tracker.js',
    }
  }
})