Nuxt Config

registry

• Type: ScriptRegistry

Configure which scripts to enable. Adding a script to the registry enables infrastructure (proxy routes, types, bundling, composable auto-imports) without auto-loading it. Add trigger to auto-load globally.

export default defineNuxtConfig({
  scripts: {
    registry: {
      // Infrastructure only (composable driven)
      googleAnalytics: { id: 'G-XXXXXX' },
      // Infrastructure + global auto-load
      plausibleAnalytics: { domain: 'mysite.com', trigger: 'onNuxtReady' },
      // Opt out of proxy
      posthog: { apiKey: 'phc_xxx', proxy: false },
      // Testing stub (no script loaded, validation skipped)
      clarity: 'mock',
      // Disable a script
      hotjar: false,
    }
  }
})

Per-script capability flags (trigger, proxy, bundle, partytown, privacy) can be set at the top level of the config object alongside the script's input fields. Setting bundle: false also disables the reverse proxy for that script since URL rewriting depends on the bundled source.

See the Script Registry for more details.

Environment Variables

Registry input fields resolve through Nuxt's runtimeConfig.public mechanism. Define fields under runtimeConfig.public.scripts and override via environment variables:

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      scripts: {
        googleAnalytics: { id: '' }, // NUXT_PUBLIC_SCRIPTS_GOOGLE_ANALYTICS_ID
        posthog: { apiKey: '' }, // NUXT_PUBLIC_SCRIPTS_POSTHOG_API_KEY
        crisp: { id: '' }, // NUXT_PUBLIC_SCRIPTS_CRISP_ID
      }
    }
  }
})

This keeps secrets out of your nuxt.config.ts and allows per-environment overrides.

prefix

• Type: string
• Default: '/_scripts'

Base path prefix for all script endpoints. Proxy endpoints are served at <prefix>/p/** and bundled assets at <prefix>/assets/**.

export default defineNuxtConfig({
  scripts: {
    prefix: '/_tracking', // Custom prefix (default: '/_scripts')
  }
})

privacy

• Type: boolean | ProxyPrivacyInput
• Default: undefined (per-script defaults)

Global privacy override for all proxied scripts. By default, each script uses its own privacy tier declared in the registry. Setting this overrides all per-script defaults.

export default defineNuxtConfig({
  scripts: {
    // Full anonymisation for ALL scripts
    privacy: true,

    // Or selective override per flag
    privacy: { ip: true },

    // Passthrough (still strips sensitive auth headers)
    privacy: false,
  }
})

See the First-Party Mode Guide for details on privacy tiers and per-script overrides.

Per-Script Capabilities

Presence in the registry enables infrastructure (proxy routes, types, bundling, composable auto-imports). Scripts only auto-load globally when trigger is explicitly set. All capability flags (trigger, proxy, bundle, partytown) can be set at the top level of the config object:

export default defineNuxtConfig({
  scripts: {
    registry: {
      // Infrastructure only (composable driven)
      googleAnalytics: { id: 'G-XXXXXX' },
      // Infrastructure + global auto-load
      plausibleAnalytics: { domain: 'mysite.com', trigger: 'onNuxtReady' },
      // Opt out of proxy for this script
      posthog: { apiKey: 'phc_xxx', proxy: false },
      // Per-script privacy override
      metaPixel: { id: '123456', privacy: { ip: true, userAgent: true } },
      // Enable Partytown for this script
      fathomAnalytics: { site: 'XXXXX', partytown: true, trigger: 'onNuxtReady' },
    }
  }
})

Partytown (Web Worker) Experimental

Load individual scripts in a web worker using Partytown. Set partytown: true in the script's options:

export default defineNuxtConfig({
  modules: ['@nuxtjs/partytown', '@nuxt/scripts'],
  scripts: {
    registry: {
      plausibleAnalytics: { domain: 'example.com', partytown: true },
      fathomAnalytics: { site: 'XXXXX', partytown: true },
      umamiAnalytics: { websiteId: 'xxx', partytown: true },
    }
  }
})

Supported Scripts

Scripts with auto-forwarding configured:

• googleAnalytics, plausibleAnalytics, fathomAnalytics, umamiAnalytics, matomoAnalytics, mixpanelAnalytics, segment
• metaPixel, xPixel, tiktokPixel, snapchatPixel, redditPixel, bingUet
• cloudflareWebAnalytics

Limitations

defaultScriptOptions

• Type: NuxtUseScriptOptions
• Default: { trigger: 'onNuxtReady' }

Default options for scripts. See the useScript() documentation for more details.

globals

• Type: Record<string, NuxtUseScriptInput | [NuxtUseScriptInput, NuxtUseScriptOptionsSerializable]>
• Default: {}

Global scripts to load on all pages. This configuration applies to the useScript() composable.

See the Globals documentation for more details.

defaultScriptOptions.warmupStrategy

• Type: false | 'preload' | 'preconnect' | 'dns-prefetch'
• Default: 'preload' for scripts with onNuxtReady or client triggers, false otherwise

Controls how the browser warms up connections to script origins before the script loads:

• 'preload' inserts a <link rel="preload"> tag, downloading the script early. Best for scripts that load soon after page load.
• 'preconnect' establishes an early connection (DNS + TCP + TLS) to the script's origin. Use for scripts loaded later.
• 'dns-prefetch' resolves DNS. Lightest option, useful for scripts that may or may not load.
• false disables warmup entirely. Use when you bundle scripts and serve them from your own domain.

enabled

• Type: boolean
• Default: true

Disables the Nuxt Scripts module.

debug

• Type: boolean
• Default: false

Enable to see debug logs.

assets

• Type: object
• Default: { strategy: 'public' }

Controls how Nuxt bundles scripts for serving.

See the Bundling documentation for more details.

assets.fallbackOnSrcOnBundleFail

• Type: boolean
• Default: false

Fallback to the remote src URL when bundle fails when enabled. By default, the bundling process stops if the third-party script can't be downloaded.

assets.fetchOptions

• Type: object
• Default: { retry: 3, retryDelay: 2000, timeout: 15_000 }

Options to pass to the fetch function when downloading scripts.

assets.cacheMaxAge

• Type: number
• Default: 604800000 (7 days)

Cache duration for bundled scripts in milliseconds. Scripts older than this will be re-downloaded during builds.

assets.integrity

• Type: boolean | 'sha256' | 'sha384' | 'sha512'
• Default: false

Enable automatic Subresource Integrity (SRI) hash generation for bundled scripts. When enabled, calculates a cryptographic hash of each bundled script and injects the integrity attribute along with crossorigin="anonymous".

See the Bundling - Subresource Integrity documentation for more details.