Global Scripts

Background

While the app.head method in Nuxt Config allows for loading global scripts, it can be cumbersome and requires manual optimization.

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

A simpler method is now available: directly input the script URL into scripts.globals. You can also include optional settings to tailor the script loading process with specific optimizations in mind.

You may consider using global scripts when:

• The script isn't a supported Registry Script.
• You don't care about interacting with the API provided by the third-party script (e.g. you don't need to use gtag from Google Analytics).
• You are interacting with the API provided by the third-party script, but you don't care about type safety.

Otherwise, it's recommended to use useScript() to load scripts in a safer way.

Usage

The globals key supports strings, objects and arrays.

Example: Load a script using the src

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

Example: Load a script while providing extra script attributes

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

You can optionally provide the script as an array which allows you to provide 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' }
      ]
    }
  }
})

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):

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

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:

# 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 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.
• 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.

For scripts registered through nuxt.config, type autocompletion is available.

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

How it Works

Nuxt uses the globals configuration to create a virtual Nuxt plugin that loads in the script using the useScript() composable.

As Nuxt uses useScript() under the hood, it's important to understand the defaults and behavior of the useScript() composable..

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

<script setup lang="ts">
// This will not trigger the script to be loaded again because of the nuxt.config global script
const { proxy, onLoaded } = useNuxtApp().$scripts.tracker

onLoaded(() => {
  console.log('Script loaded')
})

function trackCustom() {
  proxy.track('custom_event')
}
</script>

<template>
  <button @click="trackCustom">
    Track Custom Event
  </button>
</template>